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+https://github.com/dhhagan/py-openaq.git
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()
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': 'https://docs.openaq.org/'},
'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},
...
]
}
Pandas is awesome. If you are working with data, you should be using DataFrames. To easily dump your json response into a DataFrame:
from pandas.io.json 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.
Example:
>>> 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 setup.py test
You can then view the coverage report with:
>>> coverage report -m
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.