openapi: 3.0.3
info:
  title: FRED Maps API (GeoFRED) Categories Sources 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: Sources
  description: Originating institutions for FRED series (BLS, BEA, OECD, etc.) and the releases they publish.
paths:
  /sources:
    get:
      operationId: getSources
      summary: FRED Get All Sources of Economic Data
      description: Get all sources of economic data.
      tags:
      - Sources
      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: order_by
        in: query
        schema:
          type: string
          enum:
          - source_id
          - name
          - realtime_start
          - realtime_end
          default: source_id
        description: Ordering field.
        example: series_count
      - $ref: '#/components/parameters/SortOrder'
      responses:
        '200':
          description: All sources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceList'
              examples:
                Getsources200Example:
                  summary: Default getSources 200 response
                  x-microcks-default: true
                  value:
                    realtime_start: '2026-05-28'
                    realtime_end: '2026-05-28'
                    order_by: source_id
                    sort_order: asc
                    count: 1
                    offset: 0
                    limit: 1000
                    sources:
                    - id: 1
                      realtime_start: '2026-05-28'
                      realtime_end: '2026-05-28'
                      name: Board of Governors of the Federal Reserve System (US)
                      link: http://www.federalreserve.gov/
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /source:
    get:
      operationId: getSource
      summary: FRED Get a Source of Economic Data
      description: Get a source of economic data by ID.
      tags:
      - Sources
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/FileType'
      - name: source_id
        in: query
        required: true
        schema:
          type: integer
        description: Numeric source ID.
        example: 1
      - $ref: '#/components/parameters/RealtimeStart'
      - $ref: '#/components/parameters/RealtimeEnd'
      responses:
        '200':
          description: A single source.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceList'
              examples:
                Getsource200Example:
                  summary: Default getSource 200 response
                  x-microcks-default: true
                  value:
                    realtime_start: '2026-05-28'
                    realtime_end: '2026-05-28'
                    order_by: source_id
                    sort_order: asc
                    count: 1
                    offset: 0
                    limit: 1000
                    sources:
                    - id: 1
                      realtime_start: '2026-05-28'
                      realtime_end: '2026-05-28'
                      name: Board of Governors of the Federal Reserve System (US)
                      link: http://www.federalreserve.gov/
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /source/releases:
    get:
      operationId: getSourceReleases
      summary: FRED Get the Releases for a Source
      description: Get the releases for a source.
      tags:
      - Sources
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/FileType'
      - name: source_id
        in: query
        required: true
        schema:
          type: integer
        description: Numeric source ID.
        example: 1
      - $ref: '#/components/parameters/RealtimeStart'
      - $ref: '#/components/parameters/RealtimeEnd'
      - $ref: '#/components/parameters/Limit1000'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/OrderByReleases'
      - $ref: '#/components/parameters/SortOrder'
      responses:
        '200':
          description: Releases for the source.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseList'
              examples:
                Getsourcereleases200Example:
                  summary: Default getSourceReleases 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
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
    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
    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
    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
    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'
    OrderByReleases:
      name: order_by
      in: query
      required: false
      description: Field to order release results by.
      schema:
        type: string
        enum:
        - release_id
        - name
        - press_release
        - realtime_start
        - realtime_end
      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:
    Source:
      type: object
      description: An originating source of FRED economic data.
      properties:
        id:
          type: integer
          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
          example: Unemployment Rate
        link:
          type: string
          format: uri
          example: https://fred.stlouisfed.org/
        notes:
          type: string
          example: Editorial notes.
      required:
      - id
      - name
    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
    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
    SourceList:
      type: object
      description: A list of FRED sources.
      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
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
      required:
      - sources
  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).