IMF Data API

openapi: 3.2.0
info:
  title: IMF SDMX 3.0 Data API
  description: 'The International Monetary Fund (IMF) SDMX 3.0 Data API provides programmatic access

    to hundreds of IMF statistical datasets.'
  version: '3.0'
  contact:
    name: IMF Data Help
    url: https://datahelp.imf.org
    email: sdmx@imf.org
  license:
    name: IMF Data License
    url: https://www.imf.org/external/terms.htm
  termsOfService: https://www.imf.org/external/terms.htm
servers:
- url: https://api.imf.org/external/sdmx/3.0
  description: IMF SDMX 3.0 API (current)
- url: http://dataservices.imf.org/REST/SDMX_JSON.svc
  description: IMF SDMX JSON 2.1 API (legacy)
tags:
- name: Data
  description: Retrieve actual statistical data observations from IMF datasets
paths:
  /data/dataflow/{agency}/{dataflow_id}/+/{key}:
    get:
      summary: Retrieve data observations from an IMF dataset
      description: 'Returns time-series data observations for the specified dataflow filtered

        by the dimension key. The key is a dot-separated string where each position

        corresponds to a dimension in the dataset''s data structure definition (DSD),

        in positional order. Use ''+'' to specify multiple values for a dimension and

        ''*'' or blank to wildcard a dimension.


        Examples:

        - `A.USA.PCPI` - Annual, USA, Consumer Price Index

        - `A+Q.USA+GBR.*` - Annual and Quarterly, USA and UK, all indicators

        - `*.*.NGDP_RPCH` - All frequencies and countries, Real GDP Growth


        Time filtering is supported via query parameters for IMF.STA datasets.'
      operationId: getData
      tags:
      - Data
      parameters:
      - name: agency
        in: path
        required: true
        description: The agency owning the dataflow (e.g., IMF.STA, all)
        schema:
          type: string
          example: IMF.STA
      - name: dataflow_id
        in: path
        required: true
        description: The dataflow identifier (e.g., IFS, GFS, FM, WEO, MFS, BOP)
        schema:
          type: string
          example: IFS
      - name: key
        in: path
        required: true
        description: Dot-separated dimension key with + for multiple values and * for wildcard
        schema:
          type: string
          example: A.USA.PCPI
      - name: dimensionAtObservation
        in: query
        description: Specify which dimension varies at the observation level
        schema:
          type: string
          default: TIME_PERIOD
          example: TIME_PERIOD
      - name: attributes
        in: query
        description: Level of attribute detail to include in response
        schema:
          type: string
          default: dsd
          enum:
          - none
          - obs
          - series
          - dataset
          - dsd
          - all
      - name: measures
        in: query
        description: Which measures to return
        schema:
          type: string
          default: all
      - name: c[TIME_PERIOD]
        in: query
        description: 'Time period filter using SDMX comparison operators.

          Format: ge:YYYY-{freq}N+le:YYYY-{freq}N

          Examples: ge:2010-A1+le:2020-A1 (annual), ge:2010-Q1+le:2020-Q4 (quarterly)

          '
        schema:
          type: string
          example: ge:2010-A1+le:2023-A1
      responses:
        '200':
          description: SDMX JSON data message with observations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataMessage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer
        correlationId:
          type: string
        path:
          type: string
    DataMessage:
      type: object
      description: SDMX 3.0 JSON data message containing observations
      properties:
        data:
          type: object
          properties:
            dataSets:
              type: array
              items:
                type: object
                description: Dataset with series and observations
            structures:
              type: array
              items:
                type: object
                description: Structure references for interpreting the data
        meta:
          type: object
          description: Metadata about the response including schema and preparation timestamp
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded (50 requests/second per application)
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
externalDocs:
  description: IMF Data Help - Using JSON RESTful Web Service
  url: https://datahelp.imf.org/knowledgebase/articles/667294-using-json-restful-web-service