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

    def _do(
        self,
        method: str,
        path: str,
        *,
        params: (
            httpx.QueryParams | Mapping[str, str | int | float | bool] | None
        ) = None,
        headers: httpx.Headers | Mapping[str, str] | None = None,
    ) -> httpx.Response:
        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: (
            httpx.QueryParams | Mapping[str, str | int | float | bool] | None
        ) = None,
        headers: httpx.Headers | Mapping[str, str] | None = None,
    ) -> httpx.Response:
        return self._do("get", path, params=params, headers=headers)

    def close(self) -> None:
        """Closes transport connection."""
        self.transport.close()

    def __enter__(self) -> OpenAQ:
        return self

    def __exit__(
        self,
        exc_type: type[BaseException] | None,
        exc_val: BaseException | None,
        exc_tb: TracebackType | None,
    ) -> None:
        self.close()

close()

Closes transport connection.

Source code in openaq/_sync/client.py 
112
113
114
def close(self) -> None:
    """Closes transport connection."""
    self.transport.close()

Locations

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

Source code in openaq/_sync/models/locations.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
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
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
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.
        """
        locations_id = validate_integer_id(locations_id)
        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.
        """
        locations_id = validate_integer_id(locations_id)
        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: SortOrder | None = None,
    ) -> LocationsResponse:
        """List locations based on provided filters.

        Args:
            page: The page number, must be greater than zero. Page count is locations found / limit.
            limit: The number of results returned per page. Must be between 1 and 1,000.
            radius: A distance value in meters to search around the given coordinates value, must be between 1 and 25,000 (25km).
            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: Order for sorting results (asc/desc).

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

        Raises:
            InvalidParameterError: Client validation error, query parameter is not correct type or value.
            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.
        """
        page = validate_page_param(page)
        limit = validate_limit_param(limit)
        validate_geospatial_params(coordinates, radius, bbox)
        if providers_id is not None:
            providers_id = validate_integer_or_list_integer_params(
                'providers_id', providers_id
            )
        if countries_id is not None:
             countries_id = validate_integer_or_list_integer_params(
                'countries_id', countries_id
            )
        if parameters_id is not None:
             parameters_id = validate_integer_or_list_integer_params(
                'parameters_id', parameters_id
            )
        if licenses_id is not None:
            licenses_id = validate_integer_or_list_integer_params(
                'licenses_id', licenses_id
            )
        if iso is not None:
            iso = validate_iso_param(iso)
        if monitor is not None:
            monitor = validate_monitor(monitor)
        if mobile is not None:
            mobile = validate_mobile(mobile)
        if sort_order is not None:
            sort_order = validate_sort_order(sort_order)
        if order_by is not None:
            order_by = validate_order_by(order_by)
        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.
        """
        locations_id = validate_integer_id(locations_id)
        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 
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
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.
    """
    locations_id = validate_integer_id(locations_id)
    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 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def 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.
    """
    locations_id = validate_integer_id(locations_id)
    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.

Parameters:

Name Type Description Default
page int

The page number, must be greater than zero. Page count is locations found / limit.

 1
limit int

The number of results returned per page. Must be between 1 and 1,000.

 100
radius int | None

A distance value in meters to search around the given coordinates value, must be between 1 and 25,000 (25km).

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

Order for sorting results (asc/desc).

 None

Returns:

Name Type Description
LocationsResponse LocationsResponse

An instance representing the list of retrieved locations.

Raises:

Type Description
InvalidParameterError

Client validation error, query parameter is not correct type or value.
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 
 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
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: SortOrder | None = None,
) -> LocationsResponse:
    """List locations based on provided filters.

    Args:
        page: The page number, must be greater than zero. Page count is locations found / limit.
        limit: The number of results returned per page. Must be between 1 and 1,000.
        radius: A distance value in meters to search around the given coordinates value, must be between 1 and 25,000 (25km).
        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: Order for sorting results (asc/desc).

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

    Raises:
        InvalidParameterError: Client validation error, query parameter is not correct type or value.
        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.
    """
    page = validate_page_param(page)
    limit = validate_limit_param(limit)
    validate_geospatial_params(coordinates, radius, bbox)
    if providers_id is not None:
        providers_id = validate_integer_or_list_integer_params(
            'providers_id', providers_id
        )
    if countries_id is not None:
         countries_id = validate_integer_or_list_integer_params(
            'countries_id', countries_id
        )
    if parameters_id is not None:
         parameters_id = validate_integer_or_list_integer_params(
            'parameters_id', parameters_id
        )
    if licenses_id is not None:
        licenses_id = validate_integer_or_list_integer_params(
            'licenses_id', licenses_id
        )
    if iso is not None:
        iso = validate_iso_param(iso)
    if monitor is not None:
        monitor = validate_monitor(monitor)
    if mobile is not None:
        mobile = validate_mobile(mobile)
    if sort_order is not None:
        sort_order = validate_sort_order(sort_order)
    if order_by is not None:
        order_by = validate_order_by(order_by)
    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 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
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.
    """
    locations_id = validate_integer_id(locations_id)
    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 
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
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.

        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, must be greater than zero. Page count is measurements found / limit.
            limit: The number of results returned per page. Must be between 1 and 1,000.

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

        Raises:
            InvalidParameterError: Client validation error, query parameter is not correct type or value.
            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_id = validate_integer_id(sensors_id)
        page = validate_page_param(page)
        limit = validate_limit_param(limit)
        if data is not None:
            data = validate_data(data)
        if rollup is not None:
            rollup = validate_rollup(rollup)
        datetime_from, datetime_to = validate_datetime_params(
            datetime_from, datetime_to
        )
        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.

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, must be greater than zero. Page count is measurements found / limit.

 1
