Overview

Readers' guide

This document will allow you to access real time air quality data and metadata about air quality data sources via the Ido API.
The document is divided in the following sections:

  • The Resources section will explain in detail the characteristics of the resources that can be manipulated by using the API.
  • The Authentication section will explain how to obtain the credentials necessary to interact with the Ido API.
  • A list of all the endpoints.

Resources

The resources that can be accessed or manipulated using the API are:

Sensor

A device that records physical parameters. Each sensor is located in a point in space, identified by its latitude and longitude, and may contain information about the administrative entities that govern the point in space where the Sensor is located (e.g. the country, the city etc.).
Sensors have hardware of different types, and may have firmware of different types as well. Sensors can also have a human-readable name, selected by their owners and that can be used to display them.

Observation

A set of physical parameters, recorded by a Sensor in a specific instant in time. Each physical parameter describes one dimension of the physical environment around the Sensor in the specific instant in time of the Observation. Physical parameters contained in Observations are inaccurate, because they contain the values exactly as they are recorded by Sensors: it is necessary to process Observations to obtain faithful representations of the environment. Therefore, they should be used as inputs for data processing algorithms, or for fault detection and maintenance purposes.

Measure

A set of physical parameters, each of which does accurately describe one dimension of the physical environment in a given location and instant in time. Each Measure is the accurate version of one Observation, because it is obtained by processing the Observation itself. Therefore, the Measure contains the same parameters as the Observation (e.g., if the Observation contains the concentration of PM2.5, the corresponding Measure will contain the concentration of PM2.5 as well).

Prediction

A set of physical parameters, each of which contains the average of one dimension of the physical environment in a given location, during an interval in time. Predictions are necessary because legal limits and epidemiologic studies about the concentrations of air quality pollutants refer to averages in time, not to pointwise concentrations; as a consequence, Measures cannot immediatly provide insights about the consequences of air pollution.

it is possible to access Predictions refered to time intervals of different length, for example predictions that express the average over a day, or a month.

User

A physical or legal person who owns one or more Sensor, or who can access Wiseair data. Users can access the Predictions produced by a set of sensors.

Authentication

Authentication is managed using at the same time an API Key and OAuth2 access tokens. Therefore, the workflow to call the API is the following:

Obtain an App Client ID, an App Client Secret, an API Key

Contact us at [email protected]. Describe clearly what data do you need access to, and why; we will provide you with the App Client ID, the App Client Secret, the API Key.

Define the Scopes you need

Make a list of all the API endpoints you will send requests to, each one with the type of HTTP request that you will perform.
Each endpoint has the format https://apiv1.ido.wiseair-api.com/{RESOURCE}[/other-parts-of-url[/possibly-on-multiple-levels]], and receives an HTTP request of type GET or with other types.
The scope necessary to interact with an endpoint is https://apiv1.ido.wiseair-api.com/RESOURCE.read if the endpoint is accessed via a GET request, and https://apiv1.ido.wiseair-api.com/RESOURCE.write if the request has any other type.
For example:

Use the App Client ID, the App Client Secret to obtain an access token

Concatenate all the scopes, separating them with spaces, obtaining a SCOPE_STRING
Perform the following requests, replacing YOUR_APP_CLIENT_ID, YOUR_APP_CLIENT_SECRET with the values of your app client id and app client secret.

curl --request POST 'https://ido-api.auth.eu-central-1.amazoncognito.com/token'
--header 'Content-Type: application/x-www-form-urlencoded'
--data-urlencode 'grant_type=client_credentials'
--data-urlencode 'scope=SCOPE_STRING'
--data-urlencode 'client_id=YOUR_APP_CLIENT_ID'
--data-urlencode 'client_secret=YOUR_APP_CLIENT_SECRET'

The response will be similar to
{"access_token":"TOKEN","expires_in":3600,"token_type":"Bearer"}

Extract the TOKEN string, it will be necessary in the final step

Use the access token and the API Key to authenticate your requests

Attach a header "Authorization" with value "Bearer " to your requests.
Attach a header "x-api-key" with value "".
Refer to https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html for troubleshooting.