Skip to content

OpenAQ

OpenAQ

OpenAQ syncronous client.

Parameters:

Name Type Description Default
api_key str | None

The API key for accessing the service.

 None
headers Mapping[str, str]

Additional headers to be sent with the request.

 {}
base_url str

The base URL for the API endpoint.

 DEFAULT_BASE_URL
Note

An API key can either be passed directly to the OpenAQ client class at instantiation or can be accessed from a system environment variable name OPENAQ-API-KEY. An API key added at instantiation will always override one set in the environment variable.

Warning

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
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/client.py 
 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
117
class OpenAQ(BaseClient[Transport]):
    """OpenAQ syncronous client.

    Args:
        api_key: The API key for accessing the service.
        headers: Additional headers to be sent with the request.
        base_url: The base URL for the API endpoint.

    Note:
        An API key can either be passed directly to the OpenAQ client class at
        instantiation or can be accessed from a system environment variable
        name `OPENAQ-API-KEY`. An API key added at instantiation will always
        override one set in the environment variable.

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

    Raises:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.

    """

    def __init__(
        self,
        api_key: str | None = None,
        headers: Mapping[str, str] = {},
        base_url: str = DEFAULT_BASE_URL,
        _transport: Transport = Transport(),
    ) -> None:
        super().__init__(_transport, headers, api_key, base_url)

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

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

    def _do(
        self,
        method: str,
        path: str,
        *,
        params: Mapping[str, Any] | None = None,
        headers: Mapping[str, str] | None = None,
    ):
        self._check_rate_limit()
        request_headers = self.build_request_headers(headers)
        url = self._base_url + path
        data = self.transport.send_request(
            method=method, url=url, params=params, headers=request_headers
        )
        self._set_rate_limit(data.headers)
        return data

    def _get(
        self,
        path: str,
        *,
        params: Mapping[str, str] | None = None,
        headers: 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

Provides methods to retrieve the locations resource from the OpenAQ API.

Source code in openaq/_sync/models/locations.py 
 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
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
class Locations(SyncResourceBase):
    """Provides methods to retrieve the 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:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        location_response = self._client._get(f"/locations/{locations_id}")
        return LocationsResponse.read_response(location_response)

    def latest(self, locations_id: int) -> LatestResponse:
        """Retrieve latest measurements from a location.

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

        Returns:
            LatestResponse: An instance representing the retrieved latest results.

        Raises:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        latest = self._client._get(f"/locations/{locations_id}/latest")
        return LatestResponse.read_response(latest)

    def list(
        self,
        page: int = 1,
        limit: int = 100,
        radius: int | None = None,
        coordinates: Tuple[float, float] | None = None,
        bbox: Tuple[float, float, float, float] | None = None,
        providers_id: int | list[int] | None = None,
        countries_id: int | list[int] | None = None,
        parameters_id: int | list[int] | None = None,
        licenses_id: int | list[int] | None = None,
        iso: str | None = None,
        monitor: bool | None = None,
        mobile: bool | None = None,
        order_by: str | None = None,
        sort_order: 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)
        * `licenses_id` - Filters results by selected licenses 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.
            licenses_id: Single licenses 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:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            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,
            licenses_id=licenses_id,
            iso=iso,
            monitor=monitor,
            mobile=mobile,
            order_by=order_by,
            sort_order=sort_order,
        )

        locations_response = self._client._get("/locations", params=params)
        return LocationsResponse.read_response(locations_response)

    def sensors(self, locations_id: int) -> SensorsResponse:
        """Retrieve sensors from a location.

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

        Returns:
            SensorsResponse: An instance representing the retrieved latest results.

        Raises:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        sensors = self._client._get(f"/locations/{locations_id}/sensors")
        return SensorsResponse.read_response(sensors)

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
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/locations.py 
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
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:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    location_response = self._client._get(f"/locations/{locations_id}")
    return LocationsResponse.read_response(location_response)

latest(locations_id)

Retrieve latest measurements from a location.

Parameters:

Name Type Description Default
locations_id int

The locations ID of the location to retrieve.

 required

Returns:

Name Type Description
LatestResponse LatestResponse

An instance representing the retrieved latest results.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/locations.py 
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
def latest(self, locations_id: int) -> LatestResponse:
    """Retrieve latest measurements from a location.

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

    Returns:
        LatestResponse: An instance representing the retrieved latest results.

    Raises:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    latest = self._client._get(f"/locations/{locations_id}/latest")
    return LatestResponse.read_response(latest)