limit int

The number of results returned per page. Must be between 1 and 1,000.

 1000

Returns:

Name Type Description
MeasurementsResponse MeasurementsResponse

An instance representing the list of retrieved air quality measurements.

Raises:

Type Description
InvalidParameterError

Client validation error, query parameter is not correct type or value.
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 
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
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.

    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, must be greater than zero. Page count is measurements found / limit.
        limit: The number of results returned per page. Must be between 1 and 1,000.

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

    Raises:
        InvalidParameterError: Client validation error, query parameter is not correct type or value.
        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_id = validate_integer_id(sensors_id)
    page = validate_page_param(page)
    limit = validate_limit_param(limit)
    if data is not None:
        data = validate_data(data)
    if rollup is not None:
        rollup = validate_rollup(rollup)
    datetime_from, datetime_to = validate_datetime_params(
        datetime_from, datetime_to
    )
    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 
 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
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.
        """
        countries_id = validate_integer_id(countries_id)
        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: SortOrder | None = None,
        parameters_id: int | list[int] | None = None,
        providers_id: int | list[int] | None = None,
    ) -> CountriesResponse:
        """List countries based on provided filters.

        Args:
            page: The page number, must be greater than zero. Page count is countries found / limit.
            limit: The number of results returned per page. Must be between 1 and 1,000.
            order_by: Order by operators for results.
            sort_order: Order for sorting results (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:
            InvalidParameterError: Client validation error, query parameter is not correct type or value.
            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.
        """
        page = validate_page_param(page)
        limit = validate_limit_param(limit)
        if sort_order is not None:
            sort_order = validate_sort_order(sort_order)
        if order_by is not None:
            order_by = validate_order_by(order_by)
        if parameters_id is not None:
            parameters_id = validate_integer_or_list_integer_params(
                'parameters_id', parameters_id
            )
        if providers_id is not None:
            providers_id = validate_integer_or_list_integer_params(
                'providers_id', providers_id
            )
        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 
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
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.
    """
    countries_id = validate_integer_id(countries_id)
    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.

Parameters:

Name Type Description Default
page int

The page number, must be greater than zero. Page count is countries found / limit.

 1
limit int

The number of results returned per page. Must be between 1 and 1,000.

 1000
order_by str | None

Order by operators for results.

 None
sort_order SortOrder | None

Order for sorting results (asc/desc).

 None
parameters_id int | list[int] | None

Single parameters ID or an array of IDs.

 None
providers_id int | list[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
InvalidParameterError

Client validation error, query parameter is not correct type or value.
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 
 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
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str | None = None,
    sort_order: SortOrder | None = None,
    parameters_id: int | list[int] | None = None,
    providers_id: int | list[int] | None = None,
) -> CountriesResponse:
    """List countries based on provided filters.

    Args:
        page: The page number, must be greater than zero. Page count is countries found / limit.
        limit: The number of results returned per page. Must be between 1 and 1,000.
        order_by: Order by operators for results.
        sort_order: Order for sorting results (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:
        InvalidParameterError: Client validation error, query parameter is not correct type or value.
        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.
    """
    page = validate_page_param(page)
    limit = validate_limit_param(limit)
    if sort_order is not None:
        sort_order = validate_sort_order(sort_order)
    if order_by is not None:
        order_by = validate_order_by(order_by)
    if parameters_id is not None:
        parameters_id = validate_integer_or_list_integer_params(
            'parameters_id', parameters_id
        )
    if providers_id is not None:
        providers_id = validate_integer_or_list_integer_params(
            'providers_id', providers_id
        )
    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 
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
class Instruments(SyncResourceBase):
    """Provides methods to retrieve the instrument resource from the OpenAQ API."""

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

        Args:
            instruments_id: The instruments 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.
        """
        instruments_id = validate_integer_id(instruments_id)
        instrument_response = self._client._get(f"/instruments/{instruments_id}")
        return InstrumentsResponse.read_response(instrument_response)

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

        Args:
            page: The page number, must be greater than zero. Page count is instruments found / limit.
            limit: The number of results returned per page. Must be between 1 and 1,000.
            order_by: Order by operators for results.
            sort_order: Order for sorting results (asc/desc).

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

        Raises:
            InvalidParameterError: Client validation error, query parameter is not correct type or value.
            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.
        """
        page = validate_page_param(page)
        limit = validate_limit_param(limit)
        if sort_order is not None:
            sort_order = validate_sort_order(sort_order)
        if order_by is not None:
            order_by = validate_order_by(order_by)
        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(instruments_id)

Retrieve specific instrument data by its providers ID.

Parameters:

Name Type Description Default
instruments_id int

The instruments 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 
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
def get(self, instruments_id: int) -> InstrumentsResponse:
    """Retrieve specific instrument data by its providers ID.

    Args:
        instruments_id: The instruments 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.
    """
    instruments_id = validate_integer_id(instruments_id)
    instrument_response = self._client._get(f"/instruments/{instruments_id}")
    return InstrumentsResponse.read_response(instrument_response)

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

List instruments based on provided filters.

Parameters:

Name Type Description Default
page int

The page number, must be greater than zero. Page count is instruments found / limit.

 1
limit int

The number of results returned per page. Must be between 1 and 1,000.

 1000
order_by str | None

Order by operators for results.

 None
sort_order SortOrder | None

Order for sorting results (asc/desc).

 None

Returns:

Name Type Description
InstrumentsResponse InstrumentsResponse

An instance representing the list of retrieved instruments.

Raises:

Type Description
InvalidParameterError

Client validation error, query parameter is not correct type or value.
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 
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
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str | None = None,
    sort_order: SortOrder | None = None,
) -> InstrumentsResponse:
    """List instruments based on provided filters.

    Args:
        page: The page number, must be greater than zero. Page count is instruments found / limit.
        limit: The number of results returned per page. Must be between 1 and 1,000.
        order_by: Order by operators for results.
        sort_order: Order for sorting results (asc/desc).

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

    Raises:
        InvalidParameterError: Client validation error, query parameter is not correct type or value.
        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.
    """
    page = validate_page_param(page)
    limit = validate_limit_param(limit)
    if sort_order is not None:
        sort_order = validate_sort_order(sort_order)
    if order_by is not None:
        order_by = validate_order_by(order_by)
    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 
 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
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.
        """
        manufacturers_id = validate_integer_id(manufacturers_id)
        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: SortOrder | None = None,
    ) -> ManufacturersResponse:
        """List manufacturers based on provided filters.

        Args:
            page: The page number, must be greater than zero. Page count is manfacturers found / limit.
            limit: The number of results returned per page. Must be between 1 and 1,000.
            order_by: Order by operators for results.
            sort_order: Order for sorting results (asc/desc).

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

        Raises:
            InvalidParameterError: Client validation error, query parameter is not correct type or value.
            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.
        """
        page = validate_page_param(page)
        limit = validate_limit_param(limit)
        if sort_order is not None:
            sort_order = validate_sort_order(sort_order)
        if order_by is not None:
            order_by = validate_order_by(order_by)
        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:
            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.
        """
        manufacturers_id = validate_integer_id(manufacturers_id)
        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 
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
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.
    """
    manufacturers_id = validate_integer_id(manufacturers_id)
    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
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 
 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
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:
        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.
    """
    manufacturers_id = validate_integer_id(manufacturers_id)
    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.

