fred: Access 'Federal Reserve Economic Data'

Description

Provides clean, tidy access to economic data from the 'Federal Reserve Economic Data' ('FRED') API https://fred.stlouisfed.org/docs/api/fred/. 'FRED' is maintained by the 'Federal Reserve Bank of St. Louis' and contains over 800,000 time series from 118 sources covering GDP, employment, inflation, interest rates, trade, and more. Dedicated functions fetch series observations, search for series, browse categories, releases, and tags, and retrieve series metadata. Multiple series can be fetched in a single call, in long or wide format. Server-side unit transformations (percent change, log, etc.) and frequency aggregation are supported, with readable transform aliases such as 'yoy_pct' and 'log_diff'. Real-time and vintage helpers (built on 'ALFRED') return a series as it appeared on a given date, the first-release version, every revision, or a panel of selected vintages. Data is cached locally for subsequent calls. This product uses the 'FRED' API but is not endorsed or certified by the 'Federal Reserve Bank of St. Louis'.

Author(s)

Maintainer: Charles Coverdale charlesfcoverdale@gmail.com

See Also

Useful links:

• https://github.com/charlescoverdale/fred

• Report bugs at https://github.com/charlescoverdale/fred/issues

Clear the fred cache

Description

Deletes all locally cached FRED data files. The next call to any data function will re-download from the FRED API.

Usage

clear_cache()

Value

Invisible NULL.

See Also

Other configuration: fred_cache_info(), fred_get_key(), fred_request(), fred_set_key()

Examples

op <- options(fred.cache_dir = tempdir())
clear_cache()
options(op)

Fetch every vintage of a series

Description

Returns the full revision history: one row per (observation date, realtime range) combination. This is the FRED API's output_type = 2 mode. The result can be reshaped into a vintage matrix or used to compute revision statistics.

Usage

fred_all_vintages(
  series_id,
  from = NULL,
  to = NULL,
  units = "lin",
  frequency = NULL,
  aggregation = "avg",
  cache = TRUE
)

Arguments

Details

Be aware that some series have hundreds of thousands of vintage rows, so consider narrowing the date range with from/to for long-running indicators like GDP.

Value

A fred_tbl with columns date, series_id, value, realtime_start, realtime_end. The realtime_start and realtime_end columns identify the vintage window for each row.

See Also

Other vintages: fred_as_of(), fred_first_release(), fred_real_time_panel()

Examples

op <- options(fred.cache_dir = tempdir())
# All vintages of recent GDP releases
gdp_vint <- fred_all_vintages("GDP", from = "2020-01-01")
options(op)

Fetch a series as it appeared on a given vintage date

Description

Returns the values that were available in FRED on date, before any subsequent revisions. This is the standard real-time data access pattern: set realtime_start = realtime_end = date. Useful for backtesting forecasting models against the data that was actually available at the time, not the revised series we see today.

Usage

fred_as_of(
  series_id,
  date,
  from = NULL,
  to = NULL,
  units = "lin",
  frequency = NULL,
  aggregation = "avg",
  cache = TRUE
)

Arguments

Details

Underneath, this calls the series/observations endpoint with the realtime parameters set. Results are cached separately from the default (latest-vintage) cache, so calling fred_series("GDP") and fred_as_of("GDP", "2020-01-15") keep distinct cache entries.

Value

A fred_tbl with columns date, series_id, value, realtime_start, realtime_end.

See Also

Other vintages: fred_all_vintages(), fred_first_release(), fred_real_time_panel()

Examples

op <- options(fred.cache_dir = tempdir())
# GDP as it looked on 1 March 2020
gdp_2020 <- fred_as_of("GDP", "2020-03-01")
options(op)

Inspect the local fred cache

Description

Returns information about the local cache: where it lives, how many files it contains, and how much disk space they take. Useful when debugging stale results or deciding whether to call clear_cache().

Usage

fred_cache_info()

Value