list(page=1, limit=100, radius=None, coordinates=None, bbox=None, providers_id=None, countries_id=None, parameters_id=None, licenses_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)
  • licenses_id - Filters results by selected licenses 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.

 100
radius int | None

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

 None
coordinates Tuple[float, float] | None

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

 None
bbox 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 int | list[int] | None

Single providers ID or an array of IDs.

 None
countries_id int | list[int] | None

Single countries ID or an array of IDs.

 None
parameters_id int | list[int] | None

Single parameters ID or an array of IDs.

 None
licenses_id int | list[int] | None

Single licenses ID or an array of IDs.

 None
iso str | None

2 letter ISO 3166-alpha-2 country code.

 None
monitor bool | None

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

 None
mobile bool | None

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

 None
order_by str | None

Order by operators for results.

 None
sort_order str | None

Sort order (asc/desc).

 None

Returns:

Name Type Description
LocationsResponse LocationsResponse

An instance representing the list of retrieved locations.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/locations.py 
 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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
def list(
    self,
    page: int = 1,
    limit: int = 100,
    radius: int | None = None,
    coordinates: Tuple[float, float] | None = None,
    bbox: Tuple[float, float, float, float] | None = None,
    providers_id: int | list[int] | None = None,
    countries_id: int | list[int] | None = None,
    parameters_id: int | list[int] | None = None,
    licenses_id: int | list[int] | None = None,
    iso: str | None = None,
    monitor: bool | None = None,
    mobile: bool | None = None,
    order_by: str | None = None,
    sort_order: 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)
    * `licenses_id` - Filters results by selected licenses 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.
        licenses_id: Single licenses 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:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        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,
        licenses_id=licenses_id,
        iso=iso,
        monitor=monitor,
        mobile=mobile,
        order_by=order_by,
        sort_order=sort_order,
    )

    locations_response = self._client._get("/locations", params=params)
    return LocationsResponse.read_response(locations_response)

sensors(locations_id)

Retrieve sensors from a location.

Parameters:

Name Type Description Default
locations_id int

The locations ID of the location to retrieve.

 required

Returns:

Name Type Description
SensorsResponse SensorsResponse

An instance representing the retrieved latest results.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/locations.py 
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def sensors(self, locations_id: int) -> SensorsResponse:
    """Retrieve sensors from a location.

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

    Returns:
        SensorsResponse: An instance representing the retrieved latest results.

    Raises:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    sensors = self._client._get(f"/locations/{locations_id}/sensors")
    return SensorsResponse.read_response(sensors)

Measurements

Provides methods to retrieve the measurements resource from the OpenAQ API.

Source code in openaq/_sync/models/measurements.py 
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
class Measurements(SyncResourceBase):
    """Provides methods to retrieve the measurements resource from the OpenAQ API."""

    def list(
        self,
        sensors_id: int,
        data: Data | None = None,
        rollup: Rollup | None = None,
        datetime_from: datetime.datetime | str | None = "2016-10-10",
        datetime_to: datetime.datetime | str | None = None,
        page: int = 1,
        limit: int = 1000,
    ) -> MeasurementsResponse:
        """List air quality measurements based on provided filters.

        Provides the ability to return sensor measurements resource by date range,
        data periods and aggregation rollups, and pagination settings.

        * `sensors_id` - Filters measurements to a specific sensors ID (required)
        * `data` - the base measurement unit to query. options are 'measurements', 'hours', 'days', 'years'
        * `rollup` - the period by which to rollup the base measurement data. Options are 'hourly', 'daily', 'yearly'
        * `datetime_from` - Declare a start time for data retrieval
        * `datetime_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

        Args:
            sensors_id: The ID of the sensor for which measurements should be retrieved.
            data: The base measurement unit to query
            rollup: The period by which to rollup the base measurement data.
            datetime_from: Starting date for the measurement retrieval. Can be a datetime object or ISO-8601 formatted date or datetime string.
            datetime_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.

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

        Raises:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        params = build_query_params(
            page=page,
            limit=limit,
            datetime_from=datetime_from,
            datetime_to=datetime_to,
        )
        path = build_measurements_path(sensors_id, data, rollup)

        measurements_response = self._client._get(path, params=params)

        return MeasurementsResponse.read_response(measurements_response)

list(sensors_id, data=None, rollup=None, datetime_from='2016-10-10', datetime_to=None, page=1, limit=1000)

List air quality measurements based on provided filters.

Provides the ability to return sensor measurements resource by date range, data periods and aggregation rollups, and pagination settings.

  • sensors_id - Filters measurements to a specific sensors ID (required)
  • data - the base measurement unit to query. options are 'measurements', 'hours', 'days', 'years'
  • rollup - the period by which to rollup the base measurement data. Options are 'hourly', 'daily', 'yearly'
  • datetime_from - Declare a start time for data retrieval
  • datetime_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:

Name Type Description Default
sensors_id int

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

 required
data Data | None

The base measurement unit to query

 None
rollup Rollup | None

The period by which to rollup the base measurement data.

 None
datetime_from 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'
datetime_to 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

Returns:

Name Type Description
MeasurementsResponse MeasurementsResponse

An instance representing the list of retrieved air quality measurements.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/measurements.py 
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
def list(
    self,
    sensors_id: int,
    data: Data | None = None,
    rollup: Rollup | None = None,
    datetime_from: datetime.datetime | str | None = "2016-10-10",
    datetime_to: datetime.datetime | str | None = None,
    page: int = 1,
    limit: int = 1000,
) -> MeasurementsResponse:
    """List air quality measurements based on provided filters.

    Provides the ability to return sensor measurements resource by date range,
    data periods and aggregation rollups, and pagination settings.

    * `sensors_id` - Filters measurements to a specific sensors ID (required)
    * `data` - the base measurement unit to query. options are 'measurements', 'hours', 'days', 'years'
    * `rollup` - the period by which to rollup the base measurement data. Options are 'hourly', 'daily', 'yearly'
    * `datetime_from` - Declare a start time for data retrieval
    * `datetime_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

    Args:
        sensors_id: The ID of the sensor for which measurements should be retrieved.
        data: The base measurement unit to query
        rollup: The period by which to rollup the base measurement data.
        datetime_from: Starting date for the measurement retrieval. Can be a datetime object or ISO-8601 formatted date or datetime string.
        datetime_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.

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

    Raises:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    params = build_query_params(
        page=page,
        limit=limit,
        datetime_from=datetime_from,
        datetime_to=datetime_to,
    )
    path = build_measurements_path(sensors_id, data, rollup)

    measurements_response = self._client._get(path, params=params)

    return MeasurementsResponse.read_response(measurements_response)

Countries

Provides methods to retrieve the country resource 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
84
85
86
87
88
89
90
91
92
93
94
95
class Countries(SyncResourceBase):
    """Provides methods to retrieve the country resource 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:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        country_response = self._client._get(f"/countries/{countries_id}")
        return CountriesResponse.read_response(country_response)

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        order_by: str | None = None,
        sort_order: str | None = None,
        parameters_id: int | None = None,
        providers_id: int | None = 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:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            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_response = self._client._get("/countries", params=params)
        return CountriesResponse.read_response(countries_response)

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
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
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
31
32
33
34
35
36
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:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    country_response = self._client._get(f"/countries/{countries_id}")
    return CountriesResponse.read_response(country_response)

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 | None

Order by operators for results.

 None
sort_order str | None

Sort order (asc/desc).

 None
parameters_id int | None

Single parameters ID or an array of IDs.

 None
providers_id int | None

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
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/countries.py 
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
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str | None = None,
    sort_order: str | None = None,
    parameters_id: int | None = None,
    providers_id: int | None = 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:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        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_response = self._client._get("/countries", params=params)
    return CountriesResponse.read_response(countries_response)

Instruments

Provides methods to retrieve the instrument resource 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
73
74
75
76
77
78
79
80
81
82
83
84
class Instruments(SyncResourceBase):
    """Provides methods to retrieve the instrument resource 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:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        instrument_response = self._client._get(f"/instruments/{providers_id}")
        return InstrumentsResponse.read_response(instrument_response)

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        order_by: str | None = None,
        sort_order: str | None = 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:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            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_response = self._client._get("/instruments", params=params)
        return InstrumentsResponse.read_response(instruments_response)

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
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
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
31
32
33
34
35
36
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:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    instrument_response = self._client._get(f"/instruments/{providers_id}")
    return InstrumentsResponse.read_response(instrument_response)

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 | None

Order by operators for results.

 None
sort_order str | None

Sort order (asc/desc).

 None

Returns:

Name Type Description
InstrumentsResponse InstrumentsResponse

An instance representing the list of retrieved instruments.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/instruments.py 
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
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str | None = None,
    sort_order: str | None = 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:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        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_response = self._client._get("/instruments", params=params)
    return InstrumentsResponse.read_response(instruments_response)

Manufacturers

Provides methods to retrieve the manufacturer resource 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
 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
class Manufacturers(SyncResourceBase):
    """Provides methods to retrieve the manufacturer resource 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:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        manufacturer_response = self._client._get(f"/manufacturers/{manufacturers_id}")
        return ManufacturersResponse.read_response(manufacturer_response)

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        order_by: str | None = None,
        sort_order: str | None = 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:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            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
        )

        manufacturer_response = self._client._get("/manufacturers", params=params)
        return ManufacturersResponse.read_response(manufacturer_response)

    def instruments(self, manufacturers_id: int) -> InstrumentsResponse:
        """Retrieve instruments of a manufacturer by ID.

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

        Returns:
            InstrumentsResponse: An instance representing the retrieved instruments.

        Raises:
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: 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.
        """
        instruments_response = self._client._get(
            f"/manufacturers/{manufacturers_id}/instruments"
        )
        return InstrumentsResponse.read_response(instruments_response)

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
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
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
31
32
33
34
35
36
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:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    manufacturer_response = self._client._get(f"/manufacturers/{manufacturers_id}")
    return ManufacturersResponse.read_response(manufacturer_response)

instruments(manufacturers_id)

Retrieve instruments of a manufacturer by ID.

Parameters:

Name Type Description Default
manufacturers_id int

The manufacturers ID of the manufacturer to retrieve.

 required

Returns:

Name Type Description
InstrumentsResponse InstrumentsResponse

An instance representing the retrieved instruments.

Raises:

Type Description
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

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 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def instruments(self, manufacturers_id: int) -> InstrumentsResponse:
    """Retrieve instruments of a manufacturer by ID.

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

    Returns:
        InstrumentsResponse: An instance representing the retrieved instruments.

    Raises:
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: 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.
    """
    instruments_response = self._client._get(
        f"/manufacturers/{manufacturers_id}/instruments"
    )
    return InstrumentsResponse.read_response(instruments_response)

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 | None

Order by operators for results.

 None
sort_order str | None

Sort order (asc/desc).

 None

Returns:

Name Type Description
ManufacturersResponse ManufacturersResponse

An instance representing the list of retrieved manufacturers.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/manufacturers.py 
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
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str | None = None,
    sort_order: str | None = 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:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        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
    )

    manufacturer_response = self._client._get("/manufacturers", params=params)
    return ManufacturersResponse.read_response(manufacturer_response)

Licenses

Provides methods to retrieve the license resource from the OpenAQ API.

Source code in openaq/_sync/models/licenses.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
class Licenses(SyncResourceBase):
    """Provides methods to retrieve the license resource from the OpenAQ API."""

    def get(self, licenses_id: int) -> LicensesResponse:
        """Retrieve a specific license by its licenses ID.

        Args:
            licenses_id: The licenses ID of the license to retrieve.

        Returns:
            LicensesReponse: An instance representing the retrieved license.

        Raises:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        license = self._client._get(f"/licenses/{licenses_id}")
        return LicensesResponse.read_response(license)

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        order_by: str | None = None,
        sort_order: str | None = None,
    ) -> LicensesResponse:
        """List licenses 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
        * `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.
            order_by: Order by operators for results.
            sort_order: Sort order (asc/desc).

        Returns:
            LicensesReponse: An instance representing the list of retrieved licenses.

        Raises:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            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,
        )

        licenses = self._client._get("/licenses", params=params)
        return LicensesResponse.read_response(licenses)

get(licenses_id)

Retrieve a specific license by its licenses ID.

Parameters:

Name Type Description Default
licenses_id int

The licenses ID of the license to retrieve.

 required

Returns:

Name Type Description
LicensesReponse LicensesResponse

An instance representing the retrieved license.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/licenses.py 
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
def get(self, licenses_id: int) -> LicensesResponse:
    """Retrieve a specific license by its licenses ID.

    Args:
        licenses_id: The licenses ID of the license to retrieve.

    Returns:
        LicensesReponse: An instance representing the retrieved license.

    Raises:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    license = self._client._get(f"/licenses/{licenses_id}")
    return LicensesResponse.read_response(license)

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

List licenses 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
  • 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
order_by str | None

Order by operators for results.

 None
sort_order str | None

Sort order (asc/desc).

 None

Returns:

Name Type Description
LicensesReponse LicensesResponse

An instance representing the list of retrieved licenses.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/licenses.py 
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
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str | None = None,
    sort_order: str | None = None,
) -> LicensesResponse:
    """List licenses 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
    * `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.
        order_by: Order by operators for results.
        sort_order: Sort order (asc/desc).

    Returns:
        LicensesReponse: An instance representing the list of retrieved licenses.

    Raises:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        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,
    )

    licenses = self._client._get("/licenses", params=params)
    return LicensesResponse.read_response(licenses)

Owners

Provides methods to retrieve the owner resource 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
73
74
75
76
77
78
79
80
81
82
83
84
class Owners(SyncResourceBase):
    """Provides methods to retrieve the owner resource 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:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        owner_response = self._client._get(f"/owners/{owners_id}")
        return OwnersResponse.read_response(owner_response)

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        order_by: str | None = None,
        sort_order: str | None = 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:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            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_response = self._client._get("/owners", params=params)
        return OwnersResponse.read_response(owners_response)

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
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
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
31
32
33
34
35
36
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:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    owner_response = self._client._get(f"/owners/{owners_id}")
    return OwnersResponse.read_response(owner_response)

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 | None

Order by operators for results.

 None
sort_order str | None

Sort order (asc/desc).

 None

Returns:

Name Type Description
OwnersResponse OwnersResponse

An instance representing the list of retrieved owners.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/owners.py 
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
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str | None = None,
    sort_order: str | None = 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:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        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_response = self._client._get("/owners", params=params)
    return OwnersResponse.read_response(owners_response)

Parameters

Provides methods to retrieve the parameter resource 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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
class Parameters(SyncResourceBase):
    """Provides methods to retrieve the parameter resource 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.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: 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_response = self._client._get(f"/parameters/{parameters_id}")
        return ParametersResponse.read_response(parameter_response)

    def latest(self, parameters_id: int) -> LatestResponse:
        """Retrieve latest measurements from a location.

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

        Returns:
            LatestResponse: An instance representing the retrieved latest results.

        Raises:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        latest = self._client._get(f"/parameters/{parameters_id}/latest")
        return LatestResponse.read_response(latest)

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        order_by: str | None = None,
        sort_order: str | None = None,
        parameter_type: str | None = None,
        coordinates: tuple | None = None,
        radius: int | None = None,
        bbox: tuple | None = None,
        iso: str | None = None,
        countries_id: int | None = 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:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            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_response = self._client._get("/parameters", params=params)
        return ParametersResponse.read_response(parameters_response)

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.
NotAuthorizedError

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

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
31
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.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: 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_response = self._client._get(f"/parameters/{parameters_id}")
    return ParametersResponse.read_response(parameter_response)

latest(parameters_id)

Retrieve latest measurements from a location.

Parameters:

Name Type Description Default
parameters_id int

The locations ID of the location to retrieve.

 required

Returns:

Name Type Description
LatestResponse LatestResponse

An instance representing the retrieved latest results.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/parameters.py 
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
def latest(self, parameters_id: int) -> LatestResponse:
    """Retrieve latest measurements from a location.

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

    Returns:
        LatestResponse: An instance representing the retrieved latest results.

    Raises:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    latest = self._client._get(f"/parameters/{parameters_id}/latest")
    return LatestResponse.read_response(latest)

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 | None

pollutant or meteorological.

 None
radius int | None

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

 None
coordinates tuple | None

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

 None
bbox tuple | None

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

 None
iso str | None

2 letter ISO 3166-alpha-2 country code.

 None
countries_id int | None

Single countries ID or an array of IDs.

 None
order_by str | None

Order by operators for results.

 None
sort_order str | None

Sort order (asc/desc).

 None

Returns:

Name Type Description
ParametersResponse ParametersResponse

An instance representing the list of retrieved parameters.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/parameters.py 
 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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str | None = None,
    sort_order: str | None = None,
    parameter_type: str | None = None,
    coordinates: tuple | None = None,
    radius: int | None = None,
    bbox: tuple | None = None,
    iso: str | None = None,
    countries_id: int | None = 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:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        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_response = self._client._get("/parameters", params=params)
    return ParametersResponse.read_response(parameters_response)

Providers

Provides methods to retrieve provider resource 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
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
class Providers(SyncResourceBase):
    """Provides methods to retrieve provider resource 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:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        provider_response = self._client._get(f"/providers/{providers_id}")
        return ProvidersResponse.read_response(provider_response)

    def list(
        self,
        page: int = 1,
        limit: int = 1000,
        order_by: str | None = None,
        sort_order: str | None = None,
        parameters_id: int | None = None,
        monitor: bool | None = None,
        coordinates: tuple | None = None,
        radius: int | None = None,
        bbox: tuple | None = None,
        iso: str | None = None,
        countries_id: int | None = 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:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            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_response = self._client._get("/providers", params=params)
        return ProvidersResponse.read_response(providers_response)

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.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/providers.py 
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
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:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    provider_response = self._client._get(f"/providers/{providers_id}")
    return ProvidersResponse.read_response(provider_response)

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 | None

Single parameters ID or an array of IDs.

 None
monitor bool | None

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

 None
radius int | None

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

 None
coordinates tuple | None

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

 None
bbox tuple | None

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

 None
iso str | None

2 letter ISO 3166-alpha-2 country code.

 None
countries_id int | None

Single countries ID or an array of IDs.

 None
order_by str | None

Order by operators for results.

 None
sort_order str | None

Sort order (asc/desc).

 None

Returns:

Name Type Description
ProvidersResponse ProvidersResponse

An instance representing the list of retrieved providers.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/providers.py 
 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,
    order_by: str | None = None,
    sort_order: str | None = None,
    parameters_id: int | None = None,
    monitor: bool | None = None,
    coordinates: tuple | None = None,
    radius: int | None = None,
    bbox: tuple | None = None,
    iso: str | None = None,
    countries_id: int | None = 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:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        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_response = self._client._get("/providers", params=params)
    return ProvidersResponse.read_response(providers_response)

Sensors

Provides methods to retrieve the sensor resource from the OpenAQ API.

Source code in openaq/_sync/models/sensors.py 
 6
 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
class Sensors(SyncResourceBase):
    """Provides methods to retrieve the sensor resource from the OpenAQ API."""

    def get(self, sensors_id: int) -> SensorsResponse:
        """Retrieve specific sensor data by its sensors ID.

        Args:
            sensors_id: The sensors ID of the sensor to retrieve.

        Returns:
            SensorsResponse: An instance representing the retrieved sensor.

        Raises:
            IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
            ApiKeyMissingError: Authentication error, missing API Key credentials.
            BadRequestError: Raised for HTTP 400 error, indicating a client request error.
            NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
            ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
            NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
            TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
            ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
            RateLimitError: Raised when managed client exceeds rate limit.
            HTTPRateLimitError: 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.
            BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
            ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
            GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
        """
        sensor_response = self._client._get(f"/sensors/{sensors_id}")
        return SensorsResponse.read_response(sensor_response)

get(sensors_id)

Retrieve specific sensor data by its sensors ID.

Parameters:

Name Type Description Default
sensors_id int

The sensors ID of the sensor to retrieve.

 required

Returns:

Name Type Description
SensorsResponse SensorsResponse

An instance representing the retrieved sensor.

Raises:

Type Description
IdentifierOutOfBoundsError

Client validation error, identifier outside support int32 range.
ApiKeyMissingError

Authentication error, missing API Key credentials.
BadRequestError

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

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

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

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

Raised for HTTP 408 error, indicating the request has timed out.
ValidationError

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

Raised when managed client exceeds rate limit.
HTTPRateLimitError

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.
BadGatewayError

Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
ServiceUnavailableError

Raised for HTTP 503, indicating that the server is not ready to handle the request.
GatewayTimeoutError

Raised for HTTP 504 error, indicating a gateway timeout.
Source code in openaq/_sync/models/sensors.py 
 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
def get(self, sensors_id: int) -> SensorsResponse:
    """Retrieve specific sensor data by its sensors ID.

    Args:
        sensors_id: The sensors ID of the sensor to retrieve.

    Returns:
        SensorsResponse: An instance representing the retrieved sensor.

    Raises:
        IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
        ApiKeyMissingError: Authentication error, missing API Key credentials.
        BadRequestError: Raised for HTTP 400 error, indicating a client request error.
        NotAuthorizedError: Raised for HTTP 401 error, indicating the client is not authorized.
        ForbiddenError: Raised for HTTP 403 error, indicating the request is forbidden.
        NotFoundError: Raised for HTTP 404 error, indicating a resource is not found.
        TimeoutError: Raised for HTTP 408 error, indicating the request has timed out.
        ValidationError: Raised for HTTP 422 error, indicating invalid request parameters.
        RateLimitError: Raised when managed client exceeds rate limit.
        HTTPRateLimitError: 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.
        BadGatewayError: Raised for HTTP 502, indicating that the gateway or proxy received an invalid response from the upstream server.
        ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
        GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
    """
    sensor_response = self._client._get(f"/sensors/{sensors_id}")
    return SensorsResponse.read_response(sensor_response)