Parameters:

Name Type Description Default
page int

The page number, must be greater than zero. Page count is manfacturers found / limit.

 1
limit int

The number of results returned per page. Must be between 1 and 1,000.

 1000
order_by str | None

Order by operators for results.

 None
sort_order SortOrder | None

Order for sorting results (asc/desc).

 None

Returns:

Name Type Description
ManufacturersResponse ManufacturersResponse

An instance representing the list of retrieved manufacturers.

Raises:

Type Description
InvalidParameterError

Client validation error, query parameter is not correct type or value.
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 
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
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str | None = None,
    sort_order: SortOrder | None = None,
) -> ManufacturersResponse:
    """List manufacturers based on provided filters.

    Args:
        page: The page number, must be greater than zero. Page count is manfacturers found / limit.
        limit: The number of results returned per page. Must be between 1 and 1,000.
        order_by: Order by operators for results.
        sort_order: Order for sorting results (asc/desc).

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

    Raises:
        InvalidParameterError: Client validation error, query parameter is not correct type or value.
        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.
    """
    page = validate_page_param(page)
    limit = validate_limit_param(limit)
    if sort_order is not None:
        sort_order = validate_sort_order(sort_order)
    if order_by is not None:
        order_by = validate_order_by(order_by)
    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 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
class 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.
        """
        licenses_id = validate_integer_id(licenses_id)
        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: SortOrder | None = None,
    ) -> LicensesResponse:
        """List licenses based on provided filters.

        Args:
            page: The page number, must be greater than zero. Page count is licenses found / limit.
            limit: The number of results returned per page. Must be between 1 and 1,000.
            order_by: Order by operators for results.
            sort_order: Order for sorting results (asc/desc).

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

        Raises:
            InvalidParameterError: Client validation error, query parameter is not correct type or value.
            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.
        """
        page = validate_page_param(page)
        limit = validate_limit_param(limit)
        if sort_order is not None:
            sort_order = validate_sort_order(sort_order)
        if order_by is not None:
            order_by = validate_order_by(order_by)
        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 
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
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.
    """
    licenses_id = validate_integer_id(licenses_id)
    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.

