Authentication

To authorize yourself for the request, you will have to add a HTTP header field Authorization with value basic [your API key here]

Example with curl:

$ curl \
    "https://api.aerostate.io/51.501,0.143/no2,no,o3,co" \
    -H "Authorization: basic [your API key here]" \
    -o aerostate-example.json

Example with Python:

import requests

url =       "https://api.aerostate.io/51.501,0.143/no2,no,o3,co"
headers =   {"Authorization": "basic [your API key here]"}

request =   requests.get(url, headers=headers)

data =      request.content

Example with JavaScript and jQuery:

var data,
    url =       "https://api.aerostate.io/51.501,0.143/no2,no,o3,co",
    headers =   {"Authorization": "basic [your API key here]"};

$.ajax(url, {method: "GET", headers: headers}, function(json) {
    data = json;
});

Or, to set the header for all requests and only use $.getJSON():

$.ajaxSetup({"headers": headers});

List of cities

City codes for future reference in this page.

This list, extended with some additional information, is available as the part of API at the https://api.aerostate.io/cities

«la» — Los Angeles, California,

«nyc» — New York City, New York,

«sf» — San Francisco, California,

«chi» — Chicago, Illinoys,

«dnv» — Denver, Colorado,


«msc» — Moscow, Russia,

«lnd» — London, United Kingdom,

«brc» — Barcelona, Spain,


«global» — the globe-encompassing data.

List of variables

Variable codes for future reference in this page.

"co" — Carbon monoxide, units: ppm;

"no" — Nitrogen monoxide, units: ppm;

"no2" — Nitrogen dioxide, units: ppm;

"o3" — Ozone, units: ppm;


"pm2_5_dry" — Particulate matter 2.5, units: μg/m3;

"pm10" — Particulate matter 10, units: μg/m3;


"aqi" — Air Quality Index, units: dimensionless units in a [0, 500] range (see AQI documentation) and a dominating contaminant.

Data table for single location

https://api.aerostate.io/<lat>,<lng>/<vars>

lat — latitude

lng — longitude

vars — comma-separated list of variables for the retrieval.


Example of the URL: https://api.aerostate.io/51.501364,0.1431914/no2,no,o3,co,aqi

If aqi is in the variable list, with addition of the parameter aqi_texts specified as dangers or all return data will contain not only the values of Air Quality Index, but also behaviour suggestions (i.e. specific dangers or both dangers and advices based on the most dangerous chemical), as specified in AQI documentation.

There is also a version of an endpoint with specified city:

https://api.aerostate.io/<city>/data/<lat>,<lng>/<vars>

Responce

Data is stored in JSONs in table-ish way:

[
    ["",                    "CO",       "NO",       "O3",       "NO2",      "AQI",  "AQI_NAMES"],
    ["2015/11/09 10:00",    0.120730,   0.02998527, 0.00056279, 0.00280771, 43.4,   "O3"],
    ...
]

First line is a table header that specifies type of the table key and variables in the set.

Second line is an actual data row, with the forecast values for the specific variables at the specific time

Data grid for single hour

https://api.aerostate.io/<city>/data/<day>.<month>.<year>/<specs>.json

city — city of the forecast

day, month — day and month in 2-digit notation

year — year in 4-digit notation

specs — precise specifications, currently restricted to hour, minute (ignored in processing) and variable


Example of the URL: https://api.aerostate.io/nyc/data/19.08.2015/1900-co.json

There is also a shorthand link for current global data:

https://api.aerostate.io/global/data/current/current-<variable>.json

Responce

Grid data is stored in JSONs of the following scheme:

[
    {
        "header": {
            "dx":   1.125,
            "dy":   1.125,
            "nx":   320,
            "ny":   160,
            "la1":  89.4375,
            "la2": -89.4375,
            "lo2":  179.4375,
            "lo1": -179.4375,
            "forecastTime": 44,
            "refTime": "2015-11-09T00:00:00.000Z",
            "min":  0.0,
            "max":  500.0
        },
        "data": [
            2.718057155609131,
            2.7067365646362305,
            2.695054769515991,
            2.683300733566284,
            2.6714677810668945
            ...
        ]
    }
]

header fields:

nx, ny — numbers of "rows" and "columns" in grid

dx, dy — longitude and latitude steps

la1, la2 — latitudes of the first and last "rows"

lo1, lo2 — longitude of the first and last "columns"

refTime — time of forecast start

forecastTime — forecast time step of the current data slice (with the resolution of 1 hour)

min, max — minimal and maximal values for the current variable in the last forecast


data array contains flattened rectangular grid of size nx × ny.First element of the array is located at (la1, lo1) coordinates and iteration start longitude-wise, so second element is located at (la1, lo1 + dx).