openapi: 3.0.3
info:
  title: FRED Maps API (GeoFRED) Categories 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: Categories
  description: Category hierarchy navigation — children, related, series, and tags within a category.
paths:
  /category:
    get:
      operationId: getCategory
      summary: FRED Get a Category
      description: Get a category by ID.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/FileType'
      - name: category_id
        in: query
        required: true
        description: Numeric ID of the FRED category to retrieve.
        schema:
          type: integer
          default: 0
        example: 125
      responses:
        '200':
          description: A single category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryList'
              examples:
                Getcategory200Example:
                  summary: Default getCategory 200 response
                  x-microcks-default: true
                  value:
                    categories:
                    - id: 125
                      name: Trade Balance
                      parent_id: 13
                    - id: 13
                      name: International Data
                      parent_id: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /category/children:
    get:
      operationId: getCategoryChildren
      summary: FRED Get the Child Categories for a Category
      description: Get the child categories for a specified parent category.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/FileType'
      - name: category_id
        in: query
        required: true
        description: Parent category ID.
        schema:
          type: integer
          default: 0
        example: 125
      - $ref: '#/components/parameters/RealtimeStart'
      - $ref: '#/components/parameters/RealtimeEnd'
      responses:
        '200':
          description: List of child categories.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryList'
              examples:
                Getcategorychildren200Example:
                  summary: Default getCategoryChildren 200 response
                  x-microcks-default: true
                  value:
                    categories:
                    - id: 125
                      name: Trade Balance
                      parent_id: 13
                    - id: 13
                      name: International Data
                      parent_id: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /category/related:
    get:
      operationId: getCategoryRelated
      summary: FRED Get the Related Categories for a Category
      description: Get the related categories for a category. Two categories are related when one is not the parent or child of the other but the FRED editorial staff have judged them as related.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/FileType'
      - name: category_id
        in: query
        required: true
        description: The seed category ID.
        schema:
          type: integer
        example: 125
      - $ref: '#/components/parameters/RealtimeStart'
      - $ref: '#/components/parameters/RealtimeEnd'
      responses:
        '200':
          description: List of related categories.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryList'
              examples:
                Getcategoryrelated200Example:
                  summary: Default getCategoryRelated 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
  /category/series:
    get:
      operationId: getCategorySeries
      summary: FRED Get the Series in a Category
      description: Get the series in a category.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/FileType'
      - name: category_id
        in: query
        required: true
        description: The category to enumerate.
        schema:
          type: integer
        example: 125
      - $ref: '#/components/parameters/RealtimeStart'
      - $ref: '#/components/parameters/RealtimeEnd'
      - $ref: '#/components/parameters/Limit1000'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/OrderBySeries'
      - $ref: '#/components/parameters/SortOrder'
      - $ref: '#/components/parameters/FilterVariable'
      - $ref: '#/components/parameters/FilterValue'
      - $ref: '#/components/parameters/TagNames'
      - $ref: '#/components/parameters/ExcludeTagNames'
      responses:
        '200':
          description: Series in the category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeriesList'
              examples:
                Getcategoryseries200Example:
                  summary: Default getCategorySeries 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
  /category/tags:
    get:
      operationId: getCategoryTags
      summary: FRED Get the Tags for a Category
      description: Get the FRED tags for a category.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/FileType'
      - name: category_id
        in: query
        required: true
        description: The category to list tags for.
        schema:
          type: integer
        example: 125
      - $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: Tags for the category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagList'
              examples:
                Getcategorytags200Example:
                  summary: Default getCategoryTags 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
  /category/related_tags:
    get:
      operationId: getCategoryRelatedTags
      summary: FRED Get the Related Tags for a Category
      description: Get the related FRED tags for one or more FRED tags within a category.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/FileType'
      - name: category_id
        in: query
        required: true
        schema:
          type: integer
        description: Seed category.
        example: 125
      - $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 for the category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagList'
              examples:
                Getcategoryrelatedtags200Example:
                  summary: Default getCategoryRelatedTags 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
components:
  responses:
    Forbidden:
      description: Forbidden — API key missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad Request — required parameter missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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
    SearchText:
      name: search_text
      in: query
      required: false
      description: Words to match against tag names and descriptions.
      schema:
        type: string
      example: monetary aggregates
    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'
    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
    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:
    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
    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
    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
    ErrorResponse:
      type: object
      description: FRED error response.
      properties:
        error_code:
          type: integer
          description: Numeric error code returned by FRED.
          example: 400
        error_message:
          type: string
          description: Human-readable error message.
          example: example
      required:
      - error_code
      - error_message
    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
  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).