Skip to content

OpenAQ

OpenAQ

OpenAQ synchronous client.

Parameters:

Name Type Description Default
api_key str | None

The API key for accessing the service.

 None
headers Mapping[str, str] | None

Additional headers to be sent with the request.

 None
auto_wait bool

Whether to automatically wait when rate limited. Defaults to True.

 True
base_url str

The base URL for the API endpoint.

 DEFAULT_BASE_URL
transport Transport | None

The transport instance for making HTTP requests. For internal use.

 None
rate_limit_override int | None

Override the default rate limit capacity of 60 requests per minute. Useful for accounts with a higher rate limit. Defaults to 60.

 None
timeout float | Timeout | None

Timeout configuration for HTTP requests. Defaults to 5 seconds for connection, write, and pool, and 8 seconds for read to account for the API's 6 second processing limit. Pass None for no timeout.

 DEFAULT_TIMEOUT
limits Limits

Connection pool limits for the HTTP transport. Defaults to 20 maximum connections with 10 keepalive connections. Keepalive connections expire after 30 seconds.

 DEFAULT_LIMITS
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 named 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 rate limit exceeded and auto_wait is False.
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 
 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
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
class OpenAQ(BaseClient[Transport]):
    """OpenAQ synchronous client.

    Args:
        api_key: The API key for accessing the service.
        headers: Additional headers to be sent with the request.
        auto_wait: Whether to automatically wait when rate limited. Defaults to
            True.
        base_url: The base URL for the API endpoint.
        transport: The transport instance for making HTTP requests. For internal
            use.
        rate_limit_override: Override the default rate limit capacity of 60
            requests per minute.
            Useful for accounts with a higher rate limit. Defaults to 60.
        timeout: Timeout configuration for HTTP requests. Defaults to 5 seconds
            for connection, write, and pool, and 8 seconds for read to account
            for the API's 6 second processing limit. Pass None for no timeout.
        limits: Connection pool limits for the HTTP transport. Defaults to 20
            maximum connections with 10 keepalive connections. Keepalive
            connections expire after 30 seconds.

    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
        named `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 rate limit exceeded and auto_wait is False.
        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.

    """

    _rate_limit_reset_datetime: datetime
    _rate_limit_remaining: float
    _rate_limit_capacity: float
    _current_window_id: str

    def __init__(
        self,
        api_key: str | None = None,
        headers: Mapping[str, str] | None = None,
        auto_wait: bool = True,
        base_url: str = DEFAULT_BASE_URL,
        transport: Transport | None = None,
        timeout: float | httpx.Timeout | None = DEFAULT_TIMEOUT,
        limits: httpx.Limits = DEFAULT_LIMITS,
        rate_limit_override: int | None = None,
    ) -> None:
        if transport is None:
            transport = Transport(timeout=timeout, limits=limits)
        if headers is None:
            headers = {}
        super().__init__(transport, headers, api_key, auto_wait, base_url)
        self._user_agent = (
            f"openaq-python-sync-{__version__}-{platform.python_version()}"
        )
        self.resolve_headers()
        rate_limit = rate_limit_override if rate_limit_override is not None else 60
        self._rate_limit_capacity = float(rate_limit)
        self._rate_limit_reset_datetime = datetime.min
        self._rate_limit_remaining = self._rate_limit_capacity
        self._current_window_id = datetime.now().strftime("%Y%m%d%H%M")

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

    @property
    def _rate_limit_reset_seconds(self) -> int:
        return int((self._rate_limit_reset_datetime - datetime.now()).total_seconds())

    def _is_rate_limited(self) -> bool:
        return (
            self._rate_limit_remaining == 0
            and self._rate_limit_reset_datetime > datetime.now()
        )

    def _check_rate_limit(self) -> None:
        now = datetime.now()
        window_id = now.strftime("%Y%m%d%H%M")

        if self._current_window_id != window_id:
            self._rate_limit_remaining = self._rate_limit_capacity
            self._current_window_id = window_id
            return

        if self._rate_limit_remaining <= 0:
            if self._auto_wait:
                self._wait_for_rate_limit_reset()
                self._rate_limit_remaining = self._rate_limit_capacity
                self._current_window_id = datetime.now().strftime("%Y%m%d%H%M")
            else:
                message = f"Rate limit exceeded. Limit resets in {self._rate_limit_reset_seconds} seconds"
                logger.error(message)
                raise RateLimitError(message)

    def _set_rate_limit(self, headers: httpx.Headers) -> None:
        rate_limit_remaining = self._get_int_header(headers, 'x-ratelimit-remaining', 0)
        rate_limit_reset_seconds = self._get_int_header(
            headers, 'x-ratelimit-reset', 60
        )
        now = (datetime.now() + timedelta(seconds=0.5)).replace(microsecond=0)
        rate_limit_reset_datetime = now + timedelta(seconds=rate_limit_reset_seconds)
        self._rate_limit_remaining = rate_limit_remaining
        self._rate_limit_reset_datetime = rate_limit_reset_datetime

    def _wait_for_rate_limit_reset(self) -> None:
        """Wait until the rate limit resets."""
        wait_seconds = self._rate_limit_reset_seconds
        if wait_seconds > 0:
            logger.info(f"Rate limit hit. Waiting {wait_seconds} seconds for reset.")
            time.sleep(wait_seconds)

    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:
        """Execute an HTTP request with rate limit handling.

        Checks rate limits before making the request. If auto_wait is enabled
        and rate limited, waits for the limit to reset. Otherwise raises
        RateLimitError if rate limited.

        Args:
            method: HTTP method (get, post, etc.).
            path: API endpoint path.
            params: Query parameters.
            headers: Additional request headers.

        Returns:
            HTTP response object.

        Raises:
            RateLimitError: If rate limited and auto_wait is False.
        """
        self._check_rate_limit()
        self._rate_limit_remaining -= 1
        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:
        """Make a GET request to the API.

        Args:
            path: API endpoint path.
            params: Query parameters.
            headers: HTTP request headers.

        Returns:
            HTTP response object.
        """
        return self._do("get", path, params=params, headers=headers)

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

    def __enter__(self) -> OpenAQ:
        """Enter the context manager."""
        return self

    def __exit__(
        self,
        exc_type: type[BaseException] | None,
        exc_val: BaseException | None,
        exc_tb: TracebackType | None,
    ) -> None:
        """Exit the context manager and close the connection."""
        self.close()

