Introduction to openaq

This guide provides an overview of the key features of the openaq package. For detailed information on the functions provided in the package see the reference section.

For more general documentation on the OpenAQ platform and API see the main OpenAQ documentation site at docs.openaq.org.

Key concepts

API Key

An API key is required for using the OpenAQ API. Register for an account at https://explore.openaq.org/register to get an API key.

By default the OpenAQ R client looks for an API key in the OPENAQ_API_KEY system environment variable. The package also provides a helper function called set_api_key() to set this value.

set_api_key("my-super-secret-openaq-key-1234")

Alternatively, the API key can be set on individual resource function calls e.g.

list_locations(api_key = "my-super-secret-openaq-key-1234")

Setting the API key at an individual function level will always take precedent over an API key set at the environment variable level e.g.

set_api_key("my-super-secret-openaq-key-1234")
list_locations(api_key = "this-is-my-alternate-api-key")

Rate limits

OpenAQ limits the number of API requests you can make in a set time to ensure fair access for all users and prevent overuse.

The OpenAQ API provides custom rate limit headers to indicate the number of requests used, the number remaining, the rate limit allowance, and the number of seconds remaining in the current period until reset. These headers are preserved by default in the openaq package as object attributes on the output date frame:

x_ratelimit_used
x_ratelimit_remaining
x_ratelimit_limit
x_ratelimit_reset

locations <- list_locations(
  limit = 1000,
  parameters_id = 2,
  providers_id = 166
)
print(locations$x_ratelimit_remaining)

# > 59

Read more about the headers and rate limits in the OpenAQ API documentation under Rate Limits

The openaq package provides optional functionality to automatically throttle requests when the rate limit has been reached.

Pagination

The OpenAQ API uses pagination provide access to large amounts of data in “pages”. The number of results is controlled by the limit parameter which defaults 100 and can be configured up to 1000 results. If your query results in more than the page limit you can page through the results using the page parameter. For a limit = 1000 page=1 will contain results 1-1000, page=2 will contain results 1001-2000 an so on. The page and limit are available on any resource that returns more than on results, i.e. “list” functions such as list_locations(), list_licenses() or list_sensor_measurements()

Examples:

list_locations(
  limit = 1000,
  page = 1
)

list_locations(
  limit = 1000,
  page = 2
)

Features

Data frames

All resource functions return a typed data frame by default. If you prefer to work with JSON parsed as a standard list you can toggle off data frame parsing with the as_data_frame function parameter.

list_locations(
  limit = 1000,
  parameters_id = 2,
  providers_id = 166,
  as_data_frame = FALSE
)

#> list()
#> attr(,"meta")
#> attr(,"meta")$name
#> [1] "openaq-api"
#>
#> attr(,"meta")$website
#> [1] "/"
#>
#> attr(,"meta")$page
#> [1] 1
#> ...

as.data.frame methods are provided for all resource classes as well.

JSON results are parsed with the httr2::resp_body_json() function under-the-hood.

Automatic rate limiting

All resource function provide an option to enable automatic rate limiting to ensure you do not exceed account rate limits. You can or course implement your own rate limiting yourself, but the built-in functionality is provided as an easy to use option.

list_locations(
  limit = 1000,
  parameters_id = 2,
  providers_id = 166,
  rate_limit = TRUE
)

This functionality uses the OpenAQ API’s custom rate limit headers and the httr2::req_retry() function under-the-hood.

Debugging

Every resource function provides an optional parameter named DRY_RUN that prevents a full HTTP request to the API and instead prints out a summary of how the requestion would have been made.

list_locations(
  limit = 1000,
  parameters_id = 2,
  providers_id = 166,
  dry_run = TRUE
)

#> GET /v3/locations?providers_id=166&parameters_id=10&limit=1000&page=1 HTTP/1.1
#> Host: api.openaq.org
#> Accept-Encoding: gzip
#> X-API-Key: <REDACTED>
#> User-Agent: openaq-r
#> Content-Type: application/json
#> Accept: application/json

This can be helpful when debugging to identify issues and compare the raw query URL and headers.

This functionality uses the httr2::req_dry_run() function under-the-hood.

Get started with the openaq package

Russ Biggs

2025-01-17