library(fredr) knitr::opts_chunk$set( fig.width = 7, fig.height = 5, eval = fredr_has_key(), collapse = TRUE, comment = "#>" )
fredr provides a complete set of R bindings to the Federal Reserve of Economic Data (FRED) RESTful API, provided by the Federal Reserve Bank of St. Louis. The functions allow the user to search for and fetch time series observations as well as associated metadata within the FRED database.
The core function in this package is
fredr(), which fetches observations for a FRED series. That said, there are many other FRED endpoints exposed through fredr, such as
fredr_series_search_text(), which allows you to search for a FRED series by text.
We strongly encourage referencing the FRED API documentation to leverage the full power of fredr.
Once you've obtained an API key, the recommended way to use it is to set the key as an environment variable:
FRED_API_KEY . The easiest way to do that is by calling
usethis::edit_r_environ() to open a
.Renviron file. Once the file is open set the key as:
where the key has been replaced by the one you received from FRED. Don't forget to restart R after saving and closing the
Alternatively, you can set an API key for the current R session with
fredr_set_key() like so:
Again, this will only set the key for the current R session, and it is recommended to use an environment variable.
fredr() (an alias for
fredr_series_observations()) retrieves series observations (i.e. the actual time series data) for a specified FRED series ID. The function returns a tibble with 3 columns (observation date, series ID, and value).
fredr( series_id = "UNRATE", observation_start = as.Date("1990-01-01"), observation_end = as.Date("2000-01-01") )
Leverage the native features of the FRED API by passing additional parameters:
fredr( series_id = "UNRATE", observation_start = as.Date("1990-01-01"), observation_end = as.Date("2000-01-01"), frequency = "q", # quarterly units = "chg" # change over previous value )
fredr plays nicely with tidyverse packages:
library(dplyr) library(ggplot2) popular_funds_series <- fredr_series_search_text( search_text = "federal funds", order_by = "popularity", sort_order = "desc", limit = 1 ) popular_funds_series_id <- popular_funds_series$id popular_funds_series_id %>% fredr( observation_start = as.Date("1990-01-01"), observation_end = as.Date("2000-01-01") ) %>% ggplot(data = ., mapping = aes(x = date, y = value, color = series_id)) + geom_line() + labs(x = "Observation Date", y = "Rate", color = "Series")
fredr() returns a tibble with a series ID, mapping
fredr() over a vector of series IDs can be achieved as follows:
library(purrr) map_dfr(c("UNRATE", "FEDFUNDS"), fredr) %>% ggplot(data = ., mapping = aes(x = date, y = value, color = series_id)) + geom_line() + labs(x = "Observation Date", y = "Rate", color = "Series")
purrr::pmap_dfr() allows you to use varying optional parameters as well.
params <- list( series_id = c("UNRATE", "OILPRICE"), frequency = c("m", "q") ) pmap_dfr( .l = params, .f = ~ fredr(series_id = .x, frequency = .y) )
It is relatively straightforward to convert tibbles returned by fredr into other time series objects. For example:
library(xts) gnpca <- fredr(series_id = "GNPCA", units = "log") %>% mutate(value = value - lag(value)) %>% filter(!is.na(value)) gnpca_xts <- xts( x = gnpca$value, order.by = gnpca$date ) gnpca_xts %>% StructTS() %>% residuals() %>% acf(., main = "ACF for First Differenced real US GNP, log")
fredr implements functions for all FRED API endpoints. For usage examples for these functions, please consult the relevant vignette:
Finally, fredr is packaged with a list of possible endpoints in the tibble named
To get the most out of the native features of the FRED API, it is highly recommended to review the API endpoint documentation. Within an R session, you can quickly access the web documentation with the convenience function
You can also use the low-level function
fredr_request() to run more general queries against any FRED API endpoint (e.g. Categories, Series, Sources, Releases, Tags). The required parameter is
fredr_endpoints for a list of valid endpoints) and then all API parameters are passed through as named arguments. For example:
fredr_request( endpoint = "tags/series", tag_names = "population;south africa", limit = 25L )
fredr_request() will return a tibble. Set
FALSE to return a generic
response object from a
httr::GET() request that can be further parsed with
fredr_request( endpoint = "series/observations", series_id = "UNRATE", to_frame = FALSE )
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.