A list with elements dir, n_files, size_bytes, size_human, and files (a data frame with name, size_bytes, and modified columns). Returns the same shape with zero counts if the cache directory does not yet exist.

See Also

Other configuration: clear_cache(), fred_get_key(), fred_request(), fred_set_key()

Examples

op <- options(fred.cache_dir = tempdir())
fred_cache_info()
options(op)

Get a FRED category

Description

Returns information about a single category. The FRED category tree starts at category 0 (the root) and branches into 8 top-level categories: Money, Banking & Finance; Population, Employment & Labor Markets; National Accounts; Production & Business Activity; Prices; International Data; U.S. Regional Data; and Academic Data.

Usage

fred_category(category_id = 0L)

Arguments

Value

A data frame with category metadata.

See Also

Other categories: fred_category_children(), fred_category_series()

Examples

op <- options(fred.cache_dir = tempdir())
# Root category
fred_category()

# National Accounts (category 32992)
fred_category(32992)
options(op)

List child categories

Description

Returns the child categories for a given parent category.

Usage

fred_category_children(category_id = 0L)

Arguments

Value

A data frame of child categories.

See Also

Other categories: fred_category(), fred_category_series()

Examples

op <- options(fred.cache_dir = tempdir())
# Top-level categories
fred_category_children()
options(op)

List series in a category

Description

Returns all series belonging to a given category. Automatically paginates through all results.

Usage

fred_category_series(category_id, limit = 1000L)

Arguments

Value

A data frame of series metadata.

See Also

Other categories: fred_category(), fred_category_children()

Examples

op <- options(fred.cache_dir = tempdir())
fred_category_series(32992)
options(op)

Fetch the first-release ("real-time") version of a series

Description

Returns only the value that was published when each observation first appeared in FRED, with no subsequent revisions. Internally this fetches the full revision history and keeps the earliest realtime_start row for each observation date. Useful when you want a clean comparison between what policymakers saw at the time versus what the data look like after revisions.

Usage

fred_first_release(
  series_id,
  from = NULL,
  to = NULL,
  units = "lin",
  frequency = NULL,
  aggregation = "avg",
  cache = TRUE
)

Arguments

Value

A fred_tbl with columns date, series_id, value, realtime_start, realtime_end.

See Also

Other vintages: fred_all_vintages(), fred_as_of(), fred_real_time_panel()

Examples

op <- options(fred.cache_dir = tempdir())
# Initial-release GDP, never revised
gdp_first <- fred_first_release("GDP", from = "2018-01-01")
options(op)

Get the current FRED API key

Description

Returns the API key set via fred_set_key() or the FRED_API_KEY environment variable. Raises an error if no key is found.

Usage

fred_get_key()

Value

Character. The API key.

See Also

Other configuration: clear_cache(), fred_cache_info(), fred_request(), fred_set_key()

Examples

op <- options(fred.cache_dir = tempdir())
fred_get_key()
options(op)

Get metadata for a FRED series

Description

Returns descriptive information about a series, including its title, units, frequency, seasonal adjustment, and notes.

Usage

fred_info(series_id)

Arguments

Value

A data frame with one row containing series metadata.

See Also

Other series: fred_search(), fred_series(), fred_updates(), fred_vintages()

Examples

op <- options(fred.cache_dir = tempdir())
fred_info("GDP")
options(op)

Fetch a real-time panel of a series across selected vintages

Description

Returns the values that were available on each of a chosen set of vintage dates. This is the FRED API's vintage_dates parameter: instead of asking for every revision (potentially huge), you ask for only the snapshots you care about, e.g. quarterly vintages aligned to GDP release dates.

Usage

fred_real_time_panel(
  series_id,
  vintages,
  from = NULL,
  to = NULL,
  units = "lin",
  frequency = NULL,
  aggregation = "avg",
  cache = TRUE
)

Arguments

Value

A fred_tbl with columns date, series_id, value, realtime_start, realtime_end.

See Also

Other vintages: fred_all_vintages(), fred_as_of(), fred_first_release()

