Getting Started and Installation

py-openaq aims to provide easy access to the OpenAQ API via a Python platform. To read more about OpenAQ, check out their website.


You can install the package directly via pypi through pip:

>>> pip install py-openaq

You can also install the most up-to-date development version directly from github using:

>>> pip install git+



Current Limitations

As of now, the only feature that is not built into the API wrapper is returning various formats from the openaq.OpenAQ.measurements call. This is because I don’t see any reason to use python to return a csv. If a csv is your desired output, I recommend using pandas’ DataFrame.to_csv() method.


The following code example shows how to make your first API call:

import openaq

api = openaq.OpenAQ()

status, resp = api.cities()

Understanding the Response format

Each API call will reply with a tuple containing the status code and the response in json format. The three most common API status codes you will see are:

  • 200: Success
  • 40x: Error: Bad Request
  • 500: Server Error

The json response will look something like the following with both meta and results:

'meta': {'license': 'CC By 4.0', 'name': 'openaq-api', 'website': ''},
'results': [
    {'city': 'Amsterdam', 'count': 71125, 'country': 'NL', 'locations': 14},
    {'city': 'Antofagasta', 'count': 3416, 'country': 'CL', 'locations': 1},
    {'city': 'Arica', 'count': 1682, 'country': 'CL', 'locations': 1},
    {'city': 'Ayutthaya', 'count': 3880, 'country': 'TH', 'locations': 1},
    {'city': 'Badhoevedorp', 'count': 7862, 'country': 'NL', 'locations': 1},

Coupling with Pandas DataFrame

Pandas is awesome. If you are working with data, you should be using DataFrames. To easily dump your json response into a DataFrame:

from import json_normalize

df = json_normalize(resp)

As of v0.3.0, an optional keyword argument (df) has been added to the following API methods:

  • cities
  • countries
  • latest
  • locations
  • measurements

By using this keyword argument, the results of the API call will return a pandas DataFrame rather than a json response.


>>> df = api.latest(df=True)

The results are parsed through the pandasize decorator which tries to interpret the fields in the most ideal format possible. Thus, all datetime fields should be converted to proper python datetimes to allow for easy splicing, manipulation, and plotting.


Testing is automated using unittests. To run the unittests with coverage reporting, run the following command from the main directory:

>>> coverage run --source openaq test

You can then view the coverage report with:

>>> coverage report -m

Bugs and Issues

Please report any bugs or issues you find through the GitHub issues tracker. Please provide as much information as possible that will make it easier to solve/fix the problem.