Tata Center Air Quality

API v1 Introduction

Welcome to the Tata Center Air Quality API documentation.

The Tata Center API allows you to retrieve data from our expanding network of air quality monitoring stations in a simple, programmatic way using conventional HTTP requests. The endpoints are intuitive, allowing you to easily make calls to retrieve information and turn data into actionable insights.

The API documentation begins with a brief overview of the technology and design of the API, followed by reference information for each endpoint.

Throughout this documentation, examples will be shown using the tool httpie, a great command line HTTP client that will help get your data! Example code will appear as follows:

$ http -a [username]:[password] GET https://tatacenter-airquality.mit.edu/api/v1.0/auth/

Each url is built using the following format:

$ https://tatacenter-airquality.mit.edu/api/[api version]/[endpoint]

The current API version is v1.0. Thus, each unique URL you build will begin with:

$ https://tatacenter-airquality.mit.edu/api/v1.0/[endpoint]

Requests

Any tool that is fluent in HTTP can easily communicate with the API with the correct URI. Requests must be made using HTTPS protocol to ensure the traffic is encrypted. The response varies depending on the action required.

Method	Usage
GET	For simple retrieval of an object or data, you will use a GET object. It returns a simple JSON object. The JSON object can then be used to form additonal requests. Any request made with GET is read-only and will not affect the objects you are querying.
DELETE	To destroy a resource and remove it, the DELETE method should be used. This will destroy the specified object if it is found. If the resource is not found, the return will indicate so. DELETE requests are idempotent, which means you do not need to check for its existence prior to issuing the DELETE request.
PUT	To update a resource, the PUT method should be used. Like the DELETE request, the PUT request is idempotent, so checking for current attributes is not required.
POST	To create a new object, the POST method should be used. The POST request includes all of the attributes needed to create a new object.
HEAD	To retrieve metadata information, issue the HEAD method to get the headers. Response headers contain some useful information about your API access and the results that are available to you.

For more information on HTTP requests, check out this tutorial. As of August 2017, only GET requests are allowed by users.

HTTP Status Codes

Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes when necessary.

If there is an issue with the request, an error will be returned as indicated both by the HTTP status code and the response body. In general, if the status code is in the 200's, the request was successful. If the status code is in the 400's, there was an error with the request. This could range from improper authentication to an illegal operation (you were trying to request data you do not have permissions to view!).

If a 500 error is returned, there was a server-side error which means we were not able to process the request for some reason.

An example error response:

HTTP/1.1 403 Forbidden

{
    "id": "forbidden",
    "message": "You do not have access for the attempted action"
}

Responses

Coming soon...

API Rate Limiting

Rate limiting has not gone into effect as of May 2018.

API Keys

In order to interact with the Tata AQ API, you must first authenticate. The API handles this by issuing each user a unique API key that is registered to your account. This allows us to ensure each user is only accessing public data and is correctly limited.

You can generate an API key by going to the API section and clicking on the Generate New Token button. Each token acts as a complete username:password combination and handles the entire authentication request. Please keep this secure!

Parameters and Advanced API Queries

Advanced querying options can be used to reduce the number of data points or other resources returned at any point. Most API methods in place with the Tata AQ API are able to use these techniques. The three primary tools are filter, limit, and sort.

Filtering Queries

To filter a query, use the filter keyword argument with the format filter=parameter,filter-spec,value. Multiple filter arguments can be separated by a semicolon (e.g. filter=city,eq,Delhi;parameter,eq,pm25). The filter-spec's that can be used are:

Limiting Queries

To limit the number of responses in a query for API endpoints that are paginated, you can use the per_page and page keywords. For example, to grab only 5 of an object you would use per_page=5.

Sorting Queries

To sort a query, simply use the sort keyword argument with the format sort=parameter,[asc,desc]. For example, to sort ascending based on the column last_updated, you would send the keyword argument sort=last_updated,asc.

auth/

Available methods: [ GET ]

The authentication endpoint will return the status of the authentication credentials you provided. If your credentials are good, a 200 response will be returned. If they fail, a 401 response will be returned. If you are trying to access a URI for which you do not have permission, a 403 response will be returned.

Sample Response

$ http -a [api-key]: GET https://tatacenter-airquality.mit.edu/api/v1.0/auth/

