Skip to content

OpenAQ

OpenAQ

OpenAQ syncronous client.

Parameters:

Name Type Description Default
api_key Union[str, None]

The API key for accessing the service.

 None
user_agent str

The user agent string to be used in requests.

 DEFAULT_USER_AGENT
headers Mapping[str, str]

Additional headers to be sent with the request.

 {}
base_url str

The base URL for the API endpoint.

 'https://api.openaq.org/v3/'
Note

Although the api_key parameter is not required for instantiating the OpenAQ client, an API Key is required for using the OpenAQ API.

Raises:

Type Description
AuthError

Authentication error, improperly supplied credentials.
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/client.py 
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
class OpenAQ(BaseClient):
    """OpenAQ syncronous client.

    Args:
        api_key: The API key for accessing the service.
        user_agent: The user agent string to be used in requests.
        headers: Additional headers to be sent with the request.
        base_url: The base URL for the API endpoint.

    Note:
        Although the `api_key` parameter is not required for instantiating the
        OpenAQ client, an API Key is required for using the OpenAQ API.

    Raises:
        AuthError: Authentication error, improperly supplied credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.

    """

    def __init__(
        self,
        api_key: Union[str, None] = None,
        user_agent: str = DEFAULT_USER_AGENT,
        headers: Mapping[str, str] = {},
        base_url: str = "https://api.openaq.org/v3/",
        _transport: Transport = Transport(),
    ) -> OpenAQ:
        super().__init__(_transport, headers, base_url)
        if headers:
            self._headers.update(headers)
        self._headers = resolve_headers(
            self._headers,
            api_key=api_key,
            user_agent=user_agent,
        )

        self.locations = Locations(self)
        self.providers = Providers(self)
        self.parameters = Parameters(self)
        self.countries = Countries(self)
        self.instruments = Instruments(self)
        self.manufacturers = Manufacturers(self)
        self.measurements = Measurements(self)
        self.owners = Owners(self)

    @property
    def transport(self) -> Transport:
        return self._transport

    def _do(
        self,
        method: str,
        path: str,
        *,
        params: Union[Mapping[str, Any], None] = None,
        headers: Union[Mapping[str, str], None] = None,
    ):
        if headers:
            request_headers = self._headers.copy()
            request_headers.update(headers)
        else:
            request_headers = self._headers
        try:
            url = self._base_url + path
            data = self.transport.send_request(
                method=method, url=url, params=params, headers=request_headers
            )
            return data
        except Exception as e:
            raise e

    def _get(
        self,
        path: str,
        *,
        params: Union[Mapping[str, str], None] = None,
        headers: Union[Mapping[str, Any], None] = None,
    ):
        return self._do("get", path, params=params, headers=headers)

    def close(self):
        self._transport.close()

    def __enter__(self) -> OpenAQ:
        return self

    def __exit__(self, *_: Any):
        self.close()

Locations

This provides methods to retrieve air monitor locations resource from the OpenAQ API.

Source code in openaq/_sync/models/locations.py 
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
class Locations(SyncResourceBase):
    """This provides methods to retrieve air monitor locations resource from the OpenAQ API."""

    def get(self, locations_id: int) -> LocationsResponse:
        """Retrieve a specific location by its locations ID.

        Args:
            locations_id: The locations ID of the location to retrieve.

        Returns:
            LocationsResponse: An instance representing the retrieved location.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        location = self._client._get(f"/locations/{locations_id}")
        return LocationsResponse.load(location.json())

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        radius: Union[int, None] = None,
        coordinates: Union[Tuple[float, float], None] = None,
        bbox: Union[Tuple[float, float, float, float], None] = None,
        providers_id: Union[int, List[int], None] = None,
        countries_id: Union[int, List[int], None] = None,
        parameters_id: Union[int, List[int], None] = None,
        iso: Union[str, None] = None,
        monitor: Union[bool, None] = None,
        mobile: Union[bool, None] = None,
        order_by: Union[str, None] = None,
        sort_order: Union[str, None] = None,
    ) -> LocationsResponse:
        """List locations based on provided filters.

        Provides the ability to filter the locations resource by the given arguments.

        * `page` - Specifies the page number of results to retrieve
        * `limit` - Sets the number of results generated per page
        * `radius` - Specifies the distance around a central point, filtering locations within a circular area. Must be used with `coordinates`, cannot be used in combination with `bbox`
        * `coordinates` - Filters locations by coordinates. Must be used with `radius`, cannot be used in combination with `bbox`
        * `bbox` - Filters locations using a bounding box. Cannot be used with `coordinates` or `radius`
        * `providers_id` - Filters results by selected providers ID(s)
        * `countries_id` - Filters results by selected countries ID(s)
        * `parameters_id` - Filters results by selected parameters ID(s)
        * `iso` - Filters results by selected country code
        * `monitor` - Filters results by reference grade monitors (`true`), air sensors (`false`), or both if not used
        * `mobile` - Filters results for mobile sensors (`true`), non-mobile sensors (`false`), or both if not used
        * `order_by` - Determines the fields by which results are sorted; available values are `id`
        * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

        Args:
            page: The page number. Page count is locations found / limit.
            limit: The number of results returned per page.
            radius: A distance value in meters to search around the given coordinates value.
            coordinates: WGS 84 coordinate pair in form latitude, longitude (y,x).
            bbox: Geospatial bounding box of min X, min Y, max X, max Y in WGS 84 coordinates. Limited to four decimals precision.
            providers_id: Single providers ID or an array of IDs.
            countries_id: Single countries ID or an array of IDs.
            parameters_id: Single parameters ID or an array of IDs.
            iso:  2 letter ISO 3166-alpha-2 country code.
            monitor: Boolean for reference grade monitors (true) or air sensors (false)
            mobile: Boolean mobile locations (true) or not mobile locations (false).
            order_by: Order by operators for results.
            sort_order: Sort order (asc/desc).

        Returns:
            LocationsResponse: An instance representing the list of retrieved locations.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        params = build_query_params(
            page=page,
            limit=limit,
            radius=radius,
            coordinates=coordinates,
            bbox=bbox,
            providers_id=providers_id,
            countries_id=countries_id,
            parameters_id=parameters_id,
            iso=iso,
            monitor=monitor,
            mobile=mobile,
            order_by=order_by,
            sort_order=sort_order,
        )

        locations = self._client._get("/locations", params=params)
        return LocationsResponse.load(locations.json())

