FRED Series Endpoints

FRED Series Endpoints

Series endpoints provide access to economic data series metadata and observations.

Table of Contents

1. fred/series - Get series metadata
2. fred/series/observations - Get data values
3. fred/series/categories - Get series categories
4. fred/series/release - Get series release
5. fred/series/search - Search for series
6. fred/series/tags - Get series tags
7. fred/series/updates - Get recently updated series
8. fred/series/vintagedates - Get vintage dates
9. fred/series/search/tags - Get tags for search
10. fred/series/search/related_tags - Get related tags for search

fred/series

Get metadata for an economic data series.

URL: https://api.stlouisfed.org/fred/series

Required Parameters

Optional Parameters

Response Fields

Example

response = requests.get(
    "https://api.stlouisfed.org/fred/series",
    params={
        "api_key": API_KEY,
        "series_id": "GNPCA",
        "file_type": "json"
    }
)

Response

{
  "seriess": [
    {
      "id": "GNPCA",
      "title": "Real Gross National Product",
      "observation_start": "1929-01-01",
      "observation_end": "2022-01-01",
      "frequency": "Annual",
      "units": "Billions of Chained 2017 Dollars",
      "seasonal_adjustment": "Not Seasonally Adjusted",
      "last_updated": "2023-03-30 07:52:02-05",
      "popularity": 39,
      "notes": "BEA Account Code: A001RX..."
    }
  ]
}

fred/series/observations

Get observations (data values) for an economic data series. Most commonly used endpoint.

URL: https://api.stlouisfed.org/fred/series/observations

Required Parameters

Optional Parameters

Units Transformation Options

Frequency Codes

Example

# Get quarterly GDP with percent change transformation
response = requests.get(
    "https://api.stlouisfed.org/fred/series/observations",
    params={
        "api_key": API_KEY,
        "series_id": "GDP",
        "file_type": "json",
        "observation_start": "2020-01-01",
        "units": "pch"
    }
)

Response

{
  "realtime_start": "2023-08-14",
  "realtime_end": "2023-08-14",
  "observation_start": "2020-01-01",
  "observation_end": "9999-12-31",
  "units": "Percent Change",
  "output_type": 1,
  "file_type": "json",
  "order_by": "observation_date",
  "sort_order": "asc",
  "count": 14,
  "offset": 0,
  "limit": 100000,
  "observations": [
    {
      "realtime_start": "2023-08-14",
      "realtime_end": "2023-08-14",
      "date": "2020-01-01",
      "value": "1.1"
    },
    {
      "realtime_start": "2023-08-14",
      "realtime_end": "2023-08-14",
      "date": "2020-04-01",
      "value": "-8.3"
    }
  ]
}

fred/series/categories

Get the categories for an economic data series.

URL: https://api.stlouisfed.org/fred/series/categories

Required Parameters

Example

response = requests.get(
    "https://api.stlouisfed.org/fred/series/categories",
    params={
        "api_key": API_KEY,
        "series_id": "EXJPUS",
        "file_type": "json"
    }
)

Response

{
  "categories": [
    {"id": 95, "name": "Monthly Rates", "parent_id": 15},
    {"id": 275, "name": "Japan", "parent_id": 158}
  ]
}

fred/series/release

Get the release for an economic data series.

URL: https://api.stlouisfed.org/fred/series/release

Required Parameters

Example

response = requests.get(
    "https://api.stlouisfed.org/fred/series/release",
    params={
        "api_key": API_KEY,
        "series_id": "GDP",
        "file_type": "json"
    }
)

Response

{
  "releases": [
    {
      "id": 53,
      "name": "Gross Domestic Product",
      "press_release": true,
      "link": "http://www.bea.gov/national/index.htm"
    }
  ]
}

fred/series/search

Search for economic data series by keywords.

URL: https://api.stlouisfed.org/fred/series/search

Required Parameters

Optional Parameters

Order By Options

• search_rank (default for full_text)
• series_id (default for series_id)
• title
• units
• frequency
• seasonal_adjustment
• realtime_start
• realtime_end
• last_updated
• observation_start
• observation_end
• popularity
• group_popularity

Example

# Search for inflation-related series
response = requests.get(
    "https://api.stlouisfed.org/fred/series/search",
    params={
        "api_key": API_KEY,
        "search_text": "consumer price index",
        "file_type": "json",
        "limit": 10,
        "filter_variable": "frequency",
        "filter_value": "Monthly"
    }
)

Response

{
  "count": 1234,
  "offset": 0,
  "limit": 10,
  "seriess": [
    {
      "id": "CPIAUCSL",
      "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
      "observation_start": "1947-01-01",
      "observation_end": "2023-07-01",
      "frequency": "Monthly",
      "units": "Index 1982-1984=100",
      "seasonal_adjustment": "Seasonally Adjusted",
      "popularity": 95
    }
  ]
}

fred/series/tags

Get the FRED tags for a series.

URL: https://api.stlouisfed.org/fred/series/tags

Required Parameters

Optional Parameters

Example

response = requests.get(
    "https://api.stlouisfed.org/fred/series/tags",
    params={
        "api_key": API_KEY,
        "series_id": "GDP",
        "file_type": "json"
    }
)

Response

{
  "tags": [
    {"name": "gdp", "group_id": "gen", "series_count": 21862},
    {"name": "quarterly", "group_id": "freq", "series_count": 180000},
    {"name": "usa", "group_id": "geo", "series_count": 400000}
  ]
}

fred/series/updates

Get economic data series sorted by when observations were updated.

URL: https://api.stlouisfed.org/fred/series/updates

Required Parameters

Optional Parameters

Note: Results are restricted to series updated within the last two weeks.

Example

response = requests.get(
    "https://api.stlouisfed.org/fred/series/updates",
    params={
        "api_key": API_KEY,
        "file_type": "json",
        "filter_value": "macro",
        "limit": 10
    }
)

fred/series/vintagedates

Get the vintage dates for a series (dates when data was revised).

URL: https://api.stlouisfed.org/fred/series/vintagedates

Required Parameters

Optional Parameters

Example

response = requests.get(
    "https://api.stlouisfed.org/fred/series/vintagedates",
    params={
        "api_key": API_KEY,
        "series_id": "GDP",
        "file_type": "json"
    }
)

Response

{
  "count": 250,
  "vintage_dates": [
    "1991-12-04",
    "1992-01-29",
    "1992-02-28"
  ]
}

fred/series/search/tags

Get the tags for a series search.

URL: https://api.stlouisfed.org/fred/series/search/tags

Required Parameters

Optional Parameters

fred/series/search/related_tags

Get related tags for a series search.

URL: https://api.stlouisfed.org/fred/series/search/related_tags

Required Parameters

Optional Parameters

Example

response = requests.get(
    "https://api.stlouisfed.org/fred/series/search/related_tags",
    params={
        "api_key": API_KEY,
        "series_search_text": "mortgage rate",
        "tag_names": "30-year;frb",
        "file_type": "json"
    }
)