Create a new PurpleAir synoptic dataset

Download, parse and enhance synoptic data from PurpleAir and return the results as a useful tibble with class pa_synoptic.

Steps include:

1) Download and parse synoptic data

2) Replace variable names with more consistent, more human readable names.

3) Add spatial metadata for each sensor including:

• timezone -- olson timezone

• countryCode -- ISO 3166-1 alpha-2

• stateCode -- ISO 3166-2 alpha-2

4) Convert data types from character to POSIXct and numeric.

Data requests are made with a bounding box determined from the required countryCodes parameter. If a single country is specified and additional stateCodes are specified, the bounding box will be limited to those states. Withing a single state, counties may be used to further limit the data.

If show_only is used to request specific sensors, the countryCodes and stateCodes information is ignored when requesting data. But these are still used to help speed up the assignment of enhanced metadata..

pas_createNew(
  api_key = NULL,
  countryCodes = NULL,
  stateCodes = NULL,
  counties = NULL,
  lookbackDays = 1,
  location_type = 0,
  read_keys = NULL,
  show_only = NULL,
  includePWFSL = TRUE,
  baseUrl = "https://api.purpleair.com/v1/sensors"
)

Arguments

api_key

PurpleAir API Read Key.

countryCodes

ISO 3166-1 alpha-2 country codes used to subset the data. At least one countryCode must be specified.

stateCodes

ISO-3166-2 alpha-2 state codes used to subset the data. Specifying stateCodes is optional.

counties

US county names or 5-digit FIPS codes used to subset the data. Specifying counties is optional.

lookbackDays

Number of days to "look back" for valid data. Data are filtered to only include sensors with data more recent than lookbackDays ago.

location_type

The location_type of the sensors. Possible values are: 0 = Outside, 1 = Inside or NULL = both.

read_keys

Optional comma separated list of sensor read_keys is required for private devices. It is separate to the api_key and each sensor has its own read_key. Submit multiple keys by separating them with a comma (,) character for example: key-one,key-two,key-three.

show_only

Optional comma separated list of sensor_index values. When provided, the results are limited only to the sensors included in this list.

includePWFSL

Logical specifying whether to calculate distances from PWFSL monitors.

baseUrl

Base URL for the PurpleAir API.

Value

A PurpleAir Synoptic pas object.

References

PurpleAir

PurpleAir API

PurpleAir Terms of service

PurpleAir Data license

PurpleAir Data Attribution

See also

pas_downloadParseRawData

pas_enhanceRawData

Examples

# \donttest{
# Fail gracefully if any resources are not available
try({

library(AirSensor)

initializeMazamaSpatialUtils()

pas <-
  pas_createNew(
    api_key = PURPLE_AIR_API_READ_KEY,
    countryCodes = "US",
    stateCodes = "CA",
    show_only = SCAQMD_SENSOR_INDICES,
    lookbackDays = 1,
    location_type = 0
  )

pas %>% pas_leaflet()

}, silent = FALSE)
#> Error in pas_downloadParseRawData(api_key = api_key, fields = SENSOR_DATA_AVG_PM25_FIELDS,  : 
#>   object 'PURPLE_AIR_API_READ_KEY' not found
# }