get(locations_id)

Retrieve a specific location by its locations ID.

Parameters:

Name Type Description Default
locations_id int

The locations ID of the location to retrieve.

 required

Returns:

Name Type Description
LocationsResponse LocationsResponse

An instance representing the retrieved location.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/locations.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def get(self, locations_id: int) -> LocationsResponse:
    """Retrieve a specific location by its locations ID.

    Args:
        locations_id: The locations ID of the location to retrieve.

    Returns:
        LocationsResponse: An instance representing the retrieved location.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    location = self._client._get(f"/locations/{locations_id}")
    return LocationsResponse.load(location.json())

list(page=1, limit=1000, radius=None, coordinates=None, bbox=None, providers_id=None, countries_id=None, parameters_id=None, iso=None, monitor=None, mobile=None, order_by=None, sort_order=None)

List locations based on provided filters.

Provides the ability to filter the locations resource by the given arguments.

  • page - Specifies the page number of results to retrieve
  • limit - Sets the number of results generated per page
  • radius - Specifies the distance around a central point, filtering locations within a circular area. Must be used with coordinates, cannot be used in combination with bbox
  • coordinates - Filters locations by coordinates. Must be used with radius, cannot be used in combination with bbox
  • bbox - Filters locations using a bounding box. Cannot be used with coordinates or radius
  • providers_id - Filters results by selected providers ID(s)
  • countries_id - Filters results by selected countries ID(s)
  • parameters_id - Filters results by selected parameters ID(s)
  • iso - Filters results by selected country code
  • monitor - Filters results by reference grade monitors (true), air sensors (false), or both if not used
  • mobile - Filters results for mobile sensors (true), non-mobile sensors (false), or both if not used
  • order_by - Determines the fields by which results are sorted; available values are id
  • sort_order - Works in tandem with order_by to specify the direction: either asc (ascending) or desc (descending)

Parameters:

Name Type Description Default
page int

The page number. Page count is locations found / limit.

 1
limit int

The number of results returned per page.

 1000
radius Union[int, None]

A distance value in meters to search around the given coordinates value.

 None
coordinates Union[Tuple[float, float], None]

WGS 84 coordinate pair in form latitude, longitude (y,x).

 None
bbox Union[Tuple[float, float, float, float], None]

Geospatial bounding box of min X, min Y, max X, max Y in WGS 84 coordinates. Limited to four decimals precision.

 None
providers_id Union[int, List[int], None]

Single providers ID or an array of IDs.

 None
countries_id Union[int, List[int], None]

Single countries ID or an array of IDs.

 None
parameters_id Union[int, List[int], None]

Single parameters ID or an array of IDs.

 None
iso Union[str, None]

2 letter ISO 3166-alpha-2 country code.

 None
monitor Union[bool, None]

Boolean for reference grade monitors (true) or air sensors (false)

 None
mobile Union[bool, None]

Boolean mobile locations (true) or not mobile locations (false).

 None
order_by Union[str, None]

Order by operators for results.

 None
sort_order Union[str, None]

Sort order (asc/desc).

 None

Returns:

Name Type Description
LocationsResponse LocationsResponse

An instance representing the list of retrieved locations.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/locations.py 
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    radius: Union[int, None] = None,
    coordinates: Union[Tuple[float, float], None] = None,
    bbox: Union[Tuple[float, float, float, float], None] = None,
    providers_id: Union[int, List[int], None] = None,
    countries_id: Union[int, List[int], None] = None,
    parameters_id: Union[int, List[int], None] = None,
    iso: Union[str, None] = None,
    monitor: Union[bool, None] = None,
    mobile: Union[bool, None] = None,
    order_by: Union[str, None] = None,
    sort_order: Union[str, None] = None,
) -> LocationsResponse:
    """List locations based on provided filters.

    Provides the ability to filter the locations resource by the given arguments.

    * `page` - Specifies the page number of results to retrieve
    * `limit` - Sets the number of results generated per page
    * `radius` - Specifies the distance around a central point, filtering locations within a circular area. Must be used with `coordinates`, cannot be used in combination with `bbox`
    * `coordinates` - Filters locations by coordinates. Must be used with `radius`, cannot be used in combination with `bbox`
    * `bbox` - Filters locations using a bounding box. Cannot be used with `coordinates` or `radius`
    * `providers_id` - Filters results by selected providers ID(s)
    * `countries_id` - Filters results by selected countries ID(s)
    * `parameters_id` - Filters results by selected parameters ID(s)
    * `iso` - Filters results by selected country code
    * `monitor` - Filters results by reference grade monitors (`true`), air sensors (`false`), or both if not used
    * `mobile` - Filters results for mobile sensors (`true`), non-mobile sensors (`false`), or both if not used
    * `order_by` - Determines the fields by which results are sorted; available values are `id`
    * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

    Args:
        page: The page number. Page count is locations found / limit.
        limit: The number of results returned per page.
        radius: A distance value in meters to search around the given coordinates value.
        coordinates: WGS 84 coordinate pair in form latitude, longitude (y,x).
        bbox: Geospatial bounding box of min X, min Y, max X, max Y in WGS 84 coordinates. Limited to four decimals precision.
        providers_id: Single providers ID or an array of IDs.
        countries_id: Single countries ID or an array of IDs.
        parameters_id: Single parameters ID or an array of IDs.
        iso:  2 letter ISO 3166-alpha-2 country code.
        monitor: Boolean for reference grade monitors (true) or air sensors (false)
        mobile: Boolean mobile locations (true) or not mobile locations (false).
        order_by: Order by operators for results.
        sort_order: Sort order (asc/desc).

    Returns:
        LocationsResponse: An instance representing the list of retrieved locations.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    params = build_query_params(
        page=page,
        limit=limit,
        radius=radius,
        coordinates=coordinates,
        bbox=bbox,
        providers_id=providers_id,
        countries_id=countries_id,
        parameters_id=parameters_id,
        iso=iso,
        monitor=monitor,
        mobile=mobile,
        order_by=order_by,
        sort_order=sort_order,
    )

    locations = self._client._get("/locations", params=params)
    return LocationsResponse.load(locations.json())

