---
title: "Navigating API Services"
output: rmarkdown::html_vignette
description: >
  Navigating API services
vignette: >
  %\VignetteIndexEntry{Navigating API Services}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{css, echo=FALSE}
pre code {
  white-space: pre-wrap;
}
```

```{r echo = FALSE, message = FALSE}
library(jsonlite)
library(httr)
library(epair)
```

```{r echo = FALSE}
authentication <- create.authentication(Sys.getenv('aqs_email'), Sys.getenv('aqs_api_key'))
options(epa_authentication = authentication)
```

# The services object

The `services` object comes loaded with the package. It is an R list containing comprehensive information about each service offered in the EPA API. 

We can see all services available by using `names()`.

```{r}
names(services)
```

Alternatively, using RStudio's smart variable selection, you can type `services$`
to see the available services. 

![](img/making_first_call/service_selection.png)

## What service to use

You can also see a description for each service. This helps determine what service to use. For example, suppose you want to find hourly data in a particular state. Perhaps these data are contained in a daily summary so you can check the description. 

![](img/services/daily_description.png)

```{r}
services$`Daily Summary Data`$Description
```
The description suggests hourly data may be used to produce the values, but we may not necessarily get hourly data. 

So we try a different service description. 

![](img/services/sample_description.png)

```{r}
services$`Sample Data`$Description
```
This service seems more appropriate to what we need. It specifically mentions hourly data and might even offer finer grain data. 

In general, to find the description of a service, you can type the following. 

```{r eval = FALSE}
service$ServiceName$Description
```

## Filters

Most API services also have a component called a *filter*. This refers to a filter applied to desired data. 
For example, if we want to find information on weather monitors, we should specify monitors in a state vs a county. The `services` object contains a `Filters` component that lets the user find out how final data can be filtered. Using the weather monitors example, we can see the filters available as follows.

```{r}
names(services$Monitors$Filters)
```

Or, we can use `servics$Monitors$Filters$` to see available filters.

![](img/services/monitor_filters.png)

The `Filters` component in the `services` object contains all information you might need to make a call. It has the endpoint, required API variables, optional API variables (if appropriate), and a URL example of a call. 

In general, to see available filters, you can type the following: 

```{r eval = FALSE} 
names(services$ServiceName$Filters)
```

Or, using RStudio's smart variable selection:

```{r eval = FALSE}
services$ServiceName$Filters$
```

## Further information

After seeing what filter to use, you can see the requirements to make a call. As mentioned above, the `Filters` component contains an endpoint, required API variable, optional API variable, and an example URL. Each of these helps when trying to build a call with the package. 

For instance, say you want to find annual data for a state in the US. You can look at the filters for the annual data service to see how to build the call. 

```{r}
services$`Annual Summary Data`$Filters$`By State`
```

In general, you can find information for making a call using a specific filter 
as follows:

```{r eval = FALSE}
services$ServiceName$Filters$SpecificFilter
```