Title: Retrieve 'AirNow' Air Quality Observations and Forecasts
Version: 0.1.0
Description: Retrieve air quality data via the 'AirNow' https://www.airnow.gov/ API.
License: MIT + file LICENSE
URL: https://github.com/briandconnelly/airnow
BugReports: https://github.com/briandconnelly/airnow/issues
Depends: R (≥ 4.1.0)
Imports: cli, glue, httr2, jsonlite, lifecycle, rlang (≥ 1.0.0), tibble
Suggests: covr, lintr, testthat (≥ 3.0.0), withr
Config/testthat/edition: 3
Encoding: UTF-8
RoxygenNote: 7.2.1
NeedsCompilation: no
Packaged: 2022-10-30 02:10:24 UTC; bconnelly
Author: Brian Connelly ORCID iD [aut, cre, cph]
Maintainer: Brian Connelly <bdc@bconnelly.net>
Repository: CRAN
Date/Publication: 2022-10-31 14:10:15 UTC

airnow: Retrieve 'AirNow' Air Quality Observations and Forecasts

Description

Retrieve air quality data via the 'AirNow' https://www.airnow.gov/ API.

Author(s)

Maintainer: Brian Connelly bdc@bconnelly.net (ORCID) [copyright holder]

See Also

Useful links:

Label AQI Values

Description

aqi_color() returns the color that corresponds with the given AQI value.

aqi_descriptor() converts the given AQI value(s) into a descriptive string.

Usage

aqi_color(aqi)

aqi_descriptor(aqi)

Arguments

aqi

An AQI value. AQI is an integer between 0 and 500, inclusive.

Value

aqi_color() returns an RGB hex string

aqi_descriptor() returns a string

Examples

aqi_color(35)
aqi_descriptor(35)

Get air quality data for a given region

Description

get_airnow_area() retrieves the most recent air quality readings from sites in a specified region.

Usage

get_airnow_area(
  box,
  parameters = "pm25",
  start_time = NULL,
  end_time = NULL,
  monitor_type = "both",
  data_type = c("aqi", "concentrations", "both"),
  verbose = FALSE,
  raw_concentrations = FALSE,
  clean_names = TRUE,
  api_key = get_airnow_token()
)

Arguments

box

Four-element numeric vector specifying a bounding box for the region of interest. Format is (minX, minY, maxX, maxY), where X and Y are longitude and latitude, respectively.

parameters

Parameter(s) to return data for. Choices are PM_2.5 (pm25: default), ozone, PM_10 (pm10), CO (co), NO2 (no2), and SO2 (so2).

start_time

Optional. The date and time (UTC) at the start of the time period requested. If specified, end_time must also be given. If not specified, the most recent past hour is used.

end_time

Optional. The date and time (UTC) at the end of the time period requested. If specified, start_time must also be given. If not specified, the following hour is used.

monitor_type

Type of monitor to be returned, either "permanent", "mobile", or "both" (default).

data_type

Type of data to be returned, either "aqi" (default), "concentrations", or "both".

verbose

Logical value indicating whether or not to include additional site information including Site Name, Agency Name, AQS ID, and Full AQS ID (default: FALSE)

raw_concentrations

Logical value indicating whether or not raw hourly concentration data should be included (default: FALSE)

clean_names

Whether or not column names should be cleaned (default: TRUE)

api_key

AirNow API key

Value

A data frame with current air quality conditions

Examples

## Not run: 
# Get air quality data around Washington state
get_airnow_area(box = c(-125.394211, 45.295897, -116.736984, 49.172497))

## End(Not run)

Get current air quality conditions

Description

get_airnow_conditions() retrieves the most recent air quality readings for the given location. Locations can be specified either by ZIP code (zip), or by latitude/longitude. If no data exist for the specified location, an optional search radius for other sites can be specified using distance.

Usage

get_airnow_conditions(
  zip = NULL,
  latitude = NULL,
  longitude = NULL,
  distance = NULL,
  clean_names = TRUE,
  api_key = get_airnow_token()
)

Arguments

zip

ZIP code, a 5-digit numeric string (e.g., "90210")

latitude

Latitude in decimal degrees

longitude

Longitude in decimal degrees

distance

Optional. If no reporting area is associated with the given zip code, current observations from a nearby reporting area within this distance (in miles) will be returned, if available.

clean_names

Whether or not column names should be cleaned (default: TRUE)

api_key

AirNow API key

Value

A data frame with current air quality conditions

Examples

## Not run: 
get_airnow_conditions(zip = "90210")

## End(Not run)

Get air quality forecast

Description

get_airnow_forecast() retrieves forecasted air quality conditions for the given location. Locations can be specified either by ZIP code (zip), or by latitude/longitude. If no data exist for the specified location, an optional search radius for other sites can be specified using distance.

Usage

get_airnow_forecast(
  zip = NULL,
  latitude = NULL,
  longitude = NULL,
  distance = NULL,
  date = NULL,
  clean_names = TRUE,
  api_key = get_airnow_token()
)

Arguments

zip

ZIP code, a 5-digit numeric string (e.g., "90210")

latitude

Latitude in decimal degrees

longitude

Longitude in decimal degrees

distance

Optional. If no reporting area is associated with the given zip code, current observations from a nearby reporting area within this distance (in miles) will be returned, if available.

date

Optional date of forecast. If this is not specified, the current forecast is returned.

clean_names

Whether or not column names should be cleaned (default: TRUE)

api_key

AirNow API key

Value

A data frame with current air quality conditions

Examples

## Not run: 
get_airnow_forecast(zip = "90210")

## End(Not run)

Manage AirNow API Tokens

Description

get_airnow_token() returns the configured AirNow API token or errors if it is not set.

set_airnow_token() sets the AirNow API token to the given value for the current session. To use this permanently, save it as AIRNOW_API_KEY in your ⁠~/.Renviron⁠ file.

Usage

get_airnow_token(ask = is_interactive())

set_airnow_token(token = NULL, ask = is_interactive())

Arguments

ask

Whether or not to ask for the key if none is provided. Note that this only works for interactive sessions.

token

Token to use

Value

get_airnow_token() returns a string containing the current user or group key or an empty string if not set. If the user is not set but ask is TRUE, the user will be prompted for a key.

Examples

## Not run: 
get_airnow_token()

## End(Not run)
## Not run: 
set_airnow_token(token = "4d36e978-e325-11cec1-08002be10318")

## End(Not run)