Measurements

This provides methods to retrieve and list the air quality measurements from the OpenAQ API.

Source code in openaq/_sync/models/measurements.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
class Measurements(SyncResourceBase):
    """This provides methods to retrieve and list the air quality measurements from the OpenAQ API."""

    def list(
        self,
        locations_id: int,
        date_from: Union[datetime.datetime, str, None] = "2016-10-10",
        date_to: Union[datetime.datetime, str, None] = None,
        page: int = 1,
        limit: int = 1000,
        parameters_id: Union[int, List[int], None] = None,
    ) -> MeasurementsResponse:
        """List air quality measurements based on provided filters.

        Provides the ability to filter the measurements resource by location, date range,
        pagination settings, and specific parameters.

        * `locations_id` - Filters measurements to a specific locations ID (required)
        * `date_from` - Declare a start time for data retrieval
        * `date_to` - Declare an end time or data retrieval
        * `page` - Specifies the page number of results to retrieve
        * `limit` - Sets the number of results generated per page
        * `parameters_id` - Filters results by selected parameters ID(s)

        Args:
            locations_id: The ID of the location for which measurements should be retrieved.
            date_from: Starting date for the measurement retrieval. Can be a datetime object or ISO-8601 formatted date or datetime string.
            date_to: Ending date for the measurement retrieval. Can be a datetime object or ISO-8601 formatted date or datetime string.
            page: The page number to fetch. Page count is determined by total measurements found divided by the limit.
            limit: The number of results returned per page.
            parameters_id: Single parameters ID or an array of IDs.

        Returns:
            MeasurementsResponse: An instance representing the list of retrieved air quality measurements.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        params = build_query_params(
            page=page,
            limit=limit,
            locations_id=locations_id,
            date_from=date_from,
            date_to=date_to,
            parameters_id=parameters_id,
        )

        measurements = self._client._get(
            f"/locations/{locations_id}/measurements", params=params
        )
        return MeasurementsResponse.load(measurements.json())

list(locations_id, date_from='2016-10-10', date_to=None, page=1, limit=1000, parameters_id=None)

List air quality measurements based on provided filters.

Provides the ability to filter the measurements resource by location, date range, pagination settings, and specific parameters.

  • locations_id - Filters measurements to a specific locations ID (required)
  • date_from - Declare a start time for data retrieval
  • date_to - Declare an end time or data retrieval
  • page - Specifies the page number of results to retrieve
  • limit - Sets the number of results generated per page
  • parameters_id - Filters results by selected parameters ID(s)

Parameters:

Name Type Description Default
locations_id int

The ID of the location for which measurements should be retrieved.

 required
date_from Union[datetime, str, None]

Starting date for the measurement retrieval. Can be a datetime object or ISO-8601 formatted date or datetime string.

 '2016-10-10'
date_to Union[datetime, str, None]

Ending date for the measurement retrieval. Can be a datetime object or ISO-8601 formatted date or datetime string.

 None
page int

The page number to fetch. Page count is determined by total measurements found divided by the limit.

 1
limit int

The number of results returned per page.

 1000
parameters_id Union[int, List[int], None]

Single parameters ID or an array of IDs.

 None

Returns:

Name Type Description
MeasurementsResponse MeasurementsResponse

An instance representing the list of retrieved air quality measurements.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/measurements.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def list(
    self,
    locations_id: int,
    date_from: Union[datetime.datetime, str, None] = "2016-10-10",
    date_to: Union[datetime.datetime, str, None] = None,
    page: int = 1,
    limit: int = 1000,
    parameters_id: Union[int, List[int], None] = None,
) -> MeasurementsResponse:
    """List air quality measurements based on provided filters.

    Provides the ability to filter the measurements resource by location, date range,
    pagination settings, and specific parameters.

    * `locations_id` - Filters measurements to a specific locations ID (required)
    * `date_from` - Declare a start time for data retrieval
    * `date_to` - Declare an end time or data retrieval
    * `page` - Specifies the page number of results to retrieve
    * `limit` - Sets the number of results generated per page
    * `parameters_id` - Filters results by selected parameters ID(s)

    Args:
        locations_id: The ID of the location for which measurements should be retrieved.
        date_from: Starting date for the measurement retrieval. Can be a datetime object or ISO-8601 formatted date or datetime string.
        date_to: Ending date for the measurement retrieval. Can be a datetime object or ISO-8601 formatted date or datetime string.
        page: The page number to fetch. Page count is determined by total measurements found divided by the limit.
        limit: The number of results returned per page.
        parameters_id: Single parameters ID or an array of IDs.

    Returns:
        MeasurementsResponse: An instance representing the list of retrieved air quality measurements.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    params = build_query_params(
        page=page,
        limit=limit,
        locations_id=locations_id,
        date_from=date_from,
        date_to=date_to,
        parameters_id=parameters_id,
    )

    measurements = self._client._get(
        f"/locations/{locations_id}/measurements", params=params
    )
    return MeasurementsResponse.load(measurements.json())

Countries

This provides methods to retrieve country data from the OpenAQ API.

Source code in openaq/_sync/models/countries.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
class Countries(SyncResourceBase):
    """This provides methods to retrieve country data from the OpenAQ API."""

    def get(self, countries_id: int) -> CountriesResponse:
        """Retrieve specific country data by its countries ID.

        Args:
            countries_id: The countries ID of the country to retrieve.

        Returns:
            CountriesResponse: An instance representing the retrieved country.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        country = self._client._get(f"/countries/{countries_id}")
        return CountriesResponse.load(country.json())

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        order_by: str = None,
        sort_order: str = None,
        parameters_id: int = None,
        providers_id: int = None,
    ) -> CountriesResponse:
        """List countries based on provided filters.

        Provides the ability to filter the countries resource by the given arguments.

        * `page` - Specifies the page number of results to retrieve
        * `limit` - Sets the number of results generated per page
        * `providers_id` - Filter results by selected providers ID(s)
        * `parameters_id` - Filters results by selected parameters ID(s)
        * `order_by` - Determines the fields by which results are sorted; available values are `id`
        * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

        Args:
            page: The page number. Page count is countries found / limit.
            limit: The number of results returned per page.
            order_by: Order by operators for results.
            sort_order: Sort order (asc/desc).
            parameters_id: Single parameters ID or an array of IDs.
            providers_id: Single providers ID or an array of IDs.

        Returns:
            CountriesResponse: An instance representing the list of retrieved countries.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        params = build_query_params(
            page=page,
            limit=limit,
            order_by=order_by,
            sort_order=sort_order,
            parameters_id=parameters_id,
            providers_id=providers_id,
        )

        countries = self._client._get("/countries", params=params)
        return CountriesResponse.load(countries.json())