HTTP/1.1 200 OK

{
    "Authentication Check": "All good!"
}

device/

Available methods: [ GET, POST ]

The device/ endpoint allows you to add a new device (POST) or retrieve information about existing devices (GET). Data can be filtered or sorted using the methods described above in the 'Advanced API Queries section'. Adding new devices is limited to administrators at this point in time.

Results are paginated and you are only able to receive information about devices that are either public or are within your permissions. If successful, a 200 response will be returned along with the data.

The response data includes the following:

city: the city where the sensor is located (string)
country: the country where the sensor is located (ISO country code)
last_updated: the timestamp corresponding to when the sensor was last updated. This should correspond to the timezone listed below with a default of UTC.
latitude: latitude of last known location (string)
longitude: longitude of last known location (string)
location: description of the location (string)
model: model type of the sensor (string)
outdoors: true if the sensor is outdoors (boolean)
timezone: timezone of the sensor
sn: serial number
url: url for the sensor

If working with sensor data, the most important columns will be the serial number (sn) and the url (url). Details on the POST method are forthcoming.

Sample Response

$ http -a [api-key]: GET https://tatacenter-airquality.mit.edu/api/v1.0/device/

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 779
Content-Type: application/json
Date: Wed, 16 May 2018 00:57:21 GMT
Etag: "50286961588c97c8c8b9e73b1ab71500"
Server: nginx/1.10.3 (Ubuntu)

{
    "meta": {
        "first_url": "https://tatacenter-airquality.mit.edu/api/v1.0/device/?page=1&per_page=1&expand=1",
        "last_url": "https://tatacenter-airquality.mit.edu/api/v1.0/device/?page=4&per_page=1&expand=1",
        "next_url": "https://tatacenter-airquality.mit.edu/api/v1.0/device/?page=2&per_page=1&expand=1",
        "page": 1,

        "pages": 4,
        "per_page": 1,
        "prev_page": null,
        "total": 4
        },
    "data": [
        {
            "city": "Delhi",
            "country": "IN",
            "last_updated": "2017-11-02T22:34:01",
            "latitude": "35",
            "location": "",
            "longitude": "53",
            "model": "2BTech Model 202",
            "outdoors": true,
            "sn": "OZONE001",
            "timezone": "Asia/Kolkata",
            "url": "https://tatacenter-airquality.mit.edu/api/v1.0/device/OZONE001"
        }
    ],
    ...
}

device/[serial-number]

Available methods: [ GET, PUT, DELETE ]

The device/[serial-number] endpoint allows you to edit a device (PUT), delete a device (DELETE) or retrieve information about an existing device (GET). Data can be filtered or sorted using the methods described above in the 'Advanced API Queries section'. Editing a device is only available if you are the rightful owner (and have the necessary permissions). Deleting devices can only be performed by the benevolent dictator.

Users can only receive information about devices that are either public or are within your permissions. If successful, a 200 response will be returned along with the data.

The response data includes the following:

city: the city where the sensor is located (string)
country: the country where the sensor is located (ISO country code)
last_updated: the timestamp corresponding to when the sensor was last updated. This should correspond to the timezone listed below with a default of UTC.
latitude: latitude of last known location (string)
longitude: longitude of last known location (string)
location: description of the location (string)
model: model type of the sensor (string)
outdoors: true if the sensor is outdoors (boolean)
timezone: timezone of the sensor
sn: serial number
url: url for the sensor

If working with sensor data, the most important columns will be the serial number (sn) and the url (url). Details on the POST method are forthcoming.

Sample Response

$ http -a [api-key]: GET https://tatacenter-airquality.mit.edu/api/v1.0/device/OZONE001

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 331
Content-Type: application/json
Date: Wed, 16 May 2018 01:49:21 GMT
Etag: "5de9d27a6a21e58413a8d1e3411bffd0"
Server: nginx/1.10.3 (Ubuntu)

{
    "city": "Delhi",
    "country": "IN",
    "last_updated": "2017-11-02T22:34:01",
    "latitude": "35",
    "location": "",
    "longitude": "53",
    "model": "2BTech Model 202",
    "outdoors": true,
    "sn": "OZONE001",
    "timezone": "Asia/Kolkata",
    "url": "https://tatacenter-airquality.mit.edu/api/v1.0/device/OZONE001"
}