Parameters:

Name Type Description Default
page int

The page number, must be greater than zero. Page count is licenses found / limit.

 1
limit int

The number of results returned per page. Must be between 1 and 1,000.

 1000
order_by str | None

Order by operators for results.

 None
sort_order SortOrder | None

Order for sorting results (asc/desc).

 None

Returns:

Name Type Description
LicensesReponse LicensesResponse

An instance representing the list of retrieved licenses.

Raises:

Type Description
InvalidParameterError

Client validation error, query parameter is not correct type or value.
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 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str | None = None,
    sort_order: SortOrder | None = None,
) -> LicensesResponse:
    """List licenses based on provided filters.

    Args:
        page: The page number, must be greater than zero. Page count is licenses found / limit.
        limit: The number of results returned per page. Must be between 1 and 1,000.
        order_by: Order by operators for results.
        sort_order: Order for sorting results (asc/desc).

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

    Raises:
        InvalidParameterError: Client validation error, query parameter is not correct type or value.
        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.
    """
    page = validate_page_param(page)
    limit = validate_limit_param(limit)
    if sort_order is not None:
        sort_order = validate_sort_order(sort_order)
    if order_by is not None:
        order_by = validate_order_by(order_by)
    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 
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
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.
        """
        owners_id = validate_integer_id(owners_id)
        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: SortOrder | None = None,
    ) -> OwnersResponse:
        """List owners based on provided filters.

        Args:
            page: The page number, must be greater than zero. Page count is owners found / limit.
            limit: The number of results returned per page. Must be between 1 and 1,000.
            order_by: Order by operators for results.
            sort_order: Order for sorting results (asc/desc).

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

        Raises:
            InvalidParameterError: Client validation error, query parameter is not correct type or value.
            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.
        """
        page = validate_page_param(page)
        limit = validate_limit_param(limit)
        if sort_order is not None:
            sort_order = validate_sort_order(sort_order)
        if order_by is not None:
            order_by = validate_order_by(order_by)
        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 
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
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.
    """
    owners_id = validate_integer_id(owners_id)
    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.

Parameters:

Name Type Description Default
page int

The page number, must be greater than zero. Page count is owners found / limit.

 1
limit int