get(countries_id)

Retrieve specific country data by its countries ID.

Parameters:

Name Type Description Default
countries_id int

The countries ID of the country to retrieve.

 required

Returns:

Name Type Description
CountriesResponse CountriesResponse

An instance representing the retrieved country.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/countries.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def get(self, countries_id: int) -> CountriesResponse:
    """Retrieve specific country data by its countries ID.

    Args:
        countries_id: The countries ID of the country to retrieve.

    Returns:
        CountriesResponse: An instance representing the retrieved country.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    country = self._client._get(f"/countries/{countries_id}")
    return CountriesResponse.load(country.json())

list(page=1, limit=1000, order_by=None, sort_order=None, parameters_id=None, providers_id=None)

List countries based on provided filters.

Provides the ability to filter the countries resource by the given arguments.

  • page - Specifies the page number of results to retrieve
  • limit - Sets the number of results generated per page
  • providers_id - Filter results by selected providers ID(s)
  • parameters_id - Filters results by selected parameters ID(s)
  • order_by - Determines the fields by which results are sorted; available values are id
  • sort_order - Works in tandem with order_by to specify the direction: either asc (ascending) or desc (descending)

Parameters:

Name Type Description Default
page int

The page number. Page count is countries found / limit.

 1
limit int

The number of results returned per page.

 1000
order_by str

Order by operators for results.

 None
sort_order str

Sort order (asc/desc).

 None
parameters_id int

Single parameters ID or an array of IDs.

 None
providers_id int

Single providers ID or an array of IDs.

 None

Returns:

Name Type Description
CountriesResponse CountriesResponse

An instance representing the list of retrieved countries.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/countries.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str = None,
    sort_order: str = None,
    parameters_id: int = None,
    providers_id: int = None,
) -> CountriesResponse:
    """List countries based on provided filters.

    Provides the ability to filter the countries resource by the given arguments.

    * `page` - Specifies the page number of results to retrieve
    * `limit` - Sets the number of results generated per page
    * `providers_id` - Filter results by selected providers ID(s)
    * `parameters_id` - Filters results by selected parameters ID(s)
    * `order_by` - Determines the fields by which results are sorted; available values are `id`
    * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

    Args:
        page: The page number. Page count is countries found / limit.
        limit: The number of results returned per page.
        order_by: Order by operators for results.
        sort_order: Sort order (asc/desc).
        parameters_id: Single parameters ID or an array of IDs.
        providers_id: Single providers ID or an array of IDs.

    Returns:
        CountriesResponse: An instance representing the list of retrieved countries.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    params = build_query_params(
        page=page,
        limit=limit,
        order_by=order_by,
        sort_order=sort_order,
        parameters_id=parameters_id,
        providers_id=providers_id,
    )

    countries = self._client._get("/countries", params=params)
    return CountriesResponse.load(countries.json())

Instruments

This provides methods to retrieve instrument data from the OpenAQ API.

Source code in openaq/_sync/models/instruments.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
class Instruments(SyncResourceBase):
    """This provides methods to retrieve instrument data from the OpenAQ API."""

    def get(self, providers_id: int) -> InstrumentsResponse:
        """Retrieve specific instrument data by its providers ID.

        Args:
            providers_id: The providers ID of the instrument to retrieve.

        Returns:
            InstrumentsResponse: An instance representing the retrieved instrument.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        instrument = self._client._get(f"/instruments/{providers_id}")
        return InstrumentsResponse.load(instrument.json())

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        order_by: str = None,
        sort_order: str = None,
    ) -> InstrumentsResponse:
        """List instruments based on provided filters.

        Provides the ability to filter the instruments resource by the given arguments.

        * `page` - Specifies the page number of results to retrieve.
        * `limit` - Sets the number of results generated per page
        * `order_by` - Determines the fields by which results are sorted; available values are `id`
        * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

        Args:
            page: The page number. Page count is instruments found / limit.
            limit: The number of results returned per page.
            order_by: Order by operators for results.
            sort_order: Sort order (asc/desc).

        Returns:
            InstrumentsResponse: An instance representing the list of retrieved instruments.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        params = build_query_params(
            page=page, limit=limit, order_by=order_by, sort_order=sort_order
        )

        instruments = self._client._get("/instruments", params=params)
        return InstrumentsResponse.load(instruments.json())

get(providers_id)

Retrieve specific instrument data by its providers ID.

Parameters:

Name Type Description Default
providers_id int

The providers ID of the instrument to retrieve.

 required

Returns:

Name Type Description
InstrumentsResponse InstrumentsResponse

