Faceted classification across FRED — tag listings, related tags, and tag-matched series.
openapi: 3.0.3
info:
title: FRED Maps API (GeoFRED) Categories Tags 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: Tags
description: Faceted classification across FRED — tag listings, related tags, and tag-matched series.
paths:
/tags:
get:
operationId: getTags
summary: FRED Get FRED Tags
description: Get FRED tags. Optionally filtered by tag names, group_id, or search text.
tags:
- Tags
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/FileType'
- $ref: '#/components/parameters/RealtimeStart'
- $ref: '#/components/parameters/RealtimeEnd'
- $ref: '#/components/parameters/TagNames'
- $ref: '#/components/parameters/TagGroupId'
- $ref: '#/components/parameters/SearchText'
- $ref: '#/components/parameters/Limit1000'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/OrderByTags'
- $ref: '#/components/parameters/SortOrder'
responses:
'200':
description: List of tags.
content:
application/json:
schema:
$ref: '#/components/schemas/TagList'
examples:
Gettags200Example:
summary: Default getTags 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
/related_tags:
get:
operationId: getRelatedTags
summary: FRED Get the Related FRED Tags for One or More FRED Tags
description: Get the related FRED tags for one or more FRED tags. Related tags are tags assigned to series that also have all of the tag_names tags.
tags:
- Tags
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/FileType'
- $ref: '#/components/parameters/RealtimeStart'
- $ref: '#/components/parameters/RealtimeEnd'
- $ref: '#/components/parameters/TagNames'
- $ref: '#/components/parameters/ExcludeTagNames'
- $ref: '#/components/parameters/TagGroupId'
- $ref: '#/components/parameters/SearchText'
- $ref: '#/components/parameters/Limit1000'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/OrderByTags'
- $ref: '#/components/parameters/SortOrder'
responses:
'200':
description: Related tags.
content:
application/json:
schema:
$ref: '#/components/schemas/TagList'
examples:
Getrelatedtags200Example:
summary: Default getRelatedTags 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
/tags/series:
get:
operationId: getTagsSeries
summary: FRED Get the Series Matching All Tags
description: Get the series matching all of the supplied tags.
tags:
- Tags
parameters:
- $ref: '#/components/parameters/ApiKey'
- $ref: '#/components/parameters/FileType'
- $ref: '#/components/parameters/TagNames'
- $ref: '#/components/parameters/ExcludeTagNames'
- $ref: '#/components/parameters/RealtimeStart'
- $ref: '#/components/parameters/RealtimeEnd'
- $ref: '#/components/parameters/Limit1000'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/OrderBySeries'
- $ref: '#/components/parameters/SortOrder'
responses:
'200':
description: Series matching the tags.
content:
application/json:
schema:
$ref: '#/components/schemas/SeriesList'
examples:
Gettagsseries200Example:
summary: Default getTagsSeries 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
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'
ExcludeTagNames:
name: exclude_tag_names
in: query
required: false
description: Semicolon-separated list of tag names to exclude.
schema:
type: string
example: discontinued
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
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
SearchText:
name: search_text
in: query
required: false
description: Words to match against tag names and descriptions.
schema:
type: string
example: monetary aggregates
TagNames:
name: tag_names
in: query
required: false
description: Semicolon-separated list of tag names to require.
schema:
type: string
example: monthly;usa
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
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
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'
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
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
OrderBySeries:
name: order_by
in: query
required: false
description: Field to order series results by.
schema:
type: string
enum:
- series_id
- title
- units
- frequency
- seasonal_adjustment
- realtime_start
- realtime_end
- last_updated
- observation_start
- observation_end
- popularity
- group_popularity
example: series_count
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
schemas:
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
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
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
example: SA
last_updated:
type: string
description: ISO-8601 timestamp of last update.
example: '2026-05-02 07:46:10-05'
popularity:
type: integer
description: Popularity score 0–100.
example: 95
group_popularity:
type: integer
description: Group popularity score 0–100.
example: 95
notes:
type: string
description: Editorial notes for the series.
example: Editorial notes.
required:
- id
- title
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
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: api_key
description: 32-character lower-case alphanumeric FRED API key (same key used for the FRED API).