Finding info on an API variable
Even after determining a service and figuring out what API variables are needed for a call, you might face issues trying to figure out parameter codes.
High level variable information
For example, if we’re looking for daily data in a state, we see the following output for the filter.
services$`Daily Summary Data`$Filters$`By State`## $Endpoint
## [1] "dailyData/byState"
##
## $RequiredVariables
## [1] "email, key, param, bdate, edate, state"
##
## $OptionalVariables
## [1] "cbdate,cedate"
##
## $Example
## [1] "Example; returns all benzene daily summaries from North Carolina collected on May 15th, 1995:https://aqs.epa.gov/data/api/dailyData/byState?email=test@aqs.api&key=test¶m=45201&bdate=19950515&edate=19950515&state=37"The email and key are always included in calls (see Setup) so we don’t have to worry about those. But how would you declare bdate (begin date) and edate (end date)? Similarly, what values should go into param or state?
The variables object loaded in with the package helps here. variables is an R data frame that provides high level information about each API variable. We can type variables$ to see all potentially required variables in the API.
To find the right format for a specific variable, we can select the variable from variables. For example, we find out how a bdate is formed as follows:
variables$bdate## [1] "bdate"
## [2] "The begin date of the data selection in YYYYMMDD format. Only data on or after this date will be returned. (Note, for annual data, only the year portion of the bdate and edate are used and only whole years of data are returned. For example, bdate = 20171231 and edate = 20180101 will return full data for 2017 and 2018.)"
## [3] "20170101"If we want to find more about the param API variable, we can try the following:
variables$param## [1] "param"
## [2] "The AQS parameter code for the data selection. AQS uses proprietary 5 digit codes. They may be obtained via the list parameters service. Up to 5 parameters may be requested, separated by commas. Only data for these parameters will be returned."
## [3] "81101,44201"Finally, here’s an example for state:
variables$state## [1] "state"
## [2] "The 2 digit state FIPS code for the state (with leading zero). They may be obtained via the list states service. Only data from within this state will be returned."
## [3] "01"Specific codes in variables
After figuring out how API variables should be coded, we may need to find specific parameter codes. For example, as shown above, state requires a 2 digit FIPS code, and we may not know exactly what that code is.
The variable.types object loaded in with the package helps with this. It serves as a dictionary mapping API variables to endpoints that provide a list of parameter codes. An example of available options is shown.
For example, if we want to find state codes, we can do so as follows:
endpoint <- variable.types$state
result <- perform.call(endpoint)
result$Data## code value_represented
## 1 01 Alabama
## 2 02 Alaska
## 3 04 Arizona
## 4 05 Arkansas
## 5 06 California
## 6 08 Colorado
## 7 09 Connecticut
## 8 10 Delaware
## 9 11 District Of Columbia
## 10 12 Florida
## 11 13 Georgia
## 12 15 Hawaii
## 13 16 Idaho
## 14 17 Illinois
## 15 18 Indiana
## 16 19 Iowa
## 17 20 Kansas
## 18 21 Kentucky
## 19 22 Louisiana
## 20 23 Maine
## 21 24 Maryland
## 22 25 Massachusetts
## 23 26 Michigan
## 24 27 Minnesota
## 25 28 Mississippi
## 26 29 Missouri
## 27 30 Montana
## 28 31 Nebraska
## 29 32 Nevada
## 30 33 New Hampshire
## 31 34 New Jersey
## 32 35 New Mexico
## 33 36 New York
## 34 37 North Carolina
## 35 38 North Dakota
## 36 39 Ohio
## 37 40 Oklahoma
## 38 41 Oregon
## 39 42 Pennsylvania
## 40 44 Rhode Island
## 41 45 South Carolina
## 42 46 South Dakota
## 43 47 Tennessee
## 44 48 Texas
## 45 49 Utah
## 46 50 Vermont
## 47 51 Virginia
## 48 53 Washington
## 49 54 West Virginia
## 50 55 Wisconsin
## 51 56 Wyoming
## 52 66 Guam
## 53 72 Puerto Rico
## 54 78 Virgin Islands
## 55 80 Country Of Mexico
## 56 CC CanadaAnother example is shown below for county parameter codes.
Note that to find a county parameter code, we should specify a state.
endpoint <- variable.types$county
state <- "01" # Alabama
result <- perform.call(endpoint, state)
head(result$Data)## code value_represented
## 1 001 Autauga
## 2 003 Baldwin
## 3 005 Barbour
## 4 007 Bibb
## 5 009 Blount
## 6 011 BullockIn general, you can find information on parameter codes used for API variables as follows:
endpoint <- variable.types$variable.of.interest
result <- perform.call(endpoint)Note that additional API variables might need to get inputted in which case a general template is as follows:
endpoint <- variable.types$variable.of.interest
additional.variable <- "Code"
result <- perform.call(endpoint, additional.variable)