An instance representing the retrieved instrument.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/instruments.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def get(self, providers_id: int) -> InstrumentsResponse:
    """Retrieve specific instrument data by its providers ID.

    Args:
        providers_id: The providers ID of the instrument to retrieve.

    Returns:
        InstrumentsResponse: An instance representing the retrieved instrument.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    instrument = self._client._get(f"/instruments/{providers_id}")
    return InstrumentsResponse.load(instrument.json())

list(page=1, limit=1000, order_by=None, sort_order=None)

List instruments based on provided filters.

Provides the ability to filter the instruments resource by the given arguments.

  • page - Specifies the page number of results to retrieve.
  • limit - Sets the number of results generated per page
  • order_by - Determines the fields by which results are sorted; available values are id
  • sort_order - Works in tandem with order_by to specify the direction: either asc (ascending) or desc (descending)

Parameters:

Name Type Description Default
page int

The page number. Page count is instruments found / limit.

 1
limit int

The number of results returned per page.

 1000
order_by str

Order by operators for results.

 None
sort_order str

Sort order (asc/desc).

 None

Returns:

Name Type Description
InstrumentsResponse InstrumentsResponse

An instance representing the list of retrieved instruments.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/instruments.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str = None,
    sort_order: str = None,
) -> InstrumentsResponse:
    """List instruments based on provided filters.

    Provides the ability to filter the instruments resource by the given arguments.

    * `page` - Specifies the page number of results to retrieve.
    * `limit` - Sets the number of results generated per page
    * `order_by` - Determines the fields by which results are sorted; available values are `id`
    * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

    Args:
        page: The page number. Page count is instruments found / limit.
        limit: The number of results returned per page.
        order_by: Order by operators for results.
        sort_order: Sort order (asc/desc).

    Returns:
        InstrumentsResponse: An instance representing the list of retrieved instruments.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    params = build_query_params(
        page=page, limit=limit, order_by=order_by, sort_order=sort_order
    )

    instruments = self._client._get("/instruments", params=params)
    return InstrumentsResponse.load(instruments.json())

Manufacturers

This provides methods to retrieve manufacturer data from the OpenAQ API.

Source code in openaq/_sync/models/manufacturers.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
class Manufacturers(SyncResourceBase):
    """This provides methods to retrieve manufacturer data from the OpenAQ API."""

    def get(self, manufacturers_id: int) -> ManufacturersResponse:
        """Retrieve specific manufacturer data by its manufacturers ID.

        Args:
            manufacturers_id: The manufacturers ID of the manufacturer to retrieve.

        Returns:
            ManufacturersResponse: An instance representing the retrieved manufacturer.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        manufacturer = self._client._get(f"/manufacturers/{manufacturers_id}")
        return ManufacturersResponse.load(manufacturer.json())

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        order_by: str = None,
        sort_order: str = None,
    ) -> ManufacturersResponse:
        """List manufacturers based on provided filters.

        Provides the ability to filter the manufacturers resource by the given arguments.

        * `page` - Specifies the page number of results to retrieve
        * `limit` - Sets the number of results generated per page
        * `order_by` - Determines the fields by which results are sorted; available values are `id`
        * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

        Args:
            page: The page number. Page count is manufacturers found / limit.
            limit: The number of results returned per page.
            order_by: Order by operators for results.
            sort_order: Sort order (asc/desc).

        Returns:
            ManufacturersResponse: An instance representing the list of retrieved manufacturers.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        params = build_query_params(
            page=page, limit=limit, order_by=order_by, sort_order=sort_order
        )

        manufacturers = self._client._get("/manufacturers", params=params)
        return ManufacturersResponse.load(manufacturers.json())

get(manufacturers_id)

Retrieve specific manufacturer data by its manufacturers ID.

Parameters:

Name Type Description Default
manufacturers_id int

The manufacturers ID of the manufacturer to retrieve.

 required

Returns:

Name Type Description
ManufacturersResponse ManufacturersResponse

An instance representing the retrieved manufacturer.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/manufacturers.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def get(self, manufacturers_id: int) -> ManufacturersResponse:
    """Retrieve specific manufacturer data by its manufacturers ID.

    Args:
        manufacturers_id: The manufacturers ID of the manufacturer to retrieve.

    Returns:
        ManufacturersResponse: An instance representing the retrieved manufacturer.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    manufacturer = self._client._get(f"/manufacturers/{manufacturers_id}")
    return ManufacturersResponse.load(manufacturer.json())

list(page=1, limit=1000, order_by=None, sort_order=None)

List manufacturers based on provided filters.

Provides the ability to filter the manufacturers resource by the given arguments.

  • page - Specifies the page number of results to retrieve
  • limit - Sets the number of results generated per page
  • order_by - Determines the fields by which results are sorted; available values are id
  • sort_order - Works in tandem with order_by to specify the direction: either asc (ascending) or desc (descending)

Parameters:

Name Type Description Default
page int

The page number. Page count is manufacturers found / limit.

 1
limit int

The number of results returned per page.

 1000
order_by str

Order by operators for results.

 None
sort_order str

Sort order (asc/desc).

 None

Returns:

Name Type Description
ManufacturersResponse ManufacturersResponse

An instance representing the list of retrieved manufacturers.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/manufacturers.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str = None,
    sort_order: str = None,
) -> ManufacturersResponse:
    """List manufacturers based on provided filters.

    Provides the ability to filter the manufacturers resource by the given arguments.

    * `page` - Specifies the page number of results to retrieve
    * `limit` - Sets the number of results generated per page
    * `order_by` - Determines the fields by which results are sorted; available values are `id`
    * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

    Args:
        page: The page number. Page count is manufacturers found / limit.
        limit: The number of results returned per page.
        order_by: Order by operators for results.
        sort_order: Sort order (asc/desc).

    Returns:
        ManufacturersResponse: An instance representing the list of retrieved manufacturers.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    params = build_query_params(
        page=page, limit=limit, order_by=order_by, sort_order=sort_order
    )

    manufacturers = self._client._get("/manufacturers", params=params)
    return ManufacturersResponse.load(manufacturers.json())

Owners

This provides methods to retrieve owner data from the OpenAQ API.

Source code in openaq/_sync/models/owners.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
class Owners(SyncResourceBase):
    """This provides methods to retrieve owner data from the OpenAQ API."""

    def get(self, owners_id: int) -> OwnersResponse:
        """Retrieve specific owner data by its owners ID.

        Args:
            owners_id: The owners ID of the owner to retrieve.

        Returns:
            OwnersResponse: An instance representing the retrieved owner.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        owner = self._client._get(f"/owners/{owners_id}")
        return OwnersResponse.load(owner.json())

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        order_by: str = None,
        sort_order: str = None,
    ) -> OwnersResponse:
        """List owners based on provided filters.

        Provides the ability to filter the owners resource by the given arguments.

        * `page` - Specifies the page number of results to retrieve
        * `limit` - Sets the number of results generated per page
        * `order_by` - Determines the fields by which results are sorted; available values are `id`
        * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

        Args:
            page: The page number. Page count is owners found / limit.
            limit: The number of results returned per page.
            order_by: Order by operators for results.
            sort_order: Sort order (asc/desc).

        Returns:
            OwnersResponse: An instance representing the list of retrieved owners.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        params = build_query_params(
            page=page, limit=limit, order_by=order_by, sort_order=sort_order
        )

        owners = self._client._get("/owners", params=params)
        return OwnersResponse.load(owners.json())

