Our API handbook

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 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;

«so2» — Sulfur dioxide, units: ppm;

«aqi» — Air Quality Index, units: dimensionless units in a [0, 500] range (see AQI documentation) and a dominating contaminant «aqi_names» from the list above;

«aqi_texts=dangers|all» — Recomendations based on AQI:

— «all» — all recomendations,

— «danger» — only for dangerous level.

Time zones

By default you will get response with local hour for selected location. If you want to use GMT, please use «?timezone=utc»

For example:

https://api.aerostate.io/<lat>,<lon>/no2,no,o3,co,s02,pm2_5_dry,pm10,aqi?timezone=utc

Data table for single location

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

«lat» — latitude;

«lon» — 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.

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 (contact us for the list of available cities);

«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/19:00-co.json

This request is for the grid data for New York city, date 19 August 2015, time 19:00 GMT, variable «CO». Data is available for current date and several days before.

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»).