The number of results returned per page. Must be between 1 and 1,000.

 1000
order_by str | None

Order by operators for results.

 None
sort_order SortOrder | None

Order for sorting results (asc/desc).

 None

Returns:

Name Type Description
OwnersResponse OwnersResponse

An instance representing the list of retrieved owners.

Raises:

Type Description
InvalidParameterError

Client validation error, query parameter is not correct type or value.
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 
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
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str | None = None,
    sort_order: SortOrder | None = None,
) -> OwnersResponse:
    """List owners based on provided filters.

    Args:
        page: The page number, must be greater than zero. Page count is owners found / limit.
        limit: The number of results returned per page. Must be between 1 and 1,000.
        order_by: Order by operators for results.
        sort_order: Order for sorting results (asc/desc).

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

    Raises:
        InvalidParameterError: Client validation error, query parameter is not correct type or value.
        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.
    """
    page = validate_page_param(page)
    limit = validate_limit_param(limit)
    if sort_order is not None:
        sort_order = validate_sort_order(sort_order)
    if order_by is not None:
        order_by = validate_order_by(order_by)
    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 
 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
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.
        """
        parameters_id = validate_integer_id(parameters_id)
        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.
        """
        parameters_id = validate_integer_id(parameters_id)
        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: SortOrder | None = None,
        parameter_type: ParameterType | None = None,
        coordinates: tuple[float, float] | None = None,
        radius: int | None = None,
        bbox: tuple[float, float, float, float] | None = None,
        iso: str | None = None,
        countries_id: int | list[int] | None = None,
    ) -> ParametersResponse:
        """List parameters based on provided filters.

        Args:
            page: The page number, must be greater than zero. Page count is parameters found / limit.
            limit: The number of results returned per page. Must be between 1 and 1,000.
            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: Order for sorting results (asc/desc).

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

        Raises:
            InvalidParameterError: Client validation error, query parameter is not correct type or value.
            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.
        """
        page = validate_page_param(page)
        limit = validate_limit_param(limit)
        validate_geospatial_params(coordinates, radius, bbox)
        if countries_id is not None:
            countries_id = validate_integer_or_list_integer_params(
                'countries_id', countries_id
            )
        if iso is not None:
            iso = validate_iso_param(iso)
        if sort_order is not None:
            sort_order = validate_sort_order(sort_order)
        if order_by is not None:
            order_by = validate_order_by(order_by)
        if parameter_type is not None:
            parameter_type = validate_parameter_type(parameter_type)
        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 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
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.
    """
    parameters_id = validate_integer_id(parameters_id)
    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 
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
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.
    """
    parameters_id = validate_integer_id(parameters_id)
    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.

Parameters:

Name Type Description Default
page int

The page number, must be greater than zero. Page count is parameters found / limit.

 1
limit int

The number of results returned per page. Must be between 1 and 1,000.

 1000
parameter_type ParameterType | None

pollutant or meteorological.

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

2 letter ISO 3166-alpha-2 country code.

 None
countries_id int | list[int] | None

Single countries ID or an array of IDs.

 None
order_by str | None

Order by operators for results.

 None
sort_order SortOrder | None

Order for sorting results (asc/desc).

 None

Returns:

Name Type Description
ParametersResponse ParametersResponse

An instance representing the list of retrieved parameters.

Raises:

Type Description
InvalidParameterError

