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]
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.
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"
}
Coming soon...
Rate limiting has not gone into effect as of May 2018.
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!
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
.
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:
eq
: equalsne
: not equalslt
: less thangt
: greater thange
: greater than or equal tole
: less than or equal toin
: inlike
: likeTo 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
.
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
.
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.
$ http -a [api-key]: GET https://tatacenter-airquality.mit.edu/api/v1.0/auth/
HTTP/1.1 200 OK
{
"Authentication Check": "All good!"
}
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 sensorsn
: serial numberurl
: url for the sensorIf 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.
$ 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"
}
],
...
}
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 sensorsn
: serial numberurl
: url for the sensorIf 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.
$ 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"
}
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 pointparameter
: 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 timestamptimestamp_local
: the timestamp in the timezone the device is locatedlast_updated
: the timestamp corresponding to the last time the data point was updatedvalue_1min
: the real-time, 1min data pointvalue_15min
: the 15-min running meanvalue_30min
: the 30-min running meanvalue_60min
: the 60-min running mean$ 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
}
...
]
}
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.
$ 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
}