Economic Research from the Federal Reserve Bank of St. Louis

fred/series/observations

• Description
• Example
  • Request
  • Response
• Parameters
  • api_key
  • series_id
  • realtime_start
  • realtime_end
  • limit
  • offset
  • sort_order
  • observation_start
  • observation_end
  • units
  • frequency
  • aggregation_method
  • output_type
  • file_type
  • vintage_dates

Description

Get the observations or data values for an economic data series.

Example

Request (HTTP GET)

http://api.stlouisfed.org/fred/series/observations?series_id=GNPCA&api_key=abcdefghijklmnopqrstuvwxyz123456

Note that API key 'abcdefghijklmnopqrstuvwxyz123456' is for demonstration purposes only. Use a registered API key instead.

Response

<?xml version="1.0" encoding="utf-8" ?>
<observations realtime_start="2008-07-29" realtime_end="2008-07-29" observation_start="1776-07-04" observation_end="9999-12-31" units="lin" output_type="1" file_type="xml" order_by="observation_date" sort_order="asc" count="79" offset="0" limit="100000">
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1929-01-01" value="872.6"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1930-01-01" value="797.8"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1931-01-01" value="745.7"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1932-01-01" value="648.4"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1933-01-01" value="639.5"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1934-01-01" value="707.8"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1935-01-01" value="771.1"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1936-01-01" value="870.3"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1937-01-01" value="915.9"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1938-01-01" value="884.7"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1939-01-01" value="955.9"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1940-01-01" value="1038.5"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1941-01-01" value="1217.0"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1942-01-01" value="1441.3"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1943-01-01" value="1676.7"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1944-01-01" value="1812.6"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1945-01-01" value="1791.6"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1946-01-01" value="1596.1"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1947-01-01" value="1583.5"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1948-01-01" value="1654.0"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1949-01-01" value="1644.5"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1950-01-01" value="1788.2"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1951-01-01" value="1928.4"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1952-01-01" value="2002.1"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1953-01-01" value="2092.8"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1954-01-01" value="2079.4"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1955-01-01" value="2228.5"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1956-01-01" value="2273.1"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1957-01-01" value="2319.2"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1958-01-01" value="2294.7"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1959-01-01" value="2457.4"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1960-01-01" value="2519.4"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1961-01-01" value="2579.3"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1962-01-01" value="2736.9"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1963-01-01" value="2857.2"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1964-01-01" value="3023.6"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1965-01-01" value="3217.3"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1966-01-01" value="3423.7"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1967-01-01" value="3510.1"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1968-01-01" value="3680.0"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1969-01-01" value="3792.0"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1970-01-01" value="3798.2"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1971-01-01" value="3927.8"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1972-01-01" value="4136.2"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1973-01-01" value="4383.6"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1974-01-01" value="4367.5"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1975-01-01" value="4348.4"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1976-01-01" value="4585.3"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1977-01-01" value="4800.3"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1978-01-01" value="5064.4"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1979-01-01" value="5240.1"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1980-01-01" value="5227.6"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1981-01-01" value="5349.7"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1982-01-01" value="5249.7"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1983-01-01" value="5482.5"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1984-01-01" value="5869.3"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1985-01-01" value="6093.4"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1986-01-01" value="6290.6"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1987-01-01" value="6500.9"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1988-01-01" value="6775.2"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1989-01-01" value="7015.4"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1990-01-01" value="7155.2"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1991-01-01" value="7136.8"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1992-01-01" value="7371.8"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1993-01-01" value="7568.6"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1994-01-01" value="7864.2"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1995-01-01" value="8069.8"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1996-01-01" value="8365.3"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1997-01-01" value="8737.5"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1998-01-01" value="9088.7"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="1999-01-01" value="9504.7"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="2000-01-01" value="9855.9"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="2001-01-01" value="9933.6"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="2002-01-01" value="10079.0"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="2003-01-01" value="10355.3"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="2004-01-01" value="10746.0"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="2005-01-01" value="11064.7"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="2006-01-01" value="11370.1"/>
  <observation realtime_start="2008-07-29" realtime_end="2008-07-29" date="2007-01-01" value="11647.6"/>
</observations>

Parameters

api_key

Read API Keys for more information.

• 32 character alpha-numeric lowercase string, required

series_id

The id for a series.

• string, required

realtime_start

The start of the real-time period. For more information, see Real-Time Periods.

• YYYY-MM-DD formatted string, optional, default: today's date

realtime_end

The end of the real-time period. For more information, see Real-Time Periods.

• YYYY-MM-DD formatted string, optional, default: today's date

limit

The maximum number of results to return.

• integer between 1 and 100000, optional, default: 100000

offset

• non-negative integer, optional, default: 0

sort_order

Sort results is ascending or descending observation_date order.

• One of the following strings: 'asc', 'desc'.
• optional, default: asc

observation_start

The start of the observation period.

• YYYY-MM-DD formatted string, optional, default: 1776-07-04 (earliest available)

observation_end

The end of the observation period.

• YYYY-MM-DD formatted string, optional, default: 9999-12-31 (latest available)

units

A key that indicates a data value transformation.

• string, 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 Log

• For unit transformation formulas, see: http://alfred.stlouisfed.org/help#growth_formulas

frequency

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.

• string, 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 = Bi-Weekly
  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 = Bi-Weekly, Ending Wednesday
  bwem = Bi-Weekly, 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' (as returned by the fred/series request), 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' (as returned by the fred/series request), 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 bi-weekly frequencies.

  • The weekly and bi-weekly 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 'Bi-Weekly, 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'.

• Note that frequency aggregation is currently only available for file_type = xml due to time constraints.

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

aggregation_method

A key that indicates the aggregation method used for frequency aggregation. This parameter has no affect if the frequency parameter is not set.

• string, optional, default: avg
• One of the following values: 'avg', 'sum', 'eop'

  avg = Average
  sum = Sum
  eop = End of Period

output_type

An integer that indicates an output type.

• integer, 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

• For more information, read: http://alfred.stlouisfed.org/help/downloaddata#outputformats

file_type

A key or file extension that indicates the type of file to send.

• string, optional, default: xml
• One of the following values: 'xml', 'txt', 'xls'

  xml = Extensible Markup Language
  txt = Tab delimited Text
  xls = Excel Spreadsheet

• Note that if txt or xls is specified then the HTTP Content-Type is application/zip. The application/zip content type is sent to compress and group multiple files as one. The zip file contains the specified file format text or Excel. If xml is specified, the HTTP Content-Type is text/xml.

vintage_dates

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.

Sometimes it may be useful to enter a vintage date that is not a date when the data values were revised. For instance you may want to know the latest available revisions on 2001-09-11 (World Trade Center and Pentagon attacks) or as of a Federal Open Market Committee (FOMC) meeting date. Entering a vintage date is also useful to compare series on different releases with different release dates.

• string, optional, no vintage dates are set by default.