openapi: 3.0.3 info: title: FRED Maps API (GeoFRED) 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 tags: - name: Shapes description: GeoJSON shape files for state, county, MSA, country, and census-tract geographies. - name: Series Group description: Series-group metadata — the regional identifier and supported region types for a series. - name: Series Data description: Regional data values attached to a specific FRED series. - name: Regional Data description: Regional data values for a series group across a geography. security: - ApiKeyAuth: [] paths: /shapes/file: get: operationId: getShapeFile summary: FRED Get GeoJSON Shape Files for a Geographic Type description: Get GeoJSON shape file data for a given geographic type (state, county, msa, country, etc.). Returns coordinates as quantized integers (not WGS84 lat/lon). tags: [Shapes] parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/FileType' - name: shape in: query required: true description: Geographic type — bea, msa, frb, necta, state, country, county, censusregion, censusdivision. schema: type: string enum: [bea, msa, frb, necta, state, country, county, censusregion, censusdivision] example: state responses: '200': description: GeoJSON shape collection. content: application/json: schema: {$ref: '#/components/schemas/ShapeCollection'} examples: Getshapefile200Example: summary: Default getShapeFile 200 response x-microcks-default: true value: shape: state features: - name: California code: '06' centroid: -1219000000,3700000000 geometry: '...' - name: Missouri code: '29' centroid: -922000000,3837000000 geometry: '...' x-microcks-operation: {delay: 0, dispatcher: FALLBACK} /series/group: get: operationId: getSeriesGroup summary: FRED Get the Series Group for a Series description: Get the series group information for a regional data series. The series group identifier groups a collection of series matched along geography, units, frequency, and seasonal adjustment. tags: [Series Group] parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/FileType' - name: series_id in: query required: true description: The FRED series ID. schema: {type: string} example: UNRATE responses: '200': description: Series group metadata. content: application/json: schema: {$ref: '#/components/schemas/SeriesGroup'} examples: Getseriesgroup200Example: summary: Default getSeriesGroup 200 response x-microcks-default: true value: title: 'All Employees: Total Nonfarm' region_type: state series_group: '1223' season: SA units: Thousands of Persons frequency: Monthly min_date: '1990-01-01' max_date: '2026-04-01' x-microcks-operation: {delay: 0, dispatcher: FALLBACK} /series/data: get: operationId: getSeriesData summary: FRED Get Regional Data Values for a Series description: Get regional data values attached to a specific FRED series. tags: [Series Data] 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} - {name: date, in: query, schema: {type: string, format: date}, description: Date for the data values (YYYY-MM-DD). Defaults to the most recent., example: '2026-04-01'} - {name: start_date, in: query, schema: {type: string, format: date}, description: Optional start date for a range query., example: '2026-01-01'} responses: '200': description: Regional data values for the series. content: application/json: schema: {$ref: '#/components/schemas/RegionalDataResult'} examples: Getseriesdata200Example: summary: Default getSeriesData 200 response x-microcks-default: true value: meta: title: 'All Employees: Total Nonfarm' region: state seasonality: Seasonally Adjusted units: Thousands of Persons frequency: Monthly data: '2026-04-01': - region: California code: '06' value: 17920.5 series_id: CANA - region: Missouri code: '29' value: 2960.1 series_id: MONA x-microcks-operation: {delay: 0, dispatcher: FALLBACK} /regional/data: get: operationId: getRegionalData summary: FRED Get Regional Data by Series Group description: Get regional data values across a geography for a series group. tags: [Regional Data] parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/FileType' - {name: series_group, in: query, required: true, schema: {type: string}, description: ID for a group of series found in FRED., example: '1223'} - {name: region_type, in: query, required: true, schema: {type: string, enum: [bea, msa, frb, necta, state, country, county, censusregion, censusdivision]}, description: Geography to pull data for., example: state} - {name: date, in: query, required: true, schema: {type: string, format: date}, description: Date you want data from (YYYY-MM-DD)., example: '2026-04-01'} - {name: start_date, in: query, schema: {type: string, format: date}, description: Optional start date for a range query., example: '2026-01-01'} - {name: season, in: query, required: true, schema: {type: string, enum: [SA, NSA, SSA, SAAR, NSAAR]}, description: Seasonal-adjustment treatment., example: SA} - {name: units, in: query, required: true, schema: {type: string}, description: Units of the series you want to pull (e.g. Dollars, Percent).: null, example: lin} - {name: frequency, in: query, required: true, schema: {type: string, enum: [d, w, bw, m, q, sa, a]}, description: Data frequency code., example: m} - {name: transformation, in: query, schema: {type: string, enum: [lin, chg, ch1, pch, pc1, pca, cch, cca, log], default: lin}, description: Unit transformation applied to the data., example: lin} - {name: aggregation_method, in: query, schema: {type: string, enum: [avg, sum, eop], default: avg}, description: Method used to aggregate values when frequency is supplied., example: avg} responses: '200': description: Regional data values for the series group. content: application/json: schema: {$ref: '#/components/schemas/RegionalDataResult'} examples: Getregionaldata200Example: summary: Default getRegionalData 200 response x-microcks-default: true value: meta: title: 'All Employees: Total Nonfarm' region: state seasonality: Seasonally Adjusted units: Thousands of Persons frequency: Monthly data: '2026-04-01': - region: California code: '06' value: 17920.5 series_id: CANA - region: Missouri code: '29' value: 2960.1 series_id: MONA x-microcks-operation: {delay: 0, dispatcher: FALLBACK} components: 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). parameters: 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 FileType: name: file_type in: query required: false description: Response format — json or xml. schema: type: string enum: [json, xml] default: json example: json schemas: Shape: type: object description: A single GeoJSON-style shape feature. properties: name: {type: string, description: Display name of the region., example: Unemployment Rate} code: {type: string, description: Region code (FIPS, ISO: null, etc.).: null, example: example} centroid: {type: string, description: Quantized centroid coordinates., example: example} geometry: {type: string, description: Quantized geometry path., example: example} required: [name, code] ShapeCollection: type: object description: A collection of shapes for a geographic type. properties: shape: type: string description: The geographic type that was requested. example: example features: type: array items: {$ref: '#/components/schemas/Shape'} required: [features] SeriesGroup: type: object description: Metadata describing a regional series group. properties: title: {type: string, description: Display title of the series group., example: Unemployment Rate} region_type: {type: string, description: Geography type the group covers., example: example} series_group: {type: string, description: Series-group identifier., example: example} season: {type: string, enum: [SA, NSA, SSA, SAAR, NSAAR], example: example} units: {type: string, example: Percent} frequency: {type: string, example: Monthly} min_date: {type: string, format: date, example: '2026-05-28'} max_date: {type: string, format: date, example: '2026-05-28'} required: [series_group, region_type] RegionalDatum: type: object description: A single regional data value. properties: region: {type: string, description: Region display name., example: example} code: {type: string, description: Region code (FIPS, ISO: null, etc.).: null, example: example} value: {type: number, description: Indicator value., example: 4.0} series_id: {type: string, description: Underlying FRED series ID., example: UNRATE} required: [region, value] RegionalDataResult: type: object description: A regional-data result wrapped by date. properties: meta: type: object properties: title: {type: string} region: {type: string} seasonality: {type: string} units: {type: string} frequency: {type: string} data: type: object additionalProperties: type: array items: {$ref: '#/components/schemas/RegionalDatum'} description: Date-keyed map of regional values. required: [meta]