pas_downloadParseRawData: Download synoptic data from PurpleAir

In MazamaScience/AirSensor2: Process and Display Data from Air Quality Sensors

Download synoptic data from PurpleAir

Description

Download and parse raw synoptic data from PurpleAir within the specified region.

Synoptic data provides access to data from many PurpleAir sensors at a moment in time and includes both metadata and recent PM2.5 averages for each sensor. Data returned by this function is typically used to create static or interactive maps.

If show_only is used to request specific sensors, the bounding box information is ignored.

NOTE: Most users will want to use the pas_createNew function which enhances raw synoptic data with additional spatial metadata so that it meets the criteria for use as a pas object.

Usage

pas_downloadParseRawData(
  api_key = NULL,
  fields = PurpleAir_PAS_MINIMAL_FIELDS,
  location_type = 0,
  read_keys = NULL,
  show_only = NULL,
  modified_since = NULL,
  max_age = 3600 * 24 * 7,
  west = NULL,
  east = NULL,
  south = NULL,
  north = NULL,
  baseUrl = "https://api.purpleair.com/v1/sensors"
)

Arguments

api_key	PurpleAir API READ Key. If api_key = NULL, it will be obtained using getAPIKey("PurpleAir-read"). See MazamaCoreUtils::setAPIKey.
fields	Character string with PurpleAir field names for the Get Sensor Data API.
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.
modified_since	The modified_since parameter generates reults that include only sensors modified after the provided time stamp. Using the time stamp value associated with a previous call (recommended) will limit results to those with new values since the last request. Using a value of 0 will match sensors modified at any time.
max_age	Number of seconds used to filter results to only include sensors modified or updated within the the last max_age seconds. Using a value of 0 will match all sensors.
west	Longitude of the western edge of the bounding box in which to find sensors.
east	Longitude of the eastern edge of the bounding box in which to find sensors.
south	Latitude of the southern edge of the bounding box in which to find sensors.
north	Latitude of the northern edge of the bounding box in which to find sensors.
baseUrl	Base URL for the PurpleAir API.

Value

Dataframe of synoptic PurpleAir data.

Note

The fields parameter allows users to dial in which fields they are interested in depending on their needs. However, the following fields will be added if not specified in order to guarantee compatibility with pas_enhanceRawData(): "longitude,latitude,name,location_type,date_created,last_seen".

Pregenerated fields for use in this function include:

• /link{PurpleAir_PAS_METADATA_FIELDS} – instrument-only fields

• /link{PurpleAir_PAS_AVG_PM25_FIELDS} – includes measurements

References

PurpleAir

PurpleAir API

PurpleAir Terms of service

PurpleAir Data license

PurpleAir Data Attribution

Examples

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

library(AirSensor2)

initializeMazamaSpatialUtils()

source("global_vars.R") # contains PurpleAir_API_READ_KEY

# Download minimal fields, set max_age = 0, to look for historical data
pas_raw <-
  pas_downloadParseRawData(
    api_key = PurpleAir_API_READ_KEY,
    max_age = 0,
    west = -120.5,
    east = -120,
    south = 48.2,
    north = 48.7
  )

View(pas_raw)

# Download metadata, PM2.5 and weather parameter fields
pas_raw <-
  pas_downloadParseRawData(
    api_key = PurpleAir_API_READ_KEY,
    fields = PurpleAir_PAS_AVG_PM25_FIELDS,
    location_type = 0,
    modified_since = NULL,
    max_age = 3600 * 24,
    west = -120.5,
    east = -120,
    south = 48.2,
    north = 48.7
  )

View(pas_raw[1:100,])

}, silent = FALSE)

MazamaScience/AirSensor2 documentation built on Oct. 31, 2024, 1:39 a.m.