Economic data series metadata, search, categorization, release linkage, tags, updates, and vintages.
openapi: 3.0.3
info:
title: FRED Maps API (GeoFRED) Categories Series API
version: '1.0'
description: GeoFRED (the FRED Maps API) exposes geographic / regional views of FRED economic data. Series-group metadata, regional-data lookups across geographies (state, county, MSA, country, census tract, etc.), and GeoJSON shape files for cartographic rendering of FRED indicators.
contact:
name: Federal Reserve Bank of St. Louis — Research Division
url: https://fred.stlouisfed.org/docs/api/geofred/
license:
name: U.S. Government Work / Public Domain (most series)
url: https://fred.stlouisfed.org/legal/
termsOfService: https://fred.stlouisfed.org/legal/
x-generated-from: documentation
x-last-validated: '2026-05-28'
servers:
- url: https://api.stlouisfed.org/geofred
description: Production GeoFRED API
security:
- ApiKeyAuth: []
tags:
- name: Series
description: Economic data series metadata, search, categorization, release linkage, tags, updates, and vintages.
paths:
/series:
get:
operationId: getSeries
summary: FRED Get an Economic Data Series
description: Get an economic data series by ID.
tags:
- Series
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/FileType'
- name: series_id
in: query
required: true
schema:
type: string
description: The FRED series ID (e.g. GNPCA
UNRATE).: null
example: UNRATE
- $ref: '#/components/parameters/RealtimeStart'
- $ref: '#/components/parameters/RealtimeEnd'
responses:
'200':
description: A single series.
content:
application/json:
schema:
$ref: '#/components/schemas/SeriesList'
examples:
Getseries200Example:
summary: Default getSeries 200 response
x-microcks-default: true
value:
realtime_start: '2026-05-28'
realtime_end: '2026-05-28'
order_by: series_id
sort_order: asc
count: 1
offset: 0
limit: 1000
seriess:
- id: UNRATE
realtime_start: '2026-05-28'
realtime_end: '2026-05-28'
title: Unemployment Rate
observation_start: '1948-01-01'
observation_end: '2026-04-01'
frequency: Monthly
frequency_short: M
units: Percent
units_short: '%'
seasonal_adjustment: Seasonally Adjusted
seasonal_adjustment_short: SA
last_updated: '2026-05-02 07:46:10-05'
popularity: 95
group_popularity: 95
notes: The unemployment rate represents the number of unemployed as a percentage of the labor force.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/series/categories:
get:
operationId: getSeriesCategories
summary: FRED Get the Categories for an Economic Data Series
description: Get the categories for an economic data series.
tags:
- Series
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/FileType'
- name: series_id
in: query
required: true
schema:
type: string
description: The FRED series ID.
example: UNRATE
- $ref: '#/components/parameters/RealtimeStart'
- $ref: '#/components/parameters/RealtimeEnd'
responses:
'200':
description: Categories that contain the series.
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryList'
examples:
Getseriescategories200Example:
summary: Default getSeriesCategories 200 response
x-microcks-default: true
value:
categories:
- id: 125
name: Trade Balance
parent_id: 13
- id: 13
name: International Data
parent_id: 0
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/series/release:
get:
operationId: getSeriesRelease
summary: FRED Get the Release for an Economic Data Series
description: Get the release for an economic data series.
tags:
- Series
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/FileType'
- name: series_id
in: query
required: true
schema:
type: string
description: The FRED series ID.
example: UNRATE
- $ref: '#/components/parameters/RealtimeStart'
- $ref: '#/components/parameters/RealtimeEnd'
responses:
'200':
description: Release for the series.
content:
application/json:
schema:
$ref: '#/components/schemas/ReleaseList'
examples:
Getseriesrelease200Example:
summary: Default getSeriesRelease 200 response
x-microcks-default: true
value:
realtime_start: '2026-05-28'
realtime_end: '2026-05-28'
order_by: release_id
sort_order: asc
count: 326
offset: 0
limit: 1000
releases:
- id: 9
realtime_start: '2026-05-28'
realtime_end: '2026-05-28'
name: Advance Monthly Sales for Retail and Food Services
press_release: true
link: http://www.census.gov/retail/
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/series/search:
get:
operationId: searchSeries
summary: FRED Get Economic Data Series That Match Keywords
description: Get economic data series that match keywords.
tags:
- Series
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/FileType'
- name: search_text
in: query
required: true
schema:
type: string
description: Words to match against series IDs
titles: null
units: null
frequencies: null
and notes.: null
example: monetary aggregates
- name: search_type
in: query
schema:
type: string
enum:
- full_text
- series_id
default: full_text
description: Type of search.
- $ref: '#/components/parameters/RealtimeStart'
- $ref: '#/components/parameters/RealtimeEnd'
- $ref: '#/components/parameters/Limit1000'
- $ref: '#/components/parameters/Offset'
- name: order_by
in: query
schema:
type: string
enum:
- search_rank
- series_id
- title
- units
- frequency
- seasonal_adjustment
- realtime_start
- realtime_end
- last_updated
- observation_start
- observation_end
- popularity
- group_popularity
description: Ordering field.
example: series_count
- $ref: '#/components/parameters/SortOrder'
- $ref: '#/components/parameters/FilterVariable'
- $ref: '#/components/parameters/FilterValue'
- $ref: '#/components/parameters/TagNames'
- $ref: '#/components/parameters/ExcludeTagNames'
responses:
'200':
description: Series matching the search.
content:
application/json:
schema:
$ref: '#/components/schemas/SeriesList'
examples:
Searchseries200Example:
summary: Default searchSeries 200 response
x-microcks-default: true
value:
realtime_start: '2026-05-28'
realtime_end: '2026-05-28'
order_by: series_id
sort_order: asc
count: 1
offset: 0
limit: 1000
seriess:
- id: UNRATE
realtime_start: '2026-05-28'
realtime_end: '2026-05-28'
title: Unemployment Rate
observation_start: '1948-01-01'
observation_end: '2026-04-01'
frequency: Monthly
frequency_short: M
units: Percent
units_short: '%'
seasonal_adjustment: Seasonally Adjusted
seasonal_adjustment_short: SA
last_updated: '2026-05-02 07:46:10-05'
popularity: 95
group_popularity: 95
notes: The unemployment rate represents the number of unemployed as a percentage of the labor force.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/series/search/tags:
get:
operationId: searchSeriesTags
summary: FRED Get the Tags for a Series Search
description: Get the FRED tags for a series search. Find tags that match the search text and are also assigned to series matching that search.
tags:
- Series
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/FileType'
- name: series_search_text
in: query
required: true
schema:
type: string
description: Words to match against series titles.
example: monetary
- $ref: '#/components/parameters/RealtimeStart'
- $ref: '#/components/parameters/RealtimeEnd'
- $ref: '#/components/parameters/TagNames'
- $ref: '#/components/parameters/TagGroupId'
- name: tag_search_text
in: query
schema:
type: string
description: Words to match against tag names.
example: usa
- $ref: '#/components/parameters/Limit1000'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/OrderByTags'
- $ref: '#/components/parameters/SortOrder'
responses:
'200':
description: Tags for the series search.
content:
application/json:
schema:
$ref: '#/components/schemas/TagList'
examples:
Searchseriestags200Example:
summary: Default searchSeriesTags 200 response
x-microcks-default: true
value:
realtime_start: '2026-05-28'
realtime_end: '2026-05-28'
order_by: series_count
sort_order: desc
count: 2
offset: 0
limit: 1000
tags:
- name: monthly
group_id: freq
notes: ''
created: '2012-02-27 10:18:19-06'
popularity: 100
series_count: 380000
- name: nation
group_id: geot
notes: ''
created: '2012-02-27 10:18:19-06'
popularity: 99
series_count: 110000
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/series/search/related_tags:
get:
operationId: searchSeriesRelatedTags
summary: FRED Get the Related Tags for a Series Search
description: Get the related FRED tags for one or more FRED tags matching a series search.
tags:
- Series
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/FileType'
- name: series_search_text
in: query
required: true
schema:
type: string
description: Words to match against series titles.
example: monetary
- $ref: '#/components/parameters/RealtimeStart'
- $ref: '#/components/parameters/RealtimeEnd'
- $ref: '#/components/parameters/TagNames'
- $ref: '#/components/parameters/ExcludeTagNames'
- $ref: '#/components/parameters/TagGroupId'
- name: tag_search_text
in: query
schema:
type: string
description: Words to match against tag names.
example: usa
- $ref: '#/components/parameters/Limit1000'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/OrderByTags'
- $ref: '#/components/parameters/SortOrder'
responses:
'200':
description: Related tags for the series search.
content:
application/json:
schema:
$ref: '#/components/schemas/TagList'
examples:
Searchseriesrelatedtags200Example:
summary: Default searchSeriesRelatedTags 200 response
x-microcks-default: true
value:
realtime_start: '2026-05-28'
realtime_end: '2026-05-28'
order_by: series_count
sort_order: desc
count: 2
offset: 0
limit: 1000
tags:
- name: monthly
group_id: freq
notes: ''
created: '2012-02-27 10:18:19-06'
popularity: 100
series_count: 380000
- name: nation
group_id: geot
notes: ''
created: '2012-02-27 10:18:19-06'
popularity: 99
series_count: 110000
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/series/tags:
get:
operationId: getSeriesTags
summary: FRED Get the Tags for an Economic Data Series
description: Get the FRED tags for an economic data series.
tags:
- Series
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/FileType'
- name: series_id
in: query
required: true
schema:
type: string
description: The FRED series ID.
example: UNRATE
- $ref: '#/components/parameters/RealtimeStart'
- $ref: '#/components/parameters/RealtimeEnd'
- $ref: '#/components/parameters/OrderByTags'
- $ref: '#/components/parameters/SortOrder'
responses:
'200':
description: Tags for the series.
content:
application/json:
schema:
$ref: '#/components/schemas/TagList'
examples:
Getseriestags200Example:
summary: Default getSeriesTags 200 response
x-microcks-default: true
value:
realtime_start: '2026-05-28'
realtime_end: '2026-05-28'
order_by: series_count
sort_order: desc
count: 2
offset: 0
limit: 1000
tags:
- name: monthly
group_id: freq
notes: ''
created: '2012-02-27 10:18:19-06'
popularity: 100
series_count: 380000
- name: nation
group_id: geot
notes: ''
created: '2012-02-27 10:18:19-06'
popularity: 99
series_count: 110000
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/series/updates:
get:
operationId: getSeriesUpdates
summary: FRED Get Economic Data Series Sorted by Last Updated Date
description: Get economic data series sorted by when observations were updated on the FRED server.
tags:
- Series
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/FileType'
- $ref: '#/components/parameters/RealtimeStart'
- $ref: '#/components/parameters/RealtimeEnd'
- $ref: '#/components/parameters/Limit1000'
- $ref: '#/components/parameters/Offset'
- name: filter_value
in: query
schema:
type: string
enum:
- all
- macro
- regional
default: all
description: Filter results by audience.
example: monthly
- name: start_time
in: query
schema:
type: string
pattern: ^[0-9]{12}$
description: Lower bound for when a series was updated (YYYYMMDDHhmm).
example: '202601010000'
- name: end_time
in: query
schema:
type: string
pattern: ^[0-9]{12}$
description: Upper bound for when a series was updated (YYYYMMDDHhmm).
example: '202605280000'
responses:
'200':
description: Recently updated series.
content:
application/json:
schema:
$ref: '#/components/schemas/SeriesList'
examples:
Getseriesupdates200Example:
summary: Default getSeriesUpdates 200 response
x-microcks-default: true
value:
realtime_start: '2026-05-28'
realtime_end: '2026-05-28'
order_by: series_id
sort_order: asc
count: 1
offset: 0
limit: 1000
seriess:
- id: UNRATE
realtime_start: '2026-05-28'
realtime_end: '2026-05-28'
title: Unemployment Rate
observation_start: '1948-01-01'
observation_end: '2026-04-01'
frequency: Monthly
frequency_short: M
units: Percent
units_short: '%'
seasonal_adjustment: Seasonally Adjusted
seasonal_adjustment_short: SA
last_updated: '2026-05-02 07:46:10-05'
popularity: 95
group_popularity: 95
notes: The unemployment rate represents the number of unemployed as a percentage of the labor force.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/series/vintagedates:
get:
operationId: getSeriesVintageDates
summary: FRED Get the Dates in History When a Series Was Revised or Newly Released
description: Get the dates in history when a series' data values were revised or new data values were released.
tags:
- Series
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/FileType'
- name: series_id
in: query
required: true
schema:
type: string
description: The FRED series ID.
example: UNRATE
- $ref: '#/components/parameters/RealtimeStart'
- $ref: '#/components/parameters/RealtimeEnd'
- $ref: '#/components/parameters/Limit10000'
- $ref: '#/components/parameters/Offset'
- name: sort_order
in: query
schema:
type: string
enum:
- asc
- desc
description: Sort by vintage_date.
example: asc
responses:
'200':
description: Vintage dates for the series.
content:
application/json:
schema:
$ref: '#/components/schemas/VintageDateList'
examples:
Getseriesvintagedates200Example:
summary: Default getSeriesVintageDates 200 response
x-microcks-default: true
value:
realtime_start: '1776-07-04'
realtime_end: '9999-12-31'
order_by: vintage_date
sort_order: asc
count: 2
offset: 0
limit: 10000
vintage_dates:
- '1958-12-21'
- '2026-05-02'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
parameters:
RealtimeStart:
name: realtime_start
in: query
required: false
description: Start of the real-time period (YYYY-MM-DD). Defaults to today.
schema:
type: string
format: date
example: '2026-05-28'
Offset:
name: offset
in: query
required: false
description: Non-negative integer offset into the result set for pagination.
schema:
type: integer
minimum: 0
default: 0
example: 0
SortOrder:
name: sort_order
in: query
required: false
description: Sort order. asc (ascending, default) or desc (descending).
schema:
type: string
enum:
- asc
- desc
default: asc
example: asc
OrderByTags:
name: order_by
in: query
required: false
description: Field to order tag results by.
schema:
type: string
enum:
- series_count
- popularity
- created
- name
- group_id
default: series_count
example: series_count
FileType:
name: file_type
in: query
required: false
description: Response format. xml (default) or json. The observations endpoint additionally accepts xlsx and csv.
schema:
type: string
enum:
- xml
- json
- xlsx
- csv
- txt
default: xml
example: json
FilterValue:
name: filter_value
in: query
required: false
description: Value of the filter_variable attribute to match.
schema:
type: string
example: monthly
RealtimeEnd:
name: realtime_end
in: query
required: false
description: End of the real-time period (YYYY-MM-DD). Defaults to today.
schema:
type: string
format: date
example: '2026-05-28'
Limit10000:
name: limit
in: query
required: false
description: Maximum number of results to return (1–10000).
schema:
type: integer
minimum: 1
maximum: 10000
default: 10000
example: 100
TagGroupId:
name: tag_group_id
in: query
required: false
description: Group identifier for tags — freq, gen, geo, geot, rls, seas, src.
schema:
type: string
enum:
- freq
- gen
- geo
- geot
- rls
- seas
- src
example: freq
Limit1000:
name: limit
in: query
required: false
description: Maximum number of results to return (1–1000).
schema:
type: integer
minimum: 1
maximum: 1000
default: 1000
example: 100
ExcludeTagNames:
name: exclude_tag_names
in: query
required: false
description: Semicolon-separated list of tag names to exclude.
schema:
type: string
example: discontinued
FilterVariable:
name: filter_variable
in: query
required: false
description: Attribute to filter series results by.
schema:
type: string
enum:
- frequency
- units
- seasonal_adjustment
example: frequency
TagNames:
name: tag_names
in: query
required: false
description: Semicolon-separated list of tag names to require.
schema:
type: string
example: monthly;usa
ApiKey:
name: api_key
in: query
required: true
description: 32-character lower-case alphanumeric FRED API key.
schema:
type: string
pattern: ^[0-9a-f]{32}$
example: abcdef0123456789abcdef0123456789
schemas:
VintageDateList:
type: object
description: A list of vintage (release) dates for a series.
properties:
realtime_start:
type: string
format: date
example: '2026-05-28'
realtime_end:
type: string
format: date
example: '2026-05-28'
order_by:
type: string
example: example
sort_order:
type: string
example: example
count:
type: integer
example: 1
offset:
type: integer
example: 0
limit:
type: integer
example: 1000
vintage_dates:
type: array
items:
type: string
format: date
required:
- vintage_dates
Tag:
type: object
description: A FRED tag.
properties:
name:
type: string
description: Lower-case tag name.
example: Unemployment Rate
group_id:
type: string
description: Tag group id (freq
gen: null
geo: null
geot: null
rls: null
seas: null
src).: null
example: freq
notes:
type: string
description: Editorial notes.
example: Editorial notes.
created:
type: string
description: ISO-8601 created timestamp.
example: example
popularity:
type: integer
description: Popularity score 0–100.
example: 95
series_count:
type: integer
description: Number of series carrying this tag.
example: 380000
required:
- name
- group_id
ReleaseList:
type: object
description: A list of FRED releases.
properties:
realtime_start:
type: string
format: date
example: '2026-05-28'
realtime_end:
type: string
format: date
example: '2026-05-28'
order_by:
type: string
example: example
sort_order:
type: string
example: example
count:
type: integer
description: Total count of releases matched.
example: 1
offset:
type: integer
example: 0
limit:
type: integer
example: 1000
releases:
type: array
items:
$ref: '#/components/schemas/Release'
required:
- releases
CategoryList:
type: object
description: A list of FRED categories.
properties:
categories:
type: array
items:
$ref: '#/components/schemas/Category'
required:
- categories
TagList:
type: object
description: A list of FRED tags.
properties:
realtime_start:
type: string
format: date
example: '2026-05-28'
realtime_end:
type: string
format: date
example: '2026-05-28'
order_by:
type: string
example: example
sort_order:
type: string
example: example
count:
type: integer
example: 1
offset:
type: integer
example: 0
limit:
type: integer
example: 1000
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
required:
- tags
Release:
type: object
description: A FRED release of economic data.
properties:
id:
type: integer
description: Numeric release ID.
example: 1
realtime_start:
type: string
format: date
example: '2026-05-28'
realtime_end:
type: string
format: date
example: '2026-05-28'
name:
type: string
description: Display name of the release.
example: Unemployment Rate
press_release:
type: boolean
description: True if this release is also a press release.
example: false
link:
type: string
format: uri
description: Provider link for the release.
example: https://fred.stlouisfed.org/
notes:
type: string
description: Editorial notes.
example: Editorial notes.
required:
- id
- name
SeriesList:
type: object
description: A list of FRED series.
properties:
realtime_start:
type: string
format: date
example: '2026-05-28'
realtime_end:
type: string
format: date
example: '2026-05-28'
order_by:
type: string
example: example
sort_order:
type: string
example: example
count:
type: integer
example: 1
offset:
type: integer
example: 0
limit:
type: integer
example: 1000
seriess:
type: array
description: Array of series (FRED uses the legacy "seriess" key intentionally).
items:
$ref: '#/components/schemas/Series'
required:
- seriess
Category:
type: object
description: A FRED category node.
properties:
id:
type: integer
description: Numeric category ID.
example: 1
name:
type: string
description: Display name of the category.
example: Unemployment Rate
parent_id:
type: integer
description: Parent category ID.
example: 0
notes:
type: string
description: Optional editorial notes.
example: Editorial notes.
required:
- id
- name
- parent_id
Series:
type: object
description: A FRED economic data series and its metadata.
properties:
id:
type: string
description: FRED series ID (e.g. UNRATE
GNPCA).: null
example: UNRATE
realtime_start:
type: string
format: date
example: '2026-05-28'
realtime_end:
type: string
format: date
example: '2026-05-28'
title:
type: string
description: Display title of the series.
example: Unemployment Rate
observation_start:
type: string
format: date
description: First available observation date.
example: '2026-05-28'
observation_end:
type: string
format: date
description: Last available observation date.
example: '2026-05-28'
frequency:
type: string
description: Display frequency (e.g. "Monthly").
example: Monthly
frequency_short:
type: string
description: Frequency code (d
w: null
m: null
q: null
a).: null
example: Monthly
units:
type: string
description: Display unit string.
example: Percent
units_short:
type: string
description: Short unit string.
example: Percent
seasonal_adjustment:
type: string
description: Seasonal adjustment description.
example: Seasonally Adjusted
seasonal_adjustment_short:
type: string
description: Seasonal adjustment code (SA
NSA: null
SAAR: null
NSAAR: null
SSA).: null
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fred/refs/heads/main/openapi/fred-series-api-openapi.yml