fred_load#

Purpose#

Get the observations or data values for one or more economic data series.

Format#

x = fred_load(formula[, ...])#
Parameters:

  • formula (string) – Formula string made up of one or more series ids to fetch. Can be a single series id. See loadd() for reference on applying transformations. required

  • options (key, value pairs) –

    Options to pass to the API. See below. These can be set directly when calling the function in the form of consecutive (key, value) pairs or via a dataframe constructed with fred_set(). All arguments can be specified in any order. For example:

    /* Retrieve the 'GNPCA' series with the following arguments:
**   realtime_start = 2010-01-01
**   realtime_end   = 2010-12-31
**   frequency      = m
*/

fred_load("GNPCA", "realtime_start", "2010-01-01", "realtime_end", "2010-12-31", "frequency", "m");

    This function supports the following options:

    realtime_start

    YYYY-MM-DD formatted string. The start of the real-time period. For more information, see Remarks. optional, default: today’s date

    realtime_end

    YYYY-MM-DD formatted string. The end of the real-time period. For more information, see Remarks. optional, default: today’s date

    limit

    integer between 1 and 100000. The maximum number of results to return. optional, default: 100000

    offset

    non-negative integer. Sort results is ascending or descending observation_date order. optional, default: 0

    sort_order

    String. Sort results in ascending or descending order for attribute values specified by order_by. One of the following strings: ‘asc’, ‘desc’. optional, default: asc

    observation_start

    YYYY-MM-DD formatted string. The start of the observation period. optional, default: 1776-07-04 (earliest available)

    observation_end

    YYYY-MM-DD formatted string. The end of the observation period. optional, default: 9999-12-31 (latest available)

    units

    string. A key that indicates a data value transformation. optional, default: lin (No transformation)

    One of the following values: ‘lin’, ‘chg’, ‘ch1’, ‘pch’, ‘pc1’, ‘pca’, ‘cch’, ‘cca’, ‘log’

    • lin = Levels (No transformation)

    • chg = Change

    • ch1 = Change from Year Ago

    • pch = Percent Change

    • pc1 = Percent Change from Year Ago

    • pca = Compounded Annual Rate of Change

    • cch = Continuously Compounded Rate of Change

    • cca = Continuously Compounded Annual Rate of Change

    • log = Natural LogFor unit transformation formulas, see:

    Read more at https://alfred.stlouisfed.org/help#growth_formulas

    frequency

    string. An optional parameter that indicates a lower frequency to aggregate values to. The FRED frequency aggregation feature converts higher frequency data series into lower frequency data series (e.g. converts a monthly data series into an annual data series). In FRED, the highest frequency data is daily, and the lowest frequency data is annual. There are 3 aggregation methods available- average, sum, and end of period. See the aggregation_method parameter.

    • optional, default: no value for no frequency aggregation

    • One of the following values: ‘d’, ‘w’, ‘bw’, ‘m’, ‘q’, ‘sa’, ‘a’, ‘wef’, ‘weth’, ‘wew’, ‘wetu’, ‘wem’, ‘wesu’, ‘wesa’, ‘bwew’, ‘bwem’

      Frequencies without period descriptions:

      • d = Daily

      • w = Weekly

      • bw = Biweekly

      • m = Monthly

      • q = Quarterly

      • sa = Semiannual

      • a = Annual

      Frequencies with period descriptions:

      • wef = Weekly, Ending Friday

      • weth = Weekly, Ending Thursday

      • wew = Weekly, Ending Wednesday

      • wetu = Weekly, Ending Tuesday

      • wem = Weekly, Ending Monday

      • wesu = Weekly, Ending Sunday

      • wesa = Weekly, Ending Saturday

      • bwew = Biweekly, Ending Wednesday

      • bwem = Biweekly, Ending Monday

    • Note that an error will be returned if a frequency is specified that is higher than the native frequency of the series. For instance if a series has the native frequency ‘Monthly’, it is not possible to aggregate the series to the higher ‘Daily’ frequency using the frequency parameter value ‘d’.

    • No frequency aggregation will occur if the frequency specified by the frequency parameter matches the native frequency of the series. For instance if the value of the frequency parameter is ‘m’ and the native frequency of the series is ‘Monthly’, observations will be returned, but they will not be aggregated to a lower frequency.

    • For most cases, it will be sufficient to specify a lower frequency without a period description (e.g. ‘d’, ‘w’, ‘bw’, ‘m’, ‘q’, ‘sa’, ‘a’) as opposed to frequencies with period descriptions (e.g. ‘wef’, ‘weth’, ‘wew’, ‘wetu’, ‘wem’, ‘wesu’, ‘wesa’, ‘bwew’, ‘bwem’) which only exist for the weekly and biweekly frequencies.

      • The weekly and biweekly frequencies with periods exist to offer more options and override the default periods implied by values ‘w’ and ‘bw’.

      • The value ‘w’ defaults to frequency and period ‘Weekly, Ending Friday’ when aggregating daily series.

      • The value ‘bw’ defaults to frequency and period ‘Biweekly, Ending Wednesday’ when aggregating daily and weekly series.

      • Consider the difference between values ‘w’ for ‘Weekly’ and ‘wef’ for ‘Weekly, Ending Friday’. When aggregating observations from daily to weekly, the value ‘w’ defaults to frequency and period ‘Weekly, Ending Friday’ which is the same as ‘wef’. Here, the difference is that the period ‘Ending Friday’ is implicit for value ‘w’ but explicit for value ‘wef’. However, if a series has native frequency ‘Weekly, Ending Monday’, an error will be returned for value ‘wef’ but not value ‘w’.

    • Read the ‘Frequency Aggregation’ section of the FRED FAQs for implementation details.

    aggregation_method

    string. A key that indicates the aggregation method used for frequency aggregation. This parameter has no affect if the frequency parameter is not set. optional, default: avg

    One of the following values: ‘avg’, ‘sum’, ‘eop’

    • avg = Average

    • sum = Sum

    • eop = End of Period

    output_type

    integer. An integer that indicates an output type. optional, default: 1

    One of the following values: ‘1’, ‘2’, ‘3’, ‘4’

    • 1 = Observations by Real-Time Period

    • 2 = Observations by Vintage Date, All Observations

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

    • 4 = Observations, Initial Release Only

    vintage_dates

    string. A comma separated string of YYYY-MM-DD formatted dates in history (e.g. 2000-01-01,2005-02-24).

    • Vintage dates are used to download data as it existed on these specified dates in history.

    • Vintage dates can be specified instead of a real-time period using realtime_start and realtime_end. optional, no vintage dates are set by default.

