Get observations of a FRED series

Source: R/fredr_series_observations.R

Given a series ID, return observations of that series as a tibble object. fredr() is an alias for fredr_series_observations().

fredr_series_observations(
  series_id,
  ...,
  observation_start = NULL,
  observation_end = NULL,
  frequency = NULL,
  aggregation_method = NULL,
  limit = NULL,
  offset = NULL,
  sort_order = NULL,
  units = NULL,
  realtime_start = NULL,
  realtime_end = NULL,
  vintage_dates = NULL,
  output_type = NULL
)

fredr(
  series_id,
  ...,
  observation_start = NULL,
  observation_end = NULL,
  frequency = NULL,
  aggregation_method = NULL,
  limit = NULL,
  offset = NULL,
  sort_order = NULL,
  units = NULL,
  realtime_start = NULL,
  realtime_end = NULL,
  vintage_dates = NULL,
  output_type = NULL
)

Arguments

series_id

A string ID for the FRED series.

...

These dots only exist for future extensions and should be empty.

observation_start

A Date indicating the start of the observation period. Defaults to 1776-07-04, the earliest available date.

observation_end

A Date indicating the end of the observation period. Defaults to 9999-12-31, the latest available date.

frequency

A string representing a lower frequency to aggregate to. Defaults to no frequency aggregation. Possible values are:

  • "d" - Daily

  • "w" - Weekly

  • "bw" - Biweekly

  • "m" - Monthly

  • "q" - Quarterly

  • "sa" - Semiannual

  • "a" - Annual

  • "wem" - Weekly, ending Monday

  • "wetu" - Weekly, ending Tuesday

  • "wew" - Weekly, ending Wednesday

  • "weth" - Weekly, ending Thursday

  • "wef" - Weekly, ending Friday

  • "wesa" - Weekly, ending Saturday

  • "wesu" - Weekly, ending Sunday

  • "bwew" - Biweekly, ending Wednesday

  • "bwem" - Biweekly, ending Monday

aggregation_method

A string representing the aggregation method used for frequency aggregation. This parameter has no affect is frequency is not set. Possible values are:

  • "avg" for average

  • "sum" for sum

  • "eop" for end of period value

limit

An integer limit on the maximum number of results to return. Defaults to 100000, the maximum.

offset

An integer used in conjunction with limit for long series. This mimics the idea of pagination to retrieve large amounts of data over multiple calls. Defaults to 0.

sort_order

A string representing the order of the resulting series. Possible values are: "asc" (default), and "desc".

units

A string indicating the data value transformation. Defaults to "lin". Possible values are:

  • "lin" - Levels (No transformation)

  • "chg" - Change

  • "ch1" - Change from 1 year ago

  • "pch" - Percent change

  • "pc1" - Percent change from 1 year ago

  • "pca" - Compounded annual rate of change

  • "cch" - Continuously compounded rate of change

  • "cca" - Continuously compounded annual rate of change

  • "log" - Natural log

realtime_start

A Date indicating the start of the real-time period. Defaults to today's date. For more information, see Real-Time Periods.

realtime_end

A Date indicating the end of the real-time period. Defaults to today's date. For more information, see Real-Time Periods.

vintage_dates

A vector of Date objects to download data for. Vintage dates are used to download data as it existed on these specified dates in history. They can be specified instead of a real-time period using realtime_start and realtime_end. Defaults to no vintage dates.

output_type

An integer indicating the output type. Not used unless realtime_start is used. Possible values are:

  • 1 for Observations by Real-Time Period (default)

  • 2 for Observations by Vintage Date, All Observations

  • 3 for Observations by Vintage Date, New and Revised Observations Only

  • 4 for Observations, Initial Release Only.

Value

A tibble object with observation dates and values.

API Documentation

fred/series/observations

Examples

if (fredr_has_key()) {
# Observations for "UNRATE" series between 1980 and 2000.  Units are in terms
# of change from previous observation.
fredr(
  series_id = "UNRATE",
  observation_start = as.Date("1980-01-01"),
  observation_end = as.Date("2000-01-01"),
  units = "chg"
)
# All observations for "OILPRICE" series.  The data is first aggregated by
# quarter by taking the average of all observations in the quarter then
# transformed by taking the natural logarithm.
fredr(
  series_id = "OILPRICE",
  frequency = "q",
  aggregation_method = "avg",
  units = "log"
)

# To retrieve values for multiple series, use purrr's map_dfr() function.

if (requireNamespace("purrr", quietly = TRUE)) {

  library(purrr)
  purrr::map_dfr(c("UNRATE", "OILPRICE"), fredr)

  # Using purrr::pmap_dfr() allows you to use varying optional parameters
  params <- list(
    series_id = c("UNRATE", "OILPRICE"),
    frequency = c("m", "q")
  )

  purrr::pmap_dfr(
    .l = params,
    .f = ~ fredr(series_id = .x, frequency = .y)
  )

}

}
#> # A tibble: 1,174 × 5
#>    date       series_id value realtime_start realtime_end
#>    <date>     <chr>     <dbl> <date>         <date>      
#>  1 1948-01-01 UNRATE      3.4 2023-04-17     2023-04-17  
#>  2 1948-02-01 UNRATE      3.8 2023-04-17     2023-04-17  
#>  3 1948-03-01 UNRATE      4   2023-04-17     2023-04-17  
#>  4 1948-04-01 UNRATE      3.9 2023-04-17     2023-04-17  
#>  5 1948-05-01 UNRATE      3.5 2023-04-17     2023-04-17  
#>  6 1948-06-01 UNRATE      3.6 2023-04-17     2023-04-17  
#>  7 1948-07-01 UNRATE      3.6 2023-04-17     2023-04-17  
#>  8 1948-08-01 UNRATE      3.9 2023-04-17     2023-04-17  
#>  9 1948-09-01 UNRATE      3.8 2023-04-17     2023-04-17  
#> 10 1948-10-01 UNRATE      3.7 2023-04-17     2023-04-17  
#> # ℹ 1,164 more rows