get(owners_id)

Retrieve specific owner data by its owners ID.

Parameters:

Name Type Description Default
owners_id int

The owners ID of the owner to retrieve.

 required

Returns:

Name Type Description
OwnersResponse OwnersResponse

An instance representing the retrieved owner.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/owners.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def get(self, owners_id: int) -> OwnersResponse:
    """Retrieve specific owner data by its owners ID.

    Args:
        owners_id: The owners ID of the owner to retrieve.

    Returns:
        OwnersResponse: An instance representing the retrieved owner.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    owner = self._client._get(f"/owners/{owners_id}")
    return OwnersResponse.load(owner.json())

list(page=1, limit=1000, order_by=None, sort_order=None)

List owners based on provided filters.

Provides the ability to filter the owners resource by the given arguments.

  • page - Specifies the page number of results to retrieve
  • limit - Sets the number of results generated per page
  • order_by - Determines the fields by which results are sorted; available values are id
  • sort_order - Works in tandem with order_by to specify the direction: either asc (ascending) or desc (descending)

Parameters:

Name Type Description Default
page int

The page number. Page count is owners found / limit.

 1
limit int

The number of results returned per page.

 1000
order_by str

Order by operators for results.

 None
sort_order str

Sort order (asc/desc).

 None

Returns:

Name Type Description
OwnersResponse OwnersResponse

An instance representing the list of retrieved owners.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/owners.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str = None,
    sort_order: str = None,
) -> OwnersResponse:
    """List owners based on provided filters.

    Provides the ability to filter the owners resource by the given arguments.

    * `page` - Specifies the page number of results to retrieve
    * `limit` - Sets the number of results generated per page
    * `order_by` - Determines the fields by which results are sorted; available values are `id`
    * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

    Args:
        page: The page number. Page count is owners found / limit.
        limit: The number of results returned per page.
        order_by: Order by operators for results.
        sort_order: Sort order (asc/desc).

    Returns:
        OwnersResponse: An instance representing the list of retrieved owners.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    params = build_query_params(
        page=page, limit=limit, order_by=order_by, sort_order=sort_order
    )

    owners = self._client._get("/owners", params=params)
    return OwnersResponse.load(owners.json())

Parameters

This provides methods to retrieve parameter data from the OpenAQ API.

Source code in openaq/_sync/models/parameters.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
class Parameters(SyncResourceBase):
    """This provides methods to retrieve parameter data from the OpenAQ API."""

    def get(self, parameters_id: int) -> ParametersResponse:
        """Retrieve specific parameter data by its parameters ID.

        Args:
            parameters_id: The parameters ID of the parameter to retrieve.

        Returns:
            ParametersResponse: An instance representing the retrieved parameter.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        parameter = self._client._get(f"/parameters/{parameters_id}")
        return ParametersResponse.load(parameter.json())

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        order_by: str = None,
        sort_order: str = None,
        parameter_type: str = None,
        coordinates: tuple = None,
        radius: int = None,
        bbox: tuple = None,
        iso: str = None,
        countries_id: int = None,
    ) -> ParametersResponse:
        """List parameters based on provided filters.

        Provides the ability to filter the parameters resource by the given arguments.

        * `page` - Specifies the page number of results to retrieve
        * `limit` - Sets the number of results generated per page
        * `parameter_type` - Filters results by type of parameter (pollutant or meteorological)
        * `radius` - Defines the distance around a given point to filter locations within that circular area. Always use with `coordinates` and not with `bbox`
        * `coordinates` - Filters locations by coordinates. Must be used with `radius`, cannot be used in combination with `bbox`
        * `bbox` - Filters locations using a bounding box. Cannot be used with `coordinates` or `radius`
        * `iso` - Filters results by selected country code
        * `countries_id` - Filters results by selected countries ID(s)
        * `order_by` - Determines the fields by which results are sorted; available values are `id`
        * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

        Args:
            page: The page number. Page count is parameters found / limit.
            limit: The number of results returned per page.
            parameter_type: pollutant or meteorological.
            radius: A distance value in meters to search around the given coordinates value.
            coordinates: WGS 84 coordinate pair in form latitude, longitude (y,x).
            bbox: Geospatial bounding box of min X, min Y, max X, max Y in WGS 84 coordinates. Limited to four decimals precision.
            iso:  2 letter ISO 3166-alpha-2 country code.
            countries_id: Single countries ID or an array of IDs.
            order_by: Order by operators for results.
            sort_order: Sort order (asc/desc).

        Returns:
            ParametersResponse: An instance representing the list of retrieved parameters.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        params = build_query_params(
            page=page,
            limit=limit,
            order_by=order_by,
            sort_order=sort_order,
            parameter_type=parameter_type,
            coordinates=coordinates,
            radius=radius,
            bbox=bbox,
            iso=iso,
            countries_id=countries_id,
        )

        parameters = self._client._get("/parameters", params=params)
        return ParametersResponse.load(parameters.json())

get(parameters_id)

Retrieve specific parameter data by its parameters ID.

Parameters:

Name Type Description Default
parameters_id int

The parameters ID of the parameter to retrieve.

 required

Returns:

Name Type Description
ParametersResponse ParametersResponse

