---
title: "Fetching Data from FRED"
author: "Christopher Mann"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Fetching Data from FRED}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>",
  eval     = FALSE
)
```

Every function in this vignette queries the FRED web API, so none of the code
below is executed when the vignette is built. The results shown were produced by
running the same code in an interactive session; copy any chunk into R with your
own API key to reproduce it.

The `eFRED` package makes it easy to import any number of series from the FRED 
website into a single data.frame. 

First, you will need an API key. You can freely obtain one by following the instructions 
at https://fred.stlouisfed.org/docs/api/api_key.html. The API key is a 32 character, 
lower-cased string. Once you have registered for one, assign it to a variable or 
use the `set_fred_key` function.

```{r}
library(eFRED)
api_key <- "abcdefghijklmnopqrstuvwxyz123456"
set_fred_key(api_key)
```

The package does not ship a key of its own, so this step is required. Functions 
that need a key and cannot find one stop with a message explaining how to get 
and register one. If you would rather not register the key in every session, 
set `FRED_KEY` in your `.Renviron` file instead.

Almost all of the `eFRED` functions require an API key. The `set_fred_key` function 
sets the default key that is used by the functions so that you do not need to directly 
pass the key each time the function is called.

FRED data can be extracted by using the `fred` function. The general format of the 
function is  `fred(name1 = "code1", name2 = "code2", ...)`, where `"code"` is the unique series
ID that can be found next to each series' title at https://fred.stlouisfed.org/, 
and `name` is the new label for the series in the resulting data.frame. If no `name`
is provided, then the code will be used. Any number of series can be used and 
each code can be a character vector containing with multiple entries.

The following searches for two series: "GDPC1" *(Real GDP)* and "UNRATE" *(unemployment rate)*.

```{r}
df <- fred(y = "GDPC1", "unrate", all=FALSE)
head(df)
```

```
#>         date        y UNRATE
#> 1 1948-01-01 2239.682    3.4
#> 2 1948-04-01 2276.690    3.9
#> 3 1948-07-01 2289.770    3.6
#> 4 1948-10-01 2292.364    3.7
#> 5 1949-01-01 2260.807    4.3
#> 6 1949-04-01 2253.128    5.3
```

The column containing the data for GDP is named `"y"`. Since no name was provided for `"UNRATE"`, 
the column name is the same as the series. Note that the codes are not case sensitive. The 
`fred` function automatically converts all codes to uppercase. The last argument, `all=FALSE`, 
is included because GDP and the unemployment rate have different frequencies *(quarterly vs annual)* 
and different starting periods. When `all=FALSE` is used, the data.frame forces each value to the 
shortest series; otherwise, the frequency would be monthly with many `NA` values for `y`.

If a series id does not exist, that series is skipped with a warning and the 
remaining series are still returned. If the FRED API itself cannot be reached, 
or returns something that cannot be parsed, `eFRED` prints an informative 
message and returns no data for that request rather than raising an error. 
Either way, if no series at all could be retrieved, `fred` returns `NULL`.

The raw information about each series is contained within the data.frame's `info` attribute, 
unless `info=FALSE` is included. The attribute holds 16 columns; a few are shown below.

```{r}
info <- attr(df, "info")
info[, c("id", "title", "units_short", "frequency")]
```

```
#>       id                       title         units_short frequency
#> 1  GDPC1 Real Gross Domestic Product Bil. of Chn. 2017 $ Quarterly
#> 2 UNRATE           Unemployment Rate                   %   Monthly
```

The `eFRED` package contains a variety of other functions to interact with the 
FRED API. For example, the `fred_search` function can be used to search for various 
series. The example below searches for series based on the query `"unemployment"`. 
The `args` parameter is a list containing other search parameters. In this case, 
search is limited to only the top three results.

```{r}
search_results <- fred_search("unemployment", args = list(limit = 3))
search_results[, c("id", "frequency", "units_short")]
```

```
#>          id frequency units_short
#> 1    UNRATE   Monthly           %
#> 2 UNRATENSA   Monthly           %
#> 3    U6RATE   Monthly           %
```

To grab each of these series, we can use the command `fred(search_results$id, info=FALSE)`.
The information about each is not needed since we have it from the search results.

The `eFRED` package also contains functions to search across tags, categories, releases, 
and much more.