The Anatomy of an EPA API request
Source:vignettes/a01_ananomyEPARequest.Rmd
a01_ananomyEPARequest.RmdAlthough we do not need to write out an entire API url request, knowing how API requests are built helps when using this package.
Each request comes in the form of a URL. A url usually starts with https or something similar and may look like this:
In this API, a user writes out a url and then places it in their browser or in an API service (much like this package) to retrieve data. In the case of the EPA API, all requests have up to four components:
- a base url
- an endpoint
- authentication
- variables
The base url consists of the website where the API is found. It looks like this:
An endpoint refers to the string coming right after the base url, and refers to the service the API gives. For example, the API can show a list of states and their respective codes to use when querying. The endpoint for this is the string list/states?. So, if we join this endpoint with the base, we get the following url:
To actually request data, a user needs to have registered a valid email and received an API key (to do so see here ). This email and key go into an authentication string that gets appended to the url. To be able to query the url we showed above, we add our authentication. Now, our URL would look like this:
https://aqs.epa.gov/data/api/list/states?&email=youremail@domain.com&key=yourapikey
At this point, we can place the URL in the browser and retrieve data about states. Most data, however, will probably involve a particular pollutant in a desired region. In that case, we must also add additional items to the url string.
For example, suppose we wanted to get daily data values for ozone concentrations in the state of North Carolina. After determining the endpoint, which is dailyData/byState? , we need to add in a state, the beginning date, ending date for our data, and ozone. If we wrote out the entire call as URL, including authentication, we would have this:
It’s not hard to see that writing out these queries and placing them in a browser could get tedious. Additionally, you’ll notice that some additional items, like state require a specific code and figuring out the code can be difficult. This package aims to simplify these tasks by automating the making and placing of URL’s as well as helping the user determine the correct codes for specific items in the call.