skills/fred-economic-data
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e99c3e1ec9a8f9dc0115b4fb6a86d3d2c9ddf487
fred-economic-data/references/series.md
dfty e99c3e1ec9 Initial commit for fred-economic-data
2026-01-28 12:43:41 +08:00

14 KiB
Raw Blame History

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

Parameter Type Description
api_key string 32-character API key
series_id string Series identifier (e.g., "GDP", "UNRATE")

Optional Parameters

Parameter Type Default Description
file_type string xml xml or json
realtime_start date today YYYY-MM-DD
realtime_end date today YYYY-MM-DD

Response Fields

Field Description
id Series identifier
title Series title
observation_start First observation date
observation_end Last observation date
frequency Data frequency
units Units of measurement
seasonal_adjustment Seasonal adjustment status
last_updated Last update timestamp
popularity Popularity ranking (0-100)
notes Series description/notes

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

Parameter Type Description
api_key string 32-character API key
series_id string Series identifier

Optional Parameters

Parameter Type Default Description
file_type string xml xml, json, xlsx, csv
realtime_start date today YYYY-MM-DD
realtime_end date today YYYY-MM-DD
limit integer 100000 1-100000
offset integer 0 Pagination offset
sort_order string asc asc, desc
observation_start date 1776-07-04 Filter start date
observation_end date 9999-12-31 Filter end date
units string lin Data transformation
frequency string none Frequency aggregation
aggregation_method string avg avg, sum, eop
output_type integer 1 Output format type
vintage_dates string none Comma-separated dates

Units Transformation Options

Value Description
lin Levels (no transformation)
chg Change from previous period
ch1 Change from year ago
pch Percent change from previous period
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

Frequency Codes

Code Frequency
d Daily
w Weekly
bw Biweekly
m Monthly
q Quarterly
sa Semiannual
a Annual
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

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

Parameter Type Description
api_key string 32-character API key
series_id string Series identifier

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

Parameter Type Description
api_key string 32-character API key
series_id string Series identifier

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

Parameter Type Description
api_key string 32-character API key

Optional Parameters

Parameter Type Default Description
search_text string - Keywords to search
file_type string xml xml or json
search_type string full_text full_text or series_id
limit integer 1000 1-1000
offset integer 0 Pagination offset
order_by string varies Ordering field
sort_order string varies asc or desc
filter_variable string - frequency, units, seasonal_adjustment
filter_value string - Value for filter
tag_names string - Semicolon-delimited tags
exclude_tag_names string - Tags to exclude

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

Parameter Type Description
api_key string 32-character API key
series_id string Series identifier

Optional Parameters

Parameter Type Default Description
file_type string xml xml or json
order_by string series_count series_count, popularity, created, name, group_id
sort_order string asc asc or desc

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

Parameter Type Description
api_key string 32-character API key

Optional Parameters

Parameter Type Default Description
file_type string xml xml or json
limit integer 1000 1-1000
offset integer 0 Pagination offset
filter_value string all macro, regional, or all
start_time string - YYYYMMDDHhmm format
end_time string - YYYYMMDDHhmm format

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

Parameter Type Description
api_key string 32-character API key
series_id string Series identifier

Optional Parameters

Parameter Type Default Description
file_type string xml xml or json
realtime_start date 1776-07-04 YYYY-MM-DD
realtime_end date 9999-12-31 YYYY-MM-DD
limit integer 10000 1-10000
offset integer 0 Pagination offset
sort_order string asc asc or desc

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

Parameter Type Description
api_key string 32-character API key
series_search_text string Search text

Optional Parameters

Parameter Type Default Description
file_type string xml xml or json
tag_names string - Semicolon-delimited tags
tag_group_id string - freq, gen, geo, geot, rls, seas, src
tag_search_text string - Filter tags by text
limit integer 1000 1-1000
offset integer 0 Pagination offset
order_by string series_count series_count, popularity, created, name, group_id
sort_order string asc asc or desc

fred/series/search/related_tags

Get related tags for a series search.

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

Required Parameters

Parameter Type Description
api_key string 32-character API key
series_search_text string Search text
tag_names string Semicolon-delimited tags

Optional Parameters

Parameter Type Default Description
file_type string xml xml or json
exclude_tag_names string - Tags to exclude
tag_group_id string - freq, gen, geo, geot, rls, seas, src
tag_search_text string - Filter tags
limit integer 1000 1-1000
offset integer 0 Pagination offset
order_by string series_count Ordering field
sort_order string asc asc or desc

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"
    }
)
Reference in New Issue View Git Blame Copy Permalink