Providers

The Providers resource provides details about the entities that supply air quality data to OpenAQ platform. Providers may be governmental agencies, research organizations, or private companies. The data “provider” may be the same as the data “owner” (see Owners) and/or the monitoring instrument “manufacturer” (see Manufacturers), but their IDs across the three resources are independent of each other. For example, AirGradient has a providers_id=66, a owners_id=12, and a manufacturers_id=12.

Methods

The Providers resource provides the following methods:

• get() - For accessing a single provider by provider ID.
• list() - For accessing multiple providers.

Get a single provider

The get() method accepts one single providers_id as an argument and returns details about that provider in a ProvidersResponse object.

get(
  providers_id: int
  ) -> ProvidersResponse

Query arguments

argument	description	input requirements
providers_id	int OpenAQ’s unique ID for each provider	Required

Example

from openaq import OpenAQ

# Retrieve the provider with ID 66
with OpenAQ(api_key="replace-me-with-a-valid-key") as client:
    client.providers.get(providers_id=66)

Caution

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

List multiple providers

The list() method takes optional arguments and returns providers on the OpenAQ platform that meet all the conditions specified in a ProvidersResponse object. If no argument is included, the method returns all providers 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,
  monitor: bool | None = None,
  coordinates: tuple[float, float] | None = None,
  radius: int | None = None,
  bbox: tuple[float, float, float, float] | None = None,
  iso: str | None = None,
  countries_id: int | list[int] | None = None
  ) -> ProvidersResponse

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 providers field by which to sort results, defaults to id. Currently only id is supported
sort_order	str | 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
monitor	bool | None Filter for reference-grade monitors (True) or air sensor (False) locations
coordinates	tuple[float, float] | None The geographic position of a point from which to search for providers	Must be in WGS84 (EPSG:4326) in (latitude, longitude) or (Y, X) format and accompanied by radius. Cannot be used at the same time as bbox
radius	int | None How far (in meters) to search for providers around the coordinate pair	Must be between 1 and 25,000. Must be accompanied by coordinates argument. Cannot be used at the same time as bbox
bbox	tuple[float, float, float, float] | None The rectangular area within which providers are searched for and returned	Must be in WGS84 (EPSG:4326) and (minX, minY, maxX, maxY) format with maximum 4 decimals precision. Cannot be used at the same time as coordinates or radius
iso	str | None The ISO 3166-1 alpha-2 code for the country or territory where the provider operates	Must be a valid ISO 3166-1 alpha-2 code representation of the country. Cannot be used at the same time as countries_id
countries_id	int | list[int] | None Filter by the country or territory where the provider operates	Must be OpenAQ unique ID for the country or territory. Cannot be used at the same time as iso

Example

from openaq import OpenAQ

# List all providers on OpenAQ
with OpenAQ(api_key="your-api-key") as client:
    client.providers.list()

Response object

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

results[]
    ├── id: int
    ├── name: str
    ├── source_name: str
    ├── export_prefix: str
    ├── datetime_added: str
    ├── datetime_first: str
    ├── datetime_last: str
    ├── entities_id: int
    ├── bbox: Bbox()
    │   ├── type: str
    │   └── coordinates: array[]
    └── parameters: []
        ├── id: int
        ├── name: str
        ├── units: str
        └── display_name: str | None