Client validation error, query parameter is not correct type or value.
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 
 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
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str | None = None,
    sort_order: SortOrder | None = None,
    parameter_type: ParameterType | None = None,
    coordinates: tuple[float, float] | None = None,
    radius: int | None = None,
    bbox: tuple[float, float, float, float] | None = None,
    iso: str | None = None,
    countries_id: int | list[int] | None = None,
) -> ParametersResponse:
    """List parameters based on provided filters.

    Args:
        page: The page number, must be greater than zero. Page count is parameters found / limit.
        limit: The number of results returned per page. Must be between 1 and 1,000.
        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: Order for sorting results (asc/desc).

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

    Raises:
        InvalidParameterError: Client validation error, query parameter is not correct type or value.
        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.
    """
    page = validate_page_param(page)
    limit = validate_limit_param(limit)
    validate_geospatial_params(coordinates, radius, bbox)
    if countries_id is not None:
        countries_id = validate_integer_or_list_integer_params(
            'countries_id', countries_id
        )
    if iso is not None:
        iso = validate_iso_param(iso)
    if sort_order is not None:
        sort_order = validate_sort_order(sort_order)
    if order_by is not None:
        order_by = validate_order_by(order_by)
    if parameter_type is not None:
        parameter_type = validate_parameter_type(parameter_type)
    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 
 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
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.
        """
        providers_id = validate_integer_id(providers_id)
        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: SortOrder | None = None,
        parameters_id: int | list[int] | None = None,
        monitor: bool | None = None,
        coordinates: tuple[float, float] | None = None,
        radius: int | None = None,
        bbox: tuple[float, float, float, float] | None = None,
        iso: str | None = None,
        countries_id: int | list[int] | None = None,
    ) -> ProvidersResponse:
        """List providers based on provided filters.

        Args:
            page: The page number, must be greater than zero. Page count is providers found / limit.
            limit: The number of results returned per page. Must be between 1 and 1,000.
            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, must be between 1 and 25,000 (25km).
            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: Order for sorting results (asc/desc).

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

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

        Raises:
            InvalidParameterError: Client validation error, query parameter is not correct type or value.
            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.
        """
        page = validate_page_param(page)
        limit = validate_limit_param(limit)
        validate_geospatial_params(coordinates, radius, bbox)
        if countries_id is not None:
            countries_id = validate_integer_or_list_integer_params(
                'countries_id', countries_id
            )
        if parameters_id is not None:
            parameters_id = validate_integer_or_list_integer_params(
                'parameters_id', parameters_id
            )
        if iso is not None:
            iso = validate_iso_param(iso)
        if sort_order is not None:
            sort_order = validate_sort_order(sort_order)
        if order_by is not None:
            order_by = validate_order_by(order_by)
        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 
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
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.
    """
    providers_id = validate_integer_id(providers_id)
    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.

Parameters:

Name Type Description Default
page int

The page number, must be greater than zero. Page count is providers found / limit.

 1
limit int

The number of results returned per page. Must be between 1 and 1,000.

 1000
parameters_id int | list[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, must be between 1 and 25,000 (25km).

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

2 letter ISO 3166-alpha-2 country code.

 None
countries_id int | list[int] | None

Single countries ID or an array of IDs.

 None
order_by str | None

Order by operators for results.

 None
sort_order SortOrder | None

Order for sorting results (asc/desc).

 None

Returns:

Name Type Description
ProvidersResponse ProvidersResponse

An instance representing the list of retrieved providers.

Returns:

Name Type Description
ProvidersResponse ProvidersResponse

An instance representing the list of retrieved providers.

Raises:

Type Description
InvalidParameterError

Client validation error, query parameter is not correct type or value.
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 
 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
def list(
    self,
    page: int = 1,
    limit: int = 1000,
    order_by: str | None = None,
    sort_order: SortOrder | None = None,
    parameters_id: int | list[int] | None = None,
    monitor: bool | None = None,
    coordinates: tuple[float, float] | None = None,
    radius: int | None = None,
    bbox: tuple[float, float, float, float] | None = None,
    iso: str | None = None,
    countries_id: int | list[int] | None = None,
) -> ProvidersResponse:
    """List providers based on provided filters.

    Args:
        page: The page number, must be greater than zero. Page count is providers found / limit.
        limit: The number of results returned per page. Must be between 1 and 1,000.
        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, must be between 1 and 25,000 (25km).
        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: Order for sorting results (asc/desc).

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

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

    Raises:
        InvalidParameterError: Client validation error, query parameter is not correct type or value.
        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.
    """
    page = validate_page_param(page)
    limit = validate_limit_param(limit)
    validate_geospatial_params(coordinates, radius, bbox)
    if countries_id is not None:
        countries_id = validate_integer_or_list_integer_params(
            'countries_id', countries_id
        )
    if parameters_id is not None:
        parameters_id = validate_integer_or_list_integer_params(
            'parameters_id', parameters_id
        )
    if iso is not None:
        iso = validate_iso_param(iso)
    if sort_order is not None:
        sort_order = validate_sort_order(sort_order)
    if order_by is not None:
        order_by = validate_order_by(order_by)
    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 
 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
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.
        """
        sensors_id = validate_integer_id(sensors_id)
        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 
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
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.
    """
    sensors_id = validate_integer_id(sensors_id)
    sensor_response = self._client._get(f"/sensors/{sensors_id}")
    return SensorsResponse.read_response(sensor_response)