knitr::opts_chunk$set( fig.width = 7, fig.height = 5, eval = !(Sys.getenv("FRED_API_KEY") == ""), cache = TRUE, collapse = TRUE, comment = "#>" ) library(fredr) options(digits = 4)
fredr provides a complete set of
R bindings to the Federal Reserve 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 functions are
fredr_set_key()- Set the required FRED API key for the session.
fredr_series_observations()- Fetch a FRED series.
fredr_series_search_text()- Search for a FRED series by text.
fredr_request()- Send a general request to the FRED API.
Objects are returned as
tibbles. The user is strongly encouraged to read the
full FRED API documentation to
leverage the full power of
fredr and the FRED API.
To get the development version of the package:
# install.packages("devtools") devtools::install_github("sboysel/fredr")
fredr and the FRED API in general, you must first obtain a FRED API
key. It is also
recommended to review the FRED API Terms of
Use. Once you've obtained an API key, you can set the key as an environment variable using
where "abcdefghijklmnopqrstuvwxyz123456" is replaced with the actual key you obtain from FRED. This will set the key for the current session. You can persistently set the key by appending the line
FRED_API_KEY=abcdefghijklmnopqrstuvwxyz123456 to an
.Renviron file in the working directory or at the user level. This can be done using a text editor or by running
usethis::edit_r_environ(). If you edit the
.Renviron file, remember to either restart the session or run
readRenviron(".Renviron") for the changes to take effect.
fredr() function (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") )
Leverage the native features of the FRED API by passing additional parameters:
fredr_series_observations( series_id = "UNRATE", observation_start = as.Date("1990-01-01"), frequency = "q", units = "chg" )
fredr plays nicely with tidyverse packages:
library(dplyr) library(ggplot2) fredr_series_search_text( search_text = "federal funds", order_by = "popularity", sort_order = "desc", limit = 1) %>% pull(id) %>% fredr(series_id = .) %>% 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:
fredr is packaged with a list of possible endpoints in the
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 for any endpoint with the convenience function
fredr_docs(). The following example will open a web browser to the FRED API documentation page on the
fredr_docs(endpoint = "series/observations")
You may also use the
params option for
fredr_docs to go straight to the
endpoint's Parameters section.
fredr_docs(endpoint = "category/related_tags", params = TRUE)
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
FALSE to return a generic
response object from a
httr::GET() request that can be further parsed with
library(httr) 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.