CityIoT

The CityIoT project collected smart city related data in Tampere about street lights, electric buses and bus passenger analytics. This data is stored in a FIWARE based platform. FIWARE is a collection of standards and components for creating smart solutions. The platform is available at the URL https://tlt-cityiot.rd.tuni.fi/. The data is available via the HTTP-based APIs offered by the platform. To access any of the data sets an API key is required. If you are interested in using any of the CityIoT data sets, contact the person marked as the maintainer of the data set.

In order to get the data and make use of it some understanding is required about the following 3 aspects of the CityIoT platform:

The NGSI v2 specification: defines the API used by the main FIWARE component the Orion context broker and also the entity-based data model used by all FIWARE components.
The Orion context broker: Has the most recent version of the data, i.e. NGSI v2 entities. This data can be queried or subscribed to so that you get notified when the data changes.
QuantumLeap: Stores NGSI v2 entity data into a timeseries database. It allows then the querying of this historic data via an HTTP API.

So in short, understand the NGSI v2 data model so you know what kind of data structures you are dealing with. Use Orion if you want a programmatic way to list all available data entities, query their current state or subscribe to changes in their state. Use QuantumLeap if you want to explore how the entities have changed over time.

The data model

In FIWARE NGSI v2 data is modelled as context entities. Entities can represent logical of physical things such as a sensor, a person or a weather observation. Entities have an id and a type indicating what the entity represents. Entities then can have various attributes providing information about them. The entity type determines what attributes an entity should have. This way domain specific data models can be created by defining the needed entity types and their attributes. For example, weather observation could have attributes for temperature, humidity and the location for the observation. An attribute has a name and a value including data type for the value. An attribute can also have metadata such as timestamp for when the value was acquired or what is the measurement accuracy for the value. The documentation for each CityIoT data set explains what entity types the data consists of and what attributes the entities have.

The entities are represented as JSON. For example, an entity representing an electric bus from one of the CityIoT data sets looks like this with only part of the attributes included:

{
    "id": "Vehicle:TKL16",
    "type": "Vehicle",
    "vehicleType": {
        "value": "bus"
    },
    "name": {
        "value": "TKL16"
    },
    "location": {
        "type": "geo:json",
        "value": {
            "type": "Point",
            "coordinates": [23.769203333333333, 61.49531666666667]
        },
        "metadata": {
            "timestamp": {
                "type": "DateTime",
                "value": "2019-04-03T14:52:18.192881Z"
            }
        }
    },
    "speed": {
        "value": 34.5,
        "metadata": {
            "timestamp": {
                "type": "DateTime",
                "value": "2019-04-03T14:52:19.867419Z"
            }
        }
    },        
    "power": {
        "value": 75.70000000000027,
        "metadata": {
            "timestamp": {
                "type": "DateTime",
                "value": "2019-04-03T14:52:20.218114Z"
            }
        }
    },
    "chargeState": {
        "value": 87,
        "metadata": {
            "timestamp": {
                "type": "DateTime",
                "value": "2019-04-03T14:52:16.938936Z"
            }
        }
    }
}

The Orion context broker

The Orion context broker stores the latest versions of all entities. Its API is used to query information about the entities or subscribe to changes in their attributes. The Tampere CityIoT Orion API is available at the URL https://tlt-cityiot.rd.tuni.fi/orion/

To separate the entities of the different data sets, Orions multi tenancy feature is used. Data is separated into different services and under a service hierarchical service paths can be used for more fine-grained data organization. In API calls the service and service path are given in HTTP headers: Fiware-Service for the service and Fiware-ServicePath for the service path. For access control API keys are used. The API key is given in the apikey HTTP header. Documentation for each data set tells what service is used and how service paths are used. You can get an API key by requesting access to a data set from the maintainer of the data set. As an example, how all this works in practice, the Tampere electric bus pilot data set has entities representing electric buses in service public_transport under the service path /Tampere/electric_bus. Using the command line HTTP client curl, this is how to get all the electric bus entities and their attributes from Orion:

curl -H 'Fiware-Service: public_transport' -H 'Fiware-ServicePath: /Tampere/electric_bus' -H 'apikey: your_apikey' "https://tlt-cityiot.rd.tuni.fi/orion/v2/entities"

QuantumLeap

QuantumLeap stores the change history of the entities in a timeseries database. This can then be queried via its API. The Tampere CityIoT QuantumLeap is available at the URL: https://tlt-cityiot.rd.tuni.fi/quantumleap/

It uses the same service and service path system to organize entities as Orion. The same API key-based authentication system is also used. See the Orion section for more details. For example to Get all values for power and speed for electric bus entity TKL15 between 14:01 and 14:02 on 28th of October 2019 with curl the following command would be used:

curl -H 'Fiware-Service: public_transport' -H 'Fiware-ServicePath: /Tampere/electric_bus' -H 'apikey: your_apikey' "https://tlt-cityiot.rd.tuni.fi/quantumleap/v2/entities/Vehicle:TKL15?attrs=speed,power&&fromDate=2019-10-28T12:01:00&&toDate=2019-10-28T12:02:00"