Examples

op <- options(fred.cache_dir = tempdir())
# GDP as published at three quarterly snapshots
gdp_panel <- fred_real_time_panel(
  "GDP",
  vintages = c("2023-04-30", "2023-07-31", "2023-10-31")
)
options(op)

Find tags related to a given tag

Description

Returns tags that are frequently used together with the specified tag.

Usage

fred_related_tags(tag_names)

Arguments

Value

A data frame of related tags.

See Also

Other tags: fred_tags()

Examples

op <- options(fred.cache_dir = tempdir())
fred_related_tags("gdp")
options(op)

Get release dates

Description

Returns the dates on which data for a release were published. Useful for understanding the data calendar and when revisions occurred.

Usage

fred_release_dates(release_id)

Arguments

Value

A data frame with columns release_id and date.

See Also

Other releases: fred_release_series(), fred_releases()

Examples

op <- options(fred.cache_dir = tempdir())
fred_release_dates(53)
options(op)

List series in a release

Description

Returns all series belonging to a given release.

Usage

fred_release_series(release_id)

Arguments

Value

A data frame of series metadata.

See Also

Other releases: fred_release_dates(), fred_releases()

Examples

op <- options(fred.cache_dir = tempdir())
# GDP release
fred_release_series(53)
options(op)

List all FRED releases

Description

Returns all data releases available on FRED. A release is a collection of related series published together (e.g. "Employment Situation", "GDP").

Usage

fred_releases()

Value

A data frame of releases with columns including id, name, press_release, and link.

See Also

Other releases: fred_release_dates(), fred_release_series()

Examples

op <- options(fred.cache_dir = tempdir())
fred_releases()
options(op)

Make a raw request to the FRED API

Description

Low-level function that sends a request to any FRED API endpoint and returns the parsed JSON as a list. Most users should use the higher-level functions such as fred_series() or fred_search().

Usage

fred_request(endpoint, ...)

Arguments

Value

A list parsed from the JSON response.

See Also

Other configuration: clear_cache(), fred_cache_info(), fred_get_key(), fred_set_key()

Examples

op <- options(fred.cache_dir = tempdir())
fred_request("series", series_id = "GDP")
options(op)

Search for FRED series

Description

Searches the FRED database by keywords or series ID substring. Returns matching series with their metadata, ordered by relevance.

Usage

fred_search(
  query,
  type = "full_text",
  limit = 100L,
  order_by = "search_rank",
  filter_variable = NULL,
  filter_value = NULL,
  tag_names = NULL
)

Arguments

Value

A data frame of matching series with columns including id, title, frequency, units, seasonal_adjustment, last_updated, popularity, and notes.

See Also

Other series: fred_info(), fred_series(), fred_updates(), fred_vintages()

Examples

op <- options(fred.cache_dir = tempdir())
# Keyword search
fred_search("unemployment rate")

# Filter to monthly series only
fred_search("consumer price index", filter_variable = "frequency",
            filter_value = "Monthly")

# Search by series ID pattern
fred_search("GDP*", type = "series_id")
options(op)

Fetch observations for one or more FRED series

Description

The main function in the package. Downloads time series observations from FRED and returns a tidy data frame. Multiple series can be fetched in a single call, in either long or wide format.

Usage

fred_series(
  series_id,
  from = NULL,
  to = NULL,
  units = "lin",
  transform = NULL,
  frequency = NULL,
  aggregation = "avg",
  format = c("long", "wide"),
  cache = TRUE
)

Arguments

Details

FRED supports server-side unit transformations via the units argument. This avoids the need to compute growth rates or log transforms locally. For readability you can pass transform instead of units:

• "level", "raw" -levels (the default)

• "diff", "change" -change from previous period

• "yoy_diff" -change from one year ago

• "qoq_pct", "mom_pct", "pop_pct" -percent change from previous period

• "yoy_pct" -percent change from one year ago

• "annualised", "qoq_annualised" -compounded annual rate of change

• "log" -natural log

• "log_diff" -continuously compounded rate of change

• "log_diff_annualised" -continuously compounded annual rate

Raw FRED units codes ("lin", "chg", "ch1", "pch", "pc1", "pca", "cch", "cca", "log") are also accepted.

Value

A fred_tbl (a data.frame subclass that prints with a one-line provenance header). In long format, columns are date, series_id, value. In wide format, columns are date plus one numeric column per series.

See Also

Other series: fred_info(), fred_search(), fred_updates(), fred_vintages()

Examples

op <- options(fred.cache_dir = tempdir())
# Single series
gdp <- fred_series("GDP")

# Multiple series, long format
macro <- fred_series(c("GDP", "UNRATE", "CPIAUCSL"))

# Multiple series, wide format
macro_w <- fred_series(c("GDP", "UNRATE"), format = "wide")

# Readable transformation: year-on-year percent change
gdp_growth <- fred_series("GDP", transform = "yoy_pct")

# Aggregate daily to monthly
rates <- fred_series("DGS10", frequency = "m")
options(op)

Set the FRED API key

Description

Sets the API key used to authenticate requests to the FRED API. The key persists for the current R session. Alternatively, set the FRED_API_KEY environment variable in your .Renviron file.

Usage

fred_set_key(key)

Arguments

Details

Register for a free API key at https://fredaccount.stlouisfed.org/apikeys.

Value

Invisible NULL.

See Also

Other configuration: clear_cache(), fred_cache_info(), fred_get_key(), fred_request()

Examples

## Not run: 
fred_set_key("your_api_key_here")

## End(Not run)

List releases from a source

Description

Returns all releases published by a given data source.

Usage

fred_source_releases(source_id)

Arguments

Value

A data frame of releases.

See Also

Other sources: fred_sources()

Examples

op <- options(fred.cache_dir = tempdir())
# Bureau of Labor Statistics
fred_source_releases(22)
options(op)

List all FRED data sources

Description

Returns all data sources that contribute series to FRED. Sources include the Bureau of Labor Statistics, Bureau of Economic Analysis, Federal Reserve Board, U.S. Census Bureau, and over 100 others.

Usage

fred_sources()

Value

A data frame of sources with columns including id, name, and link.

See Also

Other sources: fred_source_releases()

Examples

op <- options(fred.cache_dir = tempdir())
fred_sources()
options(op)

List or search FRED tags

Description

Returns FRED tags, optionally filtered by a search query. Tags are keywords used to categorise series (e.g. "gdp", "monthly", "usa", "seasonally adjusted").

Usage

fred_tags(query = NULL, limit = 1000L)

Arguments

Value

A data frame of tags with columns including name, group_id, notes, popularity, and series_count.

See Also

Other tags: fred_related_tags()

Examples

op <- options(fred.cache_dir = tempdir())
fred_tags()
fred_tags("inflation")
options(op)

List recently updated FRED series

Description

Returns series that have been recently updated or revised.

Usage

fred_updates(limit = 100L)

Arguments

Value

A data frame of recently updated series.

See Also

Other series: fred_info(), fred_search(), fred_series(), fred_vintages()

Examples

op <- options(fred.cache_dir = tempdir())
fred_updates()
options(op)

Get vintage dates for a FRED series

Description

Returns the dates on which data for a series were revised. This is useful for real-time analysis and understanding data revisions.

Usage

fred_vintages(series_id)

Arguments

Value

A data frame with columns series_id and vintage_date.

See Also

Other series: fred_info(), fred_search(), fred_series(), fred_updates()

Examples

op <- options(fred.cache_dir = tempdir())
fred_vintages("GDP")
options(op)

Print method for fred_tbl

Description

Adds a one-line provenance header above the data frame body. The header summarises the query: number of series, observation count, transformation in effect, and any vintage information.

Usage

## S3 method for class 'fred_tbl'
print(x, ...)

Arguments

Value

x, invisibly.