SDMX: Statistical Data and Metadata eXchange

Common errors

• AttributeError: module 'sdmx' has no attribute 'Client'

  cause You are attempting to use the `sdmx.Client` class, which was removed in `sdmx1` version 2.0.0.
  fix Update your code to use `sdmx.Request()` instead of `sdmx.Client()`. For example, `req = sdmx.Request('ESTAT')`.

• sdmx.api.APIError: 404 Client Error: Not Found for url: ...

  cause The SDMX agency or resource ID specified in your request does not exist, or the URL constructed by the library leads to a non-existent endpoint. This often happens with incorrect agency IDs or resource IDs.
  fix Double-check the `agency_id` and `resource_id` (e.g., dataflow ID) you are passing to `sdmx.Request()` and `req.get_data()`. Verify them against the official SDMX documentation or the agency's portal.

• sdmx.api.APIError: 400 Client Error: Bad Request for url: ...

  cause The parameters sent in your data request are invalid, incomplete, or not understood by the SDMX API. Common issues include incorrect dimension keys, missing required parameters like `startPeriod`/`endPeriod`, or invalid date formats.
  fix Review the `key` and `params` arguments passed to `req.get_data()`. Ensure all required dimensions are specified and their values are valid according to the agency's data structure definitions. Consult the agency's SDMX API documentation.

Warnings

• breaking The `sdmx.Client` class was removed and replaced by `sdmx.Request` in version 2.0.0. This significantly changed how connections to SDMX agencies are initiated.
  Fix: Replace all instances of `sdmx.Client()` with `sdmx.Request()`. Review documentation for new constructor arguments.
• breaking Many parameter names for data queries and metadata requests changed in version 2.0.0 (e.g., `agency_id` often became `agency`), and the structure of returned objects (e.g., `Message`, `DataSet`, `Series`, `Obs`) was refined.
  Fix: Consult the 'What's New' section for v2.0.0 and the current API documentation to update parameter names and response object traversal logic.
• gotcha SDMX data is highly structured and often nested. New users may find it challenging to navigate the `Message` object to extract `DataSet`, `Series`, and `Obs` objects.
  Fix: Familiarize yourself with the SDMX information model. Use `message.data` to access data sets, `message.dataflow` for dataflow definitions, and iterate through `series` and `obs` attributes to get data points.
• gotcha Many SDMX web services (APIs) have strict rate limits, size limits for requests, or require specific query parameters (e.g., `startPeriod`, `endPeriod`, `dimensionAtObservation`) to fetch data successfully.
  Fix: Implement caching (e.g., using `requests-cache` via `pip install sdmx1[cache]`), make smaller, targeted requests, and always consult the specific agency's API documentation for allowed parameters and limits. Handle `sdmx.api.APIError` for HTTP status codes like 400, 403, 429.

Install

• pip install sdmx1 Install core library
• pip install sdmx1[cache] Install with caching support

Imports

• Request
  wrong:

  from sdmx import Client

  correct:

  import sdmx
  req = sdmx.Request('ESTAT')

  The `sdmx.Client` class was removed in version 2.0.0 and replaced by `sdmx.Request` for clearer API interaction.
• read_sdmx

  import sdmx
  with open('data.xml', 'rb') as f:
      msg = sdmx.read_sdmx(f)

  Commonly used for parsing SDMX-ML or SDMX-JSON files from local storage.

Quickstart

Demonstrates how to connect to an SDMX agency (e.g., IMF) using `sdmx.Request`, list available dataflows, and print basic information. It includes error handling for common API issues. The example for fetching specific data is commented out as it requires specific knowledge of an agency's data structure.

import sdmx
import os

# Example agency ID; replace with a real one like 'ESTAT' (Eurostat), 'IMF', 'OECD'
# Some agencies may require specific authentication or have strict rate limits.
agency_id = os.environ.get('SDMX_AGENCY_ID', 'IMF') # Using IMF as a common example

try:
    # Create a Request object for the specified agency
    req = sdmx.Request(agency_id)

    print(f"Attempting to connect to SDMX agency: {agency_id}")

    # Fetch available dataflows
    # This performs an HTTP GET request to the agency's API endpoint
    dataflows = req.dataflow()

    print(f"Successfully retrieved dataflows from {agency_id}.")
    print(f"First 3 dataflows from {agency_id} (ID: Name):")
    if dataflows.data.dataflow:
        for i, flow in enumerate(dataflows.data.dataflow[:3]):
            print(f"  - {flow.id}: {flow.name.get('en', 'No English name')}")
    else:
        print("  No dataflows found.")

    # To fetch actual data, you would then use a specific dataflow ID and keys.
    # Example (commented out, as specific dataflow IDs and keys vary greatly):
    # # For IMF, using International Financial Statistics (IFS) dataflow, if available
    # if agency_id == 'IMF':
    #     print("\nAttempting to fetch data from IMF (example).")
    #     data = req.get_data(
    #         resource_id='IFS',
    #         key={'REF_AREA': ['US', 'CN'], 'INDICATOR': ['LP_CPI_IX']},
    #         params={'startPeriod': '2020', 'endPeriod': '2022'}
    #     )
    #     print(f"Fetched {len(data.series)} series from IFS.")

except sdmx.api.APIError as e:
    print(f"Error connecting to or fetching data from {agency_id}: {e}")
    print("Possible causes: invalid agency ID, network issues, API rate limits, or specific API endpoint errors.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")