An instance representing the retrieved parameter.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/parameters.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def get(self, parameters_id: int) -> ParametersResponse:
    """Retrieve specific parameter data by its parameters ID.

    Args:
        parameters_id: The parameters ID of the parameter to retrieve.

    Returns:
        ParametersResponse: An instance representing the retrieved parameter.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    parameter = self._client._get(f"/parameters/{parameters_id}")
    return ParametersResponse.load(parameter.json())

list(page=1, limit=1000, order_by=None, sort_order=None, parameter_type=None, coordinates=None, radius=None, bbox=None, iso=None, countries_id=None)

List parameters based on provided filters.

Provides the ability to filter the parameters resource by the given arguments.

  • page - Specifies the page number of results to retrieve
  • limit - Sets the number of results generated per page
  • parameter_type - Filters results by type of parameter (pollutant or meteorological)
  • radius - Defines the distance around a given point to filter locations within that circular area. Always use with coordinates and not with bbox
  • coordinates - Filters locations by coordinates. Must be used with radius, cannot be used in combination with bbox
  • bbox - Filters locations using a bounding box. Cannot be used with coordinates or radius
  • iso - Filters results by selected country code
  • countries_id - Filters results by selected countries ID(s)
  • order_by - Determines the fields by which results are sorted; available values are id
  • sort_order - Works in tandem with order_by to specify the direction: either asc (ascending) or desc (descending)

Parameters:

Name Type Description Default
page int

The page number. Page count is parameters found / limit.

 1
limit int

The number of results returned per page.

 1000
parameter_type str

pollutant or meteorological.

 None
radius int

A distance value in meters to search around the given coordinates value.

 None
coordinates tuple

WGS 84 coordinate pair in form latitude, longitude (y,x).

 None
bbox tuple

Geospatial bounding box of min X, min Y, max X, max Y in WGS 84 coordinates. Limited to four decimals precision.

 None
iso str

2 letter ISO 3166-alpha-2 country code.

 None
countries_id int

Single countries ID or an array of IDs.

 None
order_by str

Order by operators for results.

 None
sort_order str

Sort order (asc/desc).

 None

Returns:

Name Type Description
ParametersResponse ParametersResponse

An instance representing the list of retrieved parameters.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/parameters.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str = None,
    sort_order: str = None,
    parameter_type: str = None,
    coordinates: tuple = None,
    radius: int = None,
    bbox: tuple = None,
    iso: str = None,
    countries_id: int = None,
) -> ParametersResponse:
    """List parameters based on provided filters.

    Provides the ability to filter the parameters resource by the given arguments.

    * `page` - Specifies the page number of results to retrieve
    * `limit` - Sets the number of results generated per page
    * `parameter_type` - Filters results by type of parameter (pollutant or meteorological)
    * `radius` - Defines the distance around a given point to filter locations within that circular area. Always use with `coordinates` and not with `bbox`
    * `coordinates` - Filters locations by coordinates. Must be used with `radius`, cannot be used in combination with `bbox`
    * `bbox` - Filters locations using a bounding box. Cannot be used with `coordinates` or `radius`
    * `iso` - Filters results by selected country code
    * `countries_id` - Filters results by selected countries ID(s)
    * `order_by` - Determines the fields by which results are sorted; available values are `id`
    * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

    Args:
        page: The page number. Page count is parameters found / limit.
        limit: The number of results returned per page.
        parameter_type: pollutant or meteorological.
        radius: A distance value in meters to search around the given coordinates value.
        coordinates: WGS 84 coordinate pair in form latitude, longitude (y,x).
        bbox: Geospatial bounding box of min X, min Y, max X, max Y in WGS 84 coordinates. Limited to four decimals precision.
        iso:  2 letter ISO 3166-alpha-2 country code.
        countries_id: Single countries ID or an array of IDs.
        order_by: Order by operators for results.
        sort_order: Sort order (asc/desc).

    Returns:
        ParametersResponse: An instance representing the list of retrieved parameters.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    params = build_query_params(
        page=page,
        limit=limit,
        order_by=order_by,
        sort_order=sort_order,
        parameter_type=parameter_type,
        coordinates=coordinates,
        radius=radius,
        bbox=bbox,
        iso=iso,
        countries_id=countries_id,
    )

    parameters = self._client._get("/parameters", params=params)
    return ParametersResponse.load(parameters.json())

Providers

This provides methods to retrieve provider data from the OpenAQ API.

Source code in openaq/_sync/models/providers.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
class Providers(SyncResourceBase):
    """This provides methods to retrieve provider data from the OpenAQ API."""

    def get(self, providers_id: int) -> ProvidersResponse:
        """Retrieve specific provider data by its providers ID.

        Args:
            providers_id: The providers ID of the provider to retrieve.

        Returns:
            ProvidersResponse: An instance representing the retrieved provider.

        Raises:
            See the 'Raises' section of the 'list' method for potential exceptions.
        """
        provider = self._client._get(f"/providers/{providers_id}")
        return ProvidersResponse.load(provider.json())

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        order_by: str = None,
        sort_order: str = None,
        parameters_id: int = None,
        monitor: bool = None,
        coordinates: tuple = None,
        radius: int = None,
        bbox: tuple = None,
        iso: str = None,
        countries_id: int = None,
    ) -> ProvidersResponse:
        """List providers based on provided filters.

        Provides the ability to filter the providers resource by the given arguments.

        * `page` - Specifies the page number of results to retrieve
        * `limit` - Sets the number of results generated per page
        * `parameters_id` - Filters results by selected parameters ID(s)
        * `monitor` - Filters results by reference grade monitors (`true`), air sensors (`false`), or both if not used
        * `radius` - Defines the distance around a given point to filter locations within that circular area. Always use with `coordinates` and not with `bbox`
        * `coordinates` - Filters locations by coordinates. Must be used with `radius`, cannot be used in combination with `bbox`
        * `bbox` - Filters locations using a bounding box. Cannot be used with `coordinates` or `radius`
        * `iso` - Filters results by selected country code
        * `countries_id` - Filter results by selected countries ID(s)
        * `order_by` - Determines the fields by which results are sorted; available values are `id`
        * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

        Args:
            page: The page number. Page count is providers found / limit.
            limit: The number of results returned per page.
            parameters_id: Single parameters ID or an array of IDs.
            monitor: Boolean for reference grade monitors (true) or air sensors (false).
            radius: A distance value in meters to search around the given coordinates value.
            coordinates: WGS 84 coordinate pair in form latitude, longitude (y,x).
            bbox: Geospatial bounding box of min X, min Y, max X, max Y in WGS 84 coordinates. Limited to four decimals precision.
            iso:  2 letter ISO 3166-alpha-2 country code.
            countries_id: Single countries ID or an array of IDs.
            order_by: Order by operators for results.
            sort_order: Sort order (asc/desc).

        Returns:
            ProvidersResponse: An instance representing the list of retrieved providers.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
            Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
            ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        params = build_query_params(
            page=page,
            limit=limit,
            order_by=order_by,
            sort_order=sort_order,
            parameters_id=parameters_id,
            monitor=monitor,
            coordinates=coordinates,
            radius=radius,
            bbox=bbox,
            iso=iso,
            countries_id=countries_id,
        )

        providers = self._client._get("/providers", params=params)
        return ProvidersResponse.load(providers.json())

get(providers_id)

Retrieve specific provider data by its providers ID.

Parameters:

Name Type Description Default
providers_id int

The providers ID of the provider to retrieve.

 required

Returns:

Name Type Description
ProvidersResponse ProvidersResponse

An instance representing the retrieved provider.
Source code in openaq/_sync/models/providers.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
def get(self, providers_id: int) -> ProvidersResponse:
    """Retrieve specific provider data by its providers ID.

    Args:
        providers_id: The providers ID of the provider to retrieve.

    Returns:
        ProvidersResponse: An instance representing the retrieved provider.

    Raises:
        See the 'Raises' section of the 'list' method for potential exceptions.
    """
    provider = self._client._get(f"/providers/{providers_id}")
    return ProvidersResponse.load(provider.json())

list(page=1, limit=1000, order_by=None, sort_order=None, parameters_id=None, monitor=None, coordinates=None, radius=None, bbox=None, iso=None, countries_id=None)

List providers based on provided filters.

Provides the ability to filter the providers resource by the given arguments.

  • page - Specifies the page number of results to retrieve
  • limit - Sets the number of results generated per page
  • parameters_id - Filters results by selected parameters ID(s)
  • monitor - Filters results by reference grade monitors (true), air sensors (false), or both if not used
  • radius - Defines the distance around a given point to filter locations within that circular area. Always use with coordinates and not with bbox
  • coordinates - Filters locations by coordinates. Must be used with radius, cannot be used in combination with bbox
  • bbox - Filters locations using a bounding box. Cannot be used with coordinates or radius
  • iso - Filters results by selected country code
  • countries_id - Filter results by selected countries ID(s)
  • order_by - Determines the fields by which results are sorted; available values are id
  • sort_order - Works in tandem with order_by to specify the direction: either asc (ascending) or desc (descending)

Parameters:

Name Type Description Default
page int

The page number. Page count is providers found / limit.

 1
limit int

The number of results returned per page.

 1000
parameters_id int

Single parameters ID or an array of IDs.

 None
monitor bool

Boolean for reference grade monitors (true) or air sensors (false).

 None
radius int

A distance value in meters to search around the given coordinates value.

 None
coordinates tuple

WGS 84 coordinate pair in form latitude, longitude (y,x).

 None
bbox tuple

Geospatial bounding box of min X, min Y, max X, max Y in WGS 84 coordinates. Limited to four decimals precision.

 None
iso str

2 letter ISO 3166-alpha-2 country code.

 None
countries_id int

Single countries ID or an array of IDs.

 None
order_by str

Order by operators for results.

 None
sort_order str

Sort order (asc/desc).

 None

Returns:

Name Type Description
ProvidersResponse ProvidersResponse

An instance representing the list of retrieved providers.

Raises:

Type Description
BadRequestError

Raised for HTTP 400 error, indicating a client request error.
NotAuthorized

Raised for HTTP 401 error, indicating the client is not authorized.
Forbidden

Raised for HTTP 403 error, indicating the request is forbidden.
NotFoundError

Raised for HTTP 404 error, indicating a resource is not found.
ValidationError

Raised for HTTP 422 error, indicating invalid request parameters.
RateLimit

Raised for HTTP 429 error, indicating rate limit exceeded.
ServerError

Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/providers.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str = None,
    sort_order: str = None,
    parameters_id: int = None,
    monitor: bool = None,
    coordinates: tuple = None,
    radius: int = None,
    bbox: tuple = None,
    iso: str = None,
    countries_id: int = None,
) -> ProvidersResponse:
    """List providers based on provided filters.

    Provides the ability to filter the providers resource by the given arguments.

    * `page` - Specifies the page number of results to retrieve
    * `limit` - Sets the number of results generated per page
    * `parameters_id` - Filters results by selected parameters ID(s)
    * `monitor` - Filters results by reference grade monitors (`true`), air sensors (`false`), or both if not used
    * `radius` - Defines the distance around a given point to filter locations within that circular area. Always use with `coordinates` and not with `bbox`
    * `coordinates` - Filters locations by coordinates. Must be used with `radius`, cannot be used in combination with `bbox`
    * `bbox` - Filters locations using a bounding box. Cannot be used with `coordinates` or `radius`
    * `iso` - Filters results by selected country code
    * `countries_id` - Filter results by selected countries ID(s)
    * `order_by` - Determines the fields by which results are sorted; available values are `id`
    * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)

    Args:
        page: The page number. Page count is providers found / limit.
        limit: The number of results returned per page.
        parameters_id: Single parameters ID or an array of IDs.
        monitor: Boolean for reference grade monitors (true) or air sensors (false).
        radius: A distance value in meters to search around the given coordinates value.
        coordinates: WGS 84 coordinate pair in form latitude, longitude (y,x).
        bbox: Geospatial bounding box of min X, min Y, max X, max Y in WGS 84 coordinates. Limited to four decimals precision.
        iso:  2 letter ISO 3166-alpha-2 country code.
        countries_id: Single countries ID or an array of IDs.
        order_by: Order by operators for results.
        sort_order: Sort order (asc/desc).

    Returns:
        ProvidersResponse: An instance representing the list of retrieved providers.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorized: Raised for HTTP 401 error, indicating the client is not authorized.
        Forbidden: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimit: Raised for HTTP 429 error, indicating rate limit exceeded.
        ServerError: Raised for HTTP 500 error, indicating an internal server error or unexpected server-side issue.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    params = build_query_params(
        page=page,
        limit=limit,
        order_by=order_by,
        sort_order=sort_order,
        parameters_id=parameters_id,
        monitor=monitor,
        coordinates=coordinates,
        radius=radius,
        bbox=bbox,
        iso=iso,
        countries_id=countries_id,
    )

    providers = self._client._get("/providers", params=params)
    return ProvidersResponse.load(providers.json())