device/[sn]/data/

Available methods: [ GET ]

The device/[serial-number]/data/ endpoint allows you to retrieve data for an existing device (GET) from a sanitized/cleaned table. Data can be filtered or sorted using the methods described above in the 'Advanced API Queries section'.

Users can only receive information about devices that are either public or are within their scope of permissions. If successful, a 200 response will be returned along with the data.

The response data will include two groups of information: meta and data. meta contains the meta information for paginating the data including the number of items per page, current page number, and total number of results in the query.

The data section will include the paginated data and includes the following:

id: the id of the datapoint which can be used to retrieve the exact point
parameter: the parameter corresponding to the data point - one of [so2, o3, no2, no, co, pm1, pm25, pm10]
unit: the unit of measure for the corresponding data point - one of [ppm, ppb, ugm3]
timestamp: the UTC timestamp
timestamp_local: the timestamp in the timezone the device is located
last_updated: the timestamp corresponding to the last time the data point was updated
value_1min: the real-time, 1min data point
value_15min: the 15-min running mean
value_30min: the 30-min running mean
value_60min: the 60-min running mean

Sample Response

$ http -a [api-key]: GET https://tatacenter-airquality.mit.edu/api/v1.0/device/OZONE001/data/

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 772
Content-Type: application/json
Date: Wed, 16 May 2018 02:09:25 GMT
Etag: "f477b7dc34e5c631c9ca1a9fa136bd47"
Server: nginx/1.10.3 (Ubuntu)

{
    "meta": {
        "first_url": "https://tatacenter-airquality.mit.edu/api/v1.0/device/OZONE001/data/?page=1&per_page=2&expand=1",
        "last_url": "https://tatacenter-airquality.mit.edu/api/v1.0/device/OZONE001/data/?page=25650&per_page=2&expand=1",
        "next_url": "https://tatacenter-airquality.mit.edu/api/v1.0/device/OZONE001/data/?page=2&per_page=2&expand=1",
        "page": 1,
        "pages": 25650,
        "per_page": 2,
        "prev_page": null,
        "total": 51300
    },
    "data": [
      {
        "id": 50301,
        "timestamp": "2018-05-18T13:25:43",
        "timestamp_local": "2018-05-18T18:55:43+05:30",
        "last_updated": "2018-05-18T18:55:43",
        "parameter": 'so2',
        'sn'; "TREX001",
        "unit": "ppbv",
        "value_1min": 88.01,
        "value_15min": 85.51,
        "value_30min": 80.32,
        "value_60min": 76.32
      }
      ...
    ]
}

device/[sn]/latest

Available methods: [ GET ]

The device/[serial-number]/latest endpoint returns the most recent datapoint for a given sensor. If there is no data, the response will be empty, but an error will not be thrown. The data returned will be the same as that provided in the normal, paginated data list as documented directly above.

Users can only receive information about devices that are either public or are within your scope of permissions. If successful, a 200 response will be returned along with the data.

Sample Response

$ http -a [api-key]: GET https://tatacenter-airquality.mit.edu/api/v1.0/device/OZONE001/latest

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 772
Content-Type: application/json
Date: Wed, 16 May 2018 02:09:25 GMT
Etag: "f477b7dc34e5c631c9ca1a9fa136bd47"
Server: nginx/1.10.3 (Ubuntu)

{
  "id": 50301,
  "timestamp": "2018-05-18T13:25:43",
  "timestamp_local": "2018-05-18T18:55:43+05:30",
  "last_updated": "2018-05-18T18:55:43",
  "parameter": 'so2',
  'sn'; "TREX001",
  "unit": "ppbv",
  "value_1min": 88.01,
  "value_15min": 85.51,
  "value_30min": 80.32,
  "value_60min": 76.32
}

API v1 Introduction

Requests

HTTP Status Codes

Responses

API Rate Limiting

API Keys

Parameters and Advanced API Queries

Filtering Queries

Limiting Queries

Sorting Queries

Endpoints

auth/

Sample Response

device/

Sample Response

device/[serial-number]

Sample Response

device/[sn]/data/

Sample Response

device/[sn]/latest

Sample Response