openapi: 3.0.3
info:
  title: FRED Maps API (GeoFRED) Categories Observations 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: Observations
  description: The underlying time-series data values, with frequency aggregation and unit transformations.
paths:
  /series/observations:
    get:
      operationId: getSeriesObservations
      summary: FRED Get the Observations or Data Values for an Economic Data Series
      description: Get the observations or data values for an economic data series. Supports frequency aggregation and unit transformations.
      tags:
      - Observations
      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/Limit100000'
      - $ref: '#/components/parameters/Offset'
      - name: sort_order
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: Sort by observation_date.
        example: asc
      - name: observation_start
        in: query
        schema:
          type: string
          format: date
          default: '1776-07-04'
        description: Earliest observation date (YYYY-MM-DD).
        example: '2020-01-01'
      - name: observation_end
        in: query
        schema:
          type: string
          format: date
          default: '9999-12-31'
        description: Latest observation date (YYYY-MM-DD).
        example: '2026-04-01'
      - name: units
        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: frequency
        in: query
        schema:
          type: string
          enum:
          - d
          - w
          - bw
          - m
          - q
          - sa
          - a
          - wef
          - weth
          - wew
          - wetu
          - wem
          - wesu
          - wesa
          - bwew
          - bwem
        description: Frequency to aggregate the series to.
        example: m
      - name: aggregation_method
        in: query
        schema:
          type: string
          enum:
          - avg
          - sum
          - eop
          default: avg
        description: How to aggregate when a frequency is supplied.
        example: avg
      - name: output_type
        in: query
        schema:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          default: 1
        description: Observations output type. 1=observations by real-time period
        2=observations by vintage date: null
        3=observations by vintage date with all data: null
        4=observations by initial release only.: null
        example: 1
      - name: vintage_dates
        in: query
        schema:
          type: string
        description: Comma-separated list of YYYY-MM-DD vintage dates.
        example: 2024-01-15,2025-01-15
      responses:
        '200':
          description: Observations for the series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationList'
              examples:
                Getseriesobservations200Example:
                  summary: Default getSeriesObservations 200 response
                  x-microcks-default: true
                  value:
                    realtime_start: '2026-05-28'
                    realtime_end: '2026-05-28'
                    observation_start: '2025-01-01'
                    observation_end: '2026-04-01'
                    units: lin
                    output_type: 1
                    file_type: json
                    order_by: observation_date
                    sort_order: asc
                    count: 4
                    offset: 0
                    limit: 100000
                    observations:
                    - realtime_start: '2026-05-28'
                      realtime_end: '2026-05-28'
                      date: '2026-01-01'
                      value: '4.0'
                    - realtime_start: '2026-05-28'
                      realtime_end: '2026-05-28'
                      date: '2026-02-01'
                      value: '4.1'
                    - realtime_start: '2026-05-28'
                      realtime_end: '2026-05-28'
                      date: '2026-03-01'
                      value: '3.9'
                    - realtime_start: '2026-05-28'
                      realtime_end: '2026-05-28'
                      date: '2026-04-01'
                      value: '4.0'
      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
    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'
    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
    Limit100000:
      name: limit
      in: query
      required: false
      description: Maximum number of observations to return (1–100000).
      schema:
        type: integer
        minimum: 1
        maximum: 100000
        default: 100000
      example: 100
  schemas:
    Observation:
      type: object
      description: A single time-series observation.
      properties:
        realtime_start:
          type: string
          format: date
          example: '2026-05-28'
        realtime_end:
          type: string
          format: date
          example: '2026-05-28'
        date:
          type: string
          format: date
          description: Observation date.
          example: '2026-05-28'
        value:
          type: string
          description: Observation value (string to preserve "." for missing values).
          example: '4.0'
      required:
      - date
      - value
    ObservationList:
      type: object
      description: A list of observations for a series.
      properties:
        realtime_start:
          type: string
          format: date
          example: '2026-05-28'
        realtime_end:
          type: string
          format: date
          example: '2026-05-28'
        observation_start:
          type: string
          format: date
          example: '2026-05-28'
        observation_end:
          type: string
          format: date
          example: '2026-05-28'
        units:
          type: string
          example: Percent
        output_type:
          type: integer
          example: 1
        file_type:
          type: string
          example: example
        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
        observations:
          type: array
          items:
            $ref: '#/components/schemas/Observation'
      required:
      - observations
  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).