Getting started with fredr

Sam Boysel

2018-07-22

Introduction

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

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.

Installation

To get the development version of the package:

Load package

Authentication

To use 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 fredr_set_key

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.

Retrieve series observations

The 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).

Leverage the native features of the FRED API by passing additional parameters:

fredr plays nicely with tidyverse packages:

Since fredr() returns a tibble with a series ID, mapping fredr() over a vector of series IDs can be achieved as follows:

Using purrr::pmap_dfr() allows you to use varying optional parameters as well.

It is relatively straightforward to convert tibbles returned by fredr into other time series objects. For example,

Endpoints

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 fredr_endpoints:

View FRED API documentation

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 series/observations endpoint.

You may also use the params option for fredr_docs to go straight to the endpoint’s Parameters section.

General queries

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 endpoint (see fredr_endpoints for a list of valid endpoints) and then all API parameters are passed through as named arguments. For example:

By default, fredr_request() will return a tibble. Set to_frame to FALSE to return a generic response object from a httr::GET() request that can be further parsed with httr::content():