{"id":10218,"library":"sdmx1","title":"SDMX: Statistical Data and Metadata eXchange","description":"sdmx1 is a Python library for consuming and working with Statistical Data and Metadata eXchange (SDMX) web services and files. It supports various SDMX versions and data formats, allowing users to query, download, and parse statistical data from official sources like Eurostat, IMF, and OECD. The library is actively maintained with frequent minor releases, currently at version 2.26.0, and requires Python >=3.10.","status":"active","version":"2.26.0","language":"en","source_language":"en","source_url":"https://github.com/khaeru/sdmx","tags":["sdmx","statistics","data-exchange","eia","eurostat","imf","oecd","data-analysis"],"install":[{"cmd":"pip install sdmx1","lang":"bash","label":"Install core library"},{"cmd":"pip install sdmx1[cache]","lang":"bash","label":"Install with caching support"}],"dependencies":[{"reason":"For persistent caching of HTTP requests to improve performance and reduce API calls.","package":"requests-cache","optional":true}],"imports":[{"note":"The `sdmx.Client` class was removed in version 2.0.0 and replaced by `sdmx.Request` for clearer API interaction.","wrong":"from sdmx import Client","symbol":"Request","correct":"import sdmx\nreq = sdmx.Request('ESTAT')"},{"note":"Commonly used for parsing SDMX-ML or SDMX-JSON files from local storage.","symbol":"read_sdmx","correct":"import sdmx\nwith open('data.xml', 'rb') as f:\n    msg = sdmx.read_sdmx(f)"}],"quickstart":{"code":"import sdmx\nimport os\n\n# Example agency ID; replace with a real one like 'ESTAT' (Eurostat), 'IMF', 'OECD'\n# Some agencies may require specific authentication or have strict rate limits.\nagency_id = os.environ.get('SDMX_AGENCY_ID', 'IMF') # Using IMF as a common example\n\ntry:\n    # Create a Request object for the specified agency\n    req = sdmx.Request(agency_id)\n\n    print(f\"Attempting to connect to SDMX agency: {agency_id}\")\n\n    # Fetch available dataflows\n    # This performs an HTTP GET request to the agency's API endpoint\n    dataflows = req.dataflow()\n\n    print(f\"Successfully retrieved dataflows from {agency_id}.\")\n    print(f\"First 3 dataflows from {agency_id} (ID: Name):\")\n    if dataflows.data.dataflow:\n        for i, flow in enumerate(dataflows.data.dataflow[:3]):\n            print(f\"  - {flow.id}: {flow.name.get('en', 'No English name')}\")\n    else:\n        print(\"  No dataflows found.\")\n\n    # To fetch actual data, you would then use a specific dataflow ID and keys.\n    # Example (commented out, as specific dataflow IDs and keys vary greatly):\n    # # For IMF, using International Financial Statistics (IFS) dataflow, if available\n    # if agency_id == 'IMF':\n    #     print(\"\\nAttempting to fetch data from IMF (example).\")\n    #     data = req.get_data(\n    #         resource_id='IFS',\n    #         key={'REF_AREA': ['US', 'CN'], 'INDICATOR': ['LP_CPI_IX']},\n    #         params={'startPeriod': '2020', 'endPeriod': '2022'}\n    #     )\n    #     print(f\"Fetched {len(data.series)} series from IFS.\")\n\nexcept sdmx.api.APIError as e:\n    print(f\"Error connecting to or fetching data from {agency_id}: {e}\")\n    print(\"Possible causes: invalid agency ID, network issues, API rate limits, or specific API endpoint errors.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Replace all instances of `sdmx.Client()` with `sdmx.Request()`. Review documentation for new constructor arguments.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Update your code to use `sdmx.Request()` instead of `sdmx.Client()`. For example, `req = sdmx.Request('ESTAT')`.","cause":"You are attempting to use the `sdmx.Client` class, which was removed in `sdmx1` version 2.0.0.","error":"AttributeError: module 'sdmx' has no attribute 'Client'"},{"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.","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.","error":"sdmx.api.APIError: 404 Client Error: Not Found for url: ..."},{"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.","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.","error":"sdmx.api.APIError: 400 Client Error: Bad Request for url: ..."}]}