__enter__()

Enter the context manager.

Source code in openaq/_sync/client.py 
233
234
235
def __enter__(self) -> OpenAQ:
    """Enter the context manager."""
    return self

__exit__(exc_type, exc_val, exc_tb)

Exit the context manager and close the connection.

Source code in openaq/_sync/client.py 
237
238
239
240
241
242
243
244
def __exit__(
    self,
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) -> None:
    """Exit the context manager and close the connection."""
    self.close()

close()

Close the transport connection.

Source code in openaq/_sync/client.py 
229
230
231
def close(self) -> None:
    """Close the 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
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
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,
        instruments_id: int | list[int] | None = None,
        manufacturers_id: int | list[int] | None = None,
        owners_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: Page number to retrieve, must be greater than zero.
                Page count is calculated as total locations / limit.
            limit: Number of results per page. Must be between 1 and 1,000.
            radius: Search radius in meters around the coordinates point.
                Must be between 1 and 25,000 (25km).
            coordinates: WGS 84 coordinate pair as (latitude, longitude).
            bbox: Geospatial bounding box as (min_x, min_y, max_x, max_y)
                in WGS 84 coordinates. Limited to four decimal places.
            providers_id: Filter locations by provider ID(s).
                Accepts a single ID or list of IDs.
            countries_id: Filter locations by country ID(s).
                Accepts a single ID or list of IDs.
            parameters_id: Filter locations by parameter ID(s).
                Accepts a single ID or list of IDs.
            licenses_id: Filter locations by license ID(s).
                Accepts a single ID or list of IDs.
            instruments_id: Filter locations by instrument ID(s).
                Accepts a single ID or list of IDs.
            manufacturers_id: Filter locations by manufacturer ID(s).
                Accepts a single ID or list of IDs.
            owners_id: Filter locations by owner ID(s).
                Accepts a single ID or list of IDs.
            iso: Filter locations by 2-letter ISO 3166-alpha-2 country code.
            monitor: Filter by monitor type. True for reference grade monitors,
                False for air sensors.
            mobile: Filter by mobility. True for mobile locations,
                False for stationary locations.
            order_by: Field name to sort results by.
            sort_order: Sort direction, either 'asc' or '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)
        countries_id, iso = validate_countries_query_parameters(countries_id, iso)
        if providers_id is not None:
            providers_id = validate_integer_or_list_integer_params(
                'providers_id', providers_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 instruments_id:
            instruments_id = validate_integer_or_list_integer_params(
                'instruments_id', instruments_id
            )
        if manufacturers_id:
            manufacturers_id = validate_integer_or_list_integer_params(
                'manufacturers_id', manufacturers_id
            )
        if owners_id:
            owners_id = validate_integer_or_list_integer_params('owners_id', owners_id)
        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,
            instruments_id=instruments_id,
            manufacturers_id=manufacturers_id,
            owner_contacts_id=owners_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, instruments_id=None, manufacturers_id=None, owners_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

Page number to retrieve, must be greater than zero. Page count is calculated as total locations / limit.

 1
limit int

Number of results per page. Must be between 1 and 1,000.

 100
radius int | None

Search radius in meters around the coordinates point. Must be between 1 and 25,000 (25km).

 None
coordinates tuple[float, float] | None

WGS 84 coordinate pair as (latitude, longitude).

 None
bbox tuple[float, float, float, float] | None

Geospatial bounding box as (min_x, min_y, max_x, max_y) in WGS 84 coordinates. Limited to four decimal places.

 None
providers_id int | list[int] | None

Filter locations by provider ID(s). Accepts a single ID or list of IDs.

 None
countries_id int | list[int] | None

Filter locations by country ID(s). Accepts a single ID or list of IDs.

 None
parameters_id int | list[int] | None

Filter locations by parameter ID(s). Accepts a single ID or list of IDs.

 None
licenses_id int | list[int] | None

Filter locations by license ID(s). Accepts a single ID or list of IDs.

 None
instruments_id int | list[int] | None

Filter locations by instrument ID(s). Accepts a single ID or list of IDs.

 None
manufacturers_id int | list[int] | None

Filter locations by manufacturer ID(s). Accepts a single ID or list of IDs.

 None
owners_id int | list[int] | None

Filter locations by owner ID(s). Accepts a single ID or list of IDs.

 None
iso str | None

Filter locations by 2-letter ISO 3166-alpha-2 country code.

 None
monitor bool | None

Filter by monitor type. True for reference grade monitors, False for air sensors.

 None
mobile bool | None

Filter by mobility. True for mobile locations, False for stationary locations.

 None
order_by str | None

Field name to sort results by.

 None
sort_order SortOrder | None

Sort direction, either 'asc' or '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
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
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,
    instruments_id: int | list[int] | None = None,
    manufacturers_id: int | list[int] | None = None,
    owners_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: Page number to retrieve, must be greater than zero.
            Page count is calculated as total locations / limit.
        limit: Number of results per page. Must be between 1 and 1,000.
        radius: Search radius in meters around the coordinates point.
            Must be between 1 and 25,000 (25km).
        coordinates: WGS 84 coordinate pair as (latitude, longitude).
        bbox: Geospatial bounding box as (min_x, min_y, max_x, max_y)
            in WGS 84 coordinates. Limited to four decimal places.
        providers_id: Filter locations by provider ID(s).
            Accepts a single ID or list of IDs.
        countries_id: Filter locations by country ID(s).
            Accepts a single ID or list of IDs.
        parameters_id: Filter locations by parameter ID(s).
            Accepts a single ID or list of IDs.
        licenses_id: Filter locations by license ID(s).
            Accepts a single ID or list of IDs.
        instruments_id: Filter locations by instrument ID(s).
            Accepts a single ID or list of IDs.
        manufacturers_id: Filter locations by manufacturer ID(s).
            Accepts a single ID or list of IDs.
        owners_id: Filter locations by owner ID(s).
            Accepts a single ID or list of IDs.
        iso: Filter locations by 2-letter ISO 3166-alpha-2 country code.
        monitor: Filter by monitor type. True for reference grade monitors,
            False for air sensors.
        mobile: Filter by mobility. True for mobile locations,
            False for stationary locations.
        order_by: Field name to sort results by.
        sort_order: Sort direction, either 'asc' or '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)
    countries_id, iso = validate_countries_query_parameters(countries_id, iso)
    if providers_id is not None:
        providers_id = validate_integer_or_list_integer_params(
            'providers_id', providers_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 instruments_id:
        instruments_id = validate_integer_or_list_integer_params(
            'instruments_id', instruments_id
        )
    if manufacturers_id:
        manufacturers_id = validate_integer_or_list_integer_params(
            'manufacturers_id', manufacturers_id
        )
    if owners_id:
        owners_id = validate_integer_or_list_integer_params('owners_id', owners_id)
    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,
        instruments_id=instruments_id,
        manufacturers_id=manufacturers_id,
        owner_contacts_id=owners_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 
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
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
 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
class Measurements(SyncResourceBase):
    """Provides methods to retrieve the measurements resource from the OpenAQ API."""

    @overload
    def list(
        self,
        sensors_id: int,
        data: DatetimeData,
        rollup: Rollup | None = None,
        datetime_from: datetime.datetime | datetime.date | str | None = None,
        datetime_to: datetime.datetime | datetime.date | str | None = None,
        date_from: None = None,
        date_to: None = None,
        page: int = 1,
        limit: int = 1000,
    ) -> MeasurementsResponse: ...

    @overload
    def list(
        self,
        sensors_id: int,
        data: DateData,
        rollup: Rollup | None = None,
        datetime_from: None = None,
        datetime_to: None = None,
        date_from: datetime.date | str | None = None,
        date_to: datetime.date | str | None = None,
        page: int = 1,
        limit: int = 1000,
    ) -> MeasurementsResponse: ...

    def list(
        self,
        sensors_id: int,
        data: Data,
        rollup: Rollup | None = None,
        datetime_from: datetime.datetime | datetime.date | str | None = None,
        datetime_to: datetime.datetime | datetime.date | str | None = None,
        date_from: datetime.date | str | None = None,
        date_to: datetime.date | 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 datetime for the measurement retrieval. Can be a datetime.datetime object, datetime.date object, or ISO-8601 formatted string. Only used with data='measurements' or data='hours'.
            datetime_to: Ending datetime for the measurement retrieval. Can be a datetime.datetime object, datetime.date object, or ISO-8601 formatted string. Only used with data='measurements' or data='hours'.
            date_from: Starting date for the measurement retrieval. Can be a datetime.date object or ISO-8601 formatted date string. Only used with data='days' or data='years'.
            date_to: Ending date for the measurement retrieval. Can be a datetime.date object or ISO-8601 formatted date string. Only used with data='days' or data='years'.
            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)

        data, rollup = validate_data_rollup_compatibility(data, rollup)
        datetime_from, datetime_to, date_from, date_to = validate_datetime_params(
            data, datetime_from, datetime_to, date_from, date_to
        )
        params = build_query_params(
            page=page,
            limit=limit,
            datetime_from=datetime_from,
            datetime_to=datetime_to,
            date_from=date_from,
            date_to=date_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, rollup=None, datetime_from=None, datetime_to=None, date_from=None, date_to=None, page=1, limit=1000) 

list(sensors_id: int, data: DatetimeData, rollup: Rollup | None = None, datetime_from: datetime.datetime | datetime.date | str | None = None, datetime_to: datetime.datetime | datetime.date | str | None = None, date_from: None = None, date_to: None = None, page: int = 1, limit: int = 1000) -> MeasurementsResponse

list(sensors_id: int, data: DateData, rollup: Rollup | None = None, datetime_from: None = None, datetime_to: None = None, date_from: datetime.date | str | None = None, date_to: datetime.date | str | None = None, page: int = 1, limit: int = 1000) -> MeasurementsResponse

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

The base measurement unit to query

 required
rollup Rollup | None

The period by which to rollup the base measurement data.

 None
datetime_from datetime | date | str | None

Starting datetime for the measurement retrieval. Can be a datetime.datetime object, datetime.date object, or ISO-8601 formatted string. Only used with data='measurements' or data='hours'.

 None
datetime_to datetime | date | str | None

Ending datetime for the measurement retrieval. Can be a datetime.datetime object, datetime.date object, or ISO-8601 formatted string. Only used with data='measurements' or data='hours'.

 None
date_from date | str | None

Starting date for the measurement retrieval. Can be a datetime.date object or ISO-8601 formatted date string. Only used with data='days' or data='years'.

 None
date_to date | str | None

Ending date for the measurement retrieval. Can be a datetime.date object or ISO-8601 formatted date string. Only used with data='days' or data='years'.

 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 
 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
def list(
    self,
    sensors_id: int,
    data: Data,
    rollup: Rollup | None = None,
    datetime_from: datetime.datetime | datetime.date | str | None = None,
    datetime_to: datetime.datetime | datetime.date | str | None = None,
    date_from: datetime.date | str | None = None,
    date_to: datetime.date | 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 datetime for the measurement retrieval. Can be a datetime.datetime object, datetime.date object, or ISO-8601 formatted string. Only used with data='measurements' or data='hours'.
        datetime_to: Ending datetime for the measurement retrieval. Can be a datetime.datetime object, datetime.date object, or ISO-8601 formatted string. Only used with data='measurements' or data='hours'.
        date_from: Starting date for the measurement retrieval. Can be a datetime.date object or ISO-8601 formatted date string. Only used with data='days' or data='years'.
        date_to: Ending date for the measurement retrieval. Can be a datetime.date object or ISO-8601 formatted date string. Only used with data='days' or data='years'.
        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)

    data, rollup = validate_data_rollup_compatibility(data, rollup)
    datetime_from, datetime_to, date_from, date_to = validate_datetime_params(
        data, datetime_from, datetime_to, date_from, date_to
    )
    params = build_query_params(
        page=page,
        limit=limit,
        datetime_from=datetime_from,
        datetime_to=datetime_to,
        date_from=date_from,
        date_to=date_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 
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
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 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
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 
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
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 
 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
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)