Countries

The Countries resource provides details about countries and territories (henceforth referred to as countries for short) in the OpenAQ dataset and includes only those with monitoring locations from which OpenAQ ingests data. You can use it to get a country’s air quality data information, such as the time of its first and most recent measurement on OpenAQ, or the parameters that are being measured in the country.

Country value for each location comes from the location’s coordinates provided by the upstream provider. OpenAQ uses the Natural Earth 10m dataset for country boundaries. Country codes follow the ISO 3166-1 alpha-2 standard, which may differ from codes reported by the upstream provider.

Methods

The Countries resource provides the following methods:

• get() - For accessing a single country by country ID.
• list() - For accessing multiple countries.

Get a single country

The get() method accepts one single countries_id as an argument and returns details about that country in a CountriesResponse object.

get(
  countries_id: int
  ) -> CountriesResponse

Query arguments

argument	description	input requirements
countries_id	int OpenAQ’s unique ID for each country	Required

Example

from openaq import OpenAQ

# Retrieve information about Indonesia (ID=1) on OpenAQ
with OpenAQ(api_key="replace-me-with-a-valid-key") as client:
    client.countries.get(countries_id=1)

Caution

This example uses a placeholder API key `replace-me-with-a-valid-key` and will not work as-is. Replace this value with a valid OpenAQ API key.

List multiple countries

The list() method takes optional arguments and returns countries on the OpenAQ platform that meet all the conditions specified in a CountriesResponse object. If no argument is included, the method returns all countries using the default arguments.

list(
  page: int = 1,
  limit: int = 1000,
  order_by: str | None = None,
  sort_order: SortOrder | None = None,
  parameters_id: int | list[int] | None = None,
  providers_id: int | list[int] | None = None
  ) -> CountriesResponse

Query arguments

argument	description	input requirements
page	int The page number to retrieve, defaults to 1	Must be greater than zero
limit	int The number of results returned per page, defaults to 1,000	Must be between 1 and 1,000
order_by	str | None The country field by which to sort results, defaults to id. Currently only id is supported
sort_order	SortOrder | None The sort direction for the order_by field, defaults to desc	Must be one of: asc, desc, ASC, DESC
parameters_id	int | list[int] | None Filter by a pollutant or meteorological parameter	Must be OpenAQ unique ID for the pollutant or meteorlogical parameter
providers_id	int | list[int] | None Filter by the ID of the data provider	Must be OpenAQ unique ID for the provider that facilitates data sharing

Example

from openaq import OpenAQ

# List countries where there is a PM2.5 reading and where AirGradient is present
# as a data provider
with OpenAQ(api_key="your-api-key") as client:
    client.countries.list(parameters_id=2,
                          providers_id=66)

Response objects

The Country objects in the results of the CountriesResponse contain attributes that have all data about them. The hierarchy below presents the depth of the attributes and their datatypes.

results[]
    ├── id: int
    ├── code: str
    ├── name: str
    ├── datetime_first:
    │   ├── utc: str
    │   └── local: str
    ├── datetime_last:
    │   ├── utc: str
    │   └── local: str
    └── parameters: []
        ├── id: int
        ├── name: str
        ├── units: str
        └── display_name: str | None

Was this page helpful?

Thank you for your feedback