IMF Data Structure API

openapi: 3.0.3
info:
  title: IMF SDMX 3.0 Data Structure 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: Structure
  description: Retrieve dataset metadata including dataflows, data structures, codelists, and concept schemes
paths:
  /structure/dataflow/all/*/+:
    get:
      summary: List all available IMF dataflows (datasets)
      description: 'Returns all available dataflow definitions from the IMF SDMX API.

        Each dataflow represents a dataset such as IFS, WEO, FM, GFS, MFS, etc.

        Use the dataflow ID to query data and retrieve data structures.

        '
      operationId: listDataflows
      tags:
      - Structure
      parameters:
      - name: Accept
        in: header
        description: Response format
        schema:
          type: string
          default: application/json
      responses:
        '200':
          description: List of available dataflows
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      dataflows:
                        type: array
                        items:
                          $ref: '#/components/schemas/Dataflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /structure/datastructure/{agency}/{dsd_id}/+:
    get:
      summary: Retrieve data structure definition (DSD) for a dataflow
      description: 'Returns the data structure definition for a specific dataset, including

        all dimensions, measures, attributes, and their positions.

        Use this to understand how to build query keys for data requests.

        '
      operationId: getDataStructure
      tags:
      - Structure
      parameters:
      - name: agency
        in: path
        required: true
        description: The agency that owns the data structure (e.g., IMF.STA, IMF)
        schema:
          type: string
          example: IMF.STA
      - name: dsd_id
        in: path
        required: true
        description: The data structure definition identifier
        schema:
          type: string
          example: DSD_GFS
      responses:
        '200':
          description: Data structure definition
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      dataStructures:
                        type: array
                        items:
                          $ref: '#/components/schemas/DataStructure'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /structure/codelist/{agency}/{codelist_id}/+:
    get:
      summary: Retrieve a codelist for a dimension
      description: 'Returns all valid codes and their labels for a specified codelist.

        Codelists are used to identify valid values for dimensions such as

        COUNTRY (country codes), FREQUENCY (A=Annual, Q=Quarterly, M=Monthly),

        and indicator codes specific to each dataset.

        '
      operationId: getCodelist
      tags:
      - Structure
      parameters:
      - name: agency
        in: path
        required: true
        description: The agency that owns the codelist
        schema:
          type: string
          example: IMF.STA
      - name: codelist_id
        in: path
        required: true
        description: The codelist identifier (e.g., CL_COUNTRY, CL_FREQ)
        schema:
          type: string
          example: CL_COUNTRY
      responses:
        '200':
          description: Codelist with codes and labels
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      codelists:
                        type: array
                        items:
                          $ref: '#/components/schemas/Codelist'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /structure/conceptscheme/{agency}/{scheme_id}/+:
    get:
      summary: Retrieve a concept scheme
      description: 'Returns concept definitions used to describe the meaning of dimensions

        and attributes in IMF datasets.

        '
      operationId: getConceptScheme
      tags:
      - Structure
      parameters:
      - name: agency
        in: path
        required: true
        description: The agency that owns the concept scheme
        schema:
          type: string
          example: IMF
      - name: scheme_id
        in: path
        required: true
        description: The concept scheme identifier
        schema:
          type: string
          example: CS_IFS
      responses:
        '200':
          description: Concept scheme with concept definitions
          content:
            application/json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Dimension:
      type: object
      description: A dimension in an IMF dataset structure
      properties:
        id:
          type: string
          description: Dimension identifier (e.g., COUNTRY, FREQUENCY, TIME_PERIOD)
          example: COUNTRY
        position:
          type: integer
          description: Position in the dot-separated key string
          example: 2
        type:
          type: string
          description: Dimension type
          enum:
          - Dimension
          - TimeDimension
          - Measure
        conceptIdentity:
          type: string
          description: URN reference to the concept definition
    Dataflow:
      type: object
      description: An IMF dataset definition
      properties:
        id:
          type: string
          description: Unique dataflow identifier (e.g., IFS, GFS, FM)
          example: FM
        name:
          type: string
          description: Human-readable dataset name
          example: Fiscal Monitor
        description:
          type: string
          description: Detailed dataset description
        version:
          type: string
          description: Dataflow version
          example: 8.0.1
        agencyID:
          type: string
          description: Owning agency identifier
          example: IMF.STA
        structure:
          type: string
          description: URN reference to the associated data structure definition
    DataStructure:
      type: object
      description: Data structure definition for an IMF dataset
      properties:
        id:
          type: string
          description: Data structure identifier
        agencyID:
          type: string
          description: Owning agency
        dataStructureComponents:
          type: object
          properties:
            dimensionList:
              type: object
              properties:
                dimensions:
                  type: array
                  items:
                    $ref: '#/components/schemas/Dimension'
                timeDimensions:
                  type: array
                  items:
                    $ref: '#/components/schemas/Dimension'
            measureList:
              type: object
              properties:
                measures:
                  type: array
                  items:
                    $ref: '#/components/schemas/Dimension'
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer
        correlationId:
          type: string
        path:
          type: string
    Codelist:
      type: object
      description: A list of valid codes for a dimension
      properties:
        id:
          type: string
          description: Codelist identifier
          example: CL_COUNTRY
        agencyID:
          type: string
        codes:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Code value
                example: USA
              name:
                type: string
                description: Human-readable code label
                example: United States
  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'
externalDocs:
  description: IMF Data Help - Using JSON RESTful Web Service
  url: https://datahelp.imf.org/knowledgebase/articles/667294-using-json-restful-web-service