openapi: 3.0.3
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. Data is freely available with no authentication

    required. Datasets include International Financial Statistics (IFS), World Economic

    Outlook (WEO), Fiscal Monitor (FM), Government Finance Statistics (GFS), Monetary and

    Financial Statistics (MFS), Balance of Payments (BOP), and many more.


    The API follows the SDMX 3.0 (Statistical Data and Metadata eXchange) standard.

    Responses are available in JSON format.


    Rate limit: 50 requests per second (application-based via User-Agent header).

    '
  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:
  responses:
    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'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer
        correlationId:
          type: string
        path:
          type: string
externalDocs:
  description: IMF Data Help - Using JSON RESTful Web Service
  url: https://datahelp.imf.org/knowledgebase/articles/667294-using-json-restful-web-service