Returns:

x (Dataframe) – Results.

Examples#

Fetch a single series#

x = fred_load("DGDSRL1A225NBEA");

the first 5 rows of the dataframe are:

      date  DGDSRL1A225NBEA
1930-01-01       -7.9000000
1931-01-01       -3.6000000
1932-01-01       -11.700000
1933-01-01      -0.70000000
1934-01-01        9.1000000

Fetch multiple series#

x = fred_load("DGDSRL1A225NBEA + DDURRL1A225NBEA + DNDGRL1A225NBEA");

the first 5 rows of the dataframe are:

      date  DDURRL1A225NBEA  DGDSRL1A225NBEA  DNDGRL1A225NBEA
1930-01-01       -17.200000       -7.9000000       -5.2000000
1931-01-01       -13.600000       -3.6000000       -1.1000000
1932-01-01       -24.000000       -11.700000       -8.8000000
1933-01-01       -2.6000000      -0.70000000      -0.40000000
1934-01-01        14.400000        9.1000000        8.2000000

Fetch series with inline arguments#

x = fred_load("GNPCA", "realtime_start", "1980-01-01", "realtime_end", "1989-12-31")

the first 5 rows of the dataframe are:

      date            GNPCA
1929-01-01        314.70000
1929-01-01        315.70000
1929-01-01        709.60000
1930-01-01        285.20000
1930-01-01        285.60000

Remarks#

API Key#

This function requires a valid API key. Please visit https://fred.stlouisfed.org/docs/api/api_key.html to find out more on how to obtain one.

Set your API key using any of the following methods in GAUSS:

  1. Set the API key directly at the top of your program:

    FRED_API_KEY = "your_api_key"

  2. Set the environment variable FRED_API_KEY to your API key.

  3. Edit your gauss.cfg file and modify the fred_api_key value:

    fred_api_key = your_api_key

Disclaimer#

Note

This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis.

Real-Time Periods#

You can read extensively about the real-time period parameters directly on the FRED Website at https://fred.stlouisfed.org/docs/api/fred/realtime_period.html

Per the FRED website:

The real-time period marks when facts were true or when information was known until it changed. Economic data sources, releases, series, and observations are all assigned a real-time period. Sources, releases, and series can change their names, and observation data values can be revised.

On almost all URLs, the default real-time period is today. This can be thought of as FRED® mode- what information about the past is available today. ALFRED® users can change the real-time period to retrieve information that was known as of a past period of history.

The real-time period can be specified by setting the realtime_start and realtime_end variables. Variables realtime_start and realtime_end are optional YYYY-MM-DD formatted dates that default to today’s date. The real-time period set by realtime_start and realtime_end is a (closed, closed) period. This means that the real-time period includes the dates or boundaries set by realtime_start and realtime_end.

See also

fred_load(), fred_search(), fred_set()

On this page