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. Server-side unit transformations (percent change, log, etc.) and frequency aggregation are supported. 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_get_key(), fred_request(), fred_set_key()

Examples

op <- options(fred.cache_dir = tempdir())
clear_cache()
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)

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_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)

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_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.

Usage

fred_series(
  series_id,
  from = NULL,
  to = NULL,
  units = "lin",
  frequency = NULL,
  aggregation = "avg",
  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. Supported values:

• "lin" -levels (no transformation, the default)

• "chg" -change from previous period

• "ch1" -change from one year ago

• "pch" -percent change from previous period

• "pc1" -percent change from one year ago

• "pca" -compounded annual rate of change

• "cch" -continuously compounded rate of change

• "cca" -continuously compounded annual rate of change

• "log" -natural log

Value

A data frame with columns:

date

Date. The observation date.

series_id

Character. The FRED series identifier.

value

Numeric. The observation value.

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
macro <- fred_series(c("GDP", "UNRATE", "CPIAUCSL"))

# With transformation: year-on-year percent change
gdp_growth <- fred_series("GDP", units = "pc1")

# 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_get_key(), fred_request()

Examples

op <- options(fred.cache_dir = tempdir())
fred_set_key("your_api_key_here")
options(op)

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)