openaq.OpenAQ.locations

OpenAQ.locations(**kwargs)[source]

Provides metadata about distinct measurement locations

Parameters:
  • city (string, array, or tuple) – Limit results by one or more cities. Defaults to None. Can define as a single city (ex. city=’Delhi’), a list of cities (ex. city=[‘Delhi’, ‘Mumbai’]), or as a tuple (ex. city=(‘Delhi’, ‘Mumbai’)).
  • country (string, array, or tuple) – Limit results by one or more countries. Should be a 2-digit ISO country code as a string, a list, or a tuple. See city for details.
  • location (string, array, or tuple) – Limit results by one or more locations.
  • parameter (string, array, or tuple) – Limit results by one or more parameters. Options include [ pm25, pm10, so2, co, no2, o3, bc]
  • has_geo (bool) – Filter items that do or do not have geographic information.
  • coordinates (string) – center point (lat, long) used to get measurements within a certain area. (Ex: coordinates=40.23,34.17)
  • nearest (int) – get the X nearest number of locations to coordinates. Must be used with coordinates. Wins over radius if both are present. Will add the distance property to locations.
  • radius (int) – radius (in meters) used to get measurements. Must be used with coordinates. Default value is 2500.
  • order_by (string or list) – order by one or more fields (ex. order_by=[‘country’, ‘count’]). Default value is ‘location’
  • sort (string) – define the sort order for one or more fields (ex. sort=’desc’)
  • limit (int) – change the number of results returned. Max is 10000. Default is 100.
  • page (int) – paginate through the results.
  • df (bool) – return results as a pandas DataFrame
  • index (string) – if returning as a DataFrame, set index to (‘utc’, ‘local’, None). The default is local
Returns:

a dictionary containing the location, country, city, count, distance, sourceName, sourceNames, firstUpdated, lastUpdated, parameters, and coordinates

Example:
>>> import openaq
>>> api = openaq.OpenAQ()
>>> status, resp = api.locations()
>>> resp['results']
[
    {
        "count": 4242,
        "sourceName": "Australia - New South Wales",
        "firstUpdated": "2015-07-24T11:30:00.000Z",
        "lastUpdated": "2015-07-24T11:30:00.000Z",
        "parameters": [
            "pm25",
            "pm10",
            "so2",
            "co",
            "no2",
            "o3"
        ],
        "country": "AU",
        "city": "Central Coast",
        "location": "wyong"
    },
    ...
]