Unit 4: Structure Queries

In SDMX API v2, structure queries allow developers to retrieve metadata that defines how data is organised and classified. These structures include Data Structure Definitions (DSDs), code lists, concept schemes, dataflows, categorisations, and content constraints. Understanding and using structure queries is essential for interpreting data correctly and building dynamic, metadata-driven applications.

Structure queries use RESTful endpoints and can be filtered by identifiers, agency IDs, and version numbers. For example, you can query a specific DSD, retrieve a list of all dataflows, or retrieve all code lists used in a dataflow. The API supports responses in multiple formats, including SDMX-ML and JSON, making it adaptable to different technical environments.

Options like references=children, references=parents, or references=all allow you to control the scope of related metadata included in the response—useful for fetching a DSD, along with its associated code lists and concepts in a single call. Query parameters like detail=full or detail=referencepartial help adjust the level of detail returned.

These structure queries are critical for building flexible data integration tools, validating data, or creating user interfaces that dynamically adapt to available dimensions and indicators. Overall, SDMX API v2 provides a powerful and standardised way to programmatically explore and consume statistical metadata.

In this unit, we'll take a closer look at structure queries, providing realistic examples. Then we'll explain how the Fusion Metadata Registry (FMR) supports these queries. Finally, we'll introduce you to two programming languages that allow you to retrieve structural metadata and automate.

Structure queries: what SDMX API allows

When it comes to structure queries, the SDMX API allows the following:

Select each item below to discover more.

Structure query parameters defined

Let's look at a few examples of structure queries. The image below illustrates the components of the structure query URL, emphasising how to identify the resource to be returned.

Select the image to enlarge.

The image below shows the parts of the structure query URL that allow you to filter or provide additional information about the results.

Select the image to enlarge.

Fusion Metadata Registry API

FMR is primarily concerned with structural metadata and therefore supports structure queries but does not support data queries. The FMR implements a subset of the SDMX RESTful API specification, as illustrated here.

Select the table to enlarge.

The FMR API provides additional functions that are necessary for a practical registry implementation, but not explicitly provided for in SDMX standard REST specification.

The table below provides more details regarding FMR API function and purpose.

Select the table to enlarge.

Please see the References section at the end of this module for more information.

Structure query examples

An easy way to become familiar with retrieving structural metadata and the various options available is to try various parameters using the UI in publicly available registries like SDMX Global Registry and SDMX.IO Sandbox Registry.

On the next couple of screens, we'll cover two programming languages that allow you to retrieve structural metadata and automate.

Curl

The first programming language that allows you to retrieve structural metadata and automate is CURL.

Automate using CURL, a command-line tool in Windows, MacOS, and Linux:

curl -X GET "copy-paste-QUERY-URL-from-registry"

Python

The second programming language that allows you to retrieve structural metadata and automate is PYTHON.

Automate using PYTHON. The "requests" library works very well.

import requests
            response = requests.get("copy-paste-QUERY-URL-from-registry")
            print (response.text)

A closer look at structure queries

Now, let's take a look at a few examples of structure queries in action presented in this short video.

Select Play to begin.

To access the code presented in this video, click here.

What do you know?

Let's complete one final question before concluding. Which of the following statements are true?

Select all that apply and then select Submit.

Schema, availability, and metadata queries

The queries below are included for completeness, but they are out of scope for this introductory course.

Note: host = = entryURL

Data validity:
https://host/schema/context/agency/id/version?dimensionAtObservation
&explicitMeasure

Data availability:
https://host/availability/context/agency/id/version/key/componentId?c
&updatedAfter
&references
&mode

Metadata:
https://host/metadata/metadataset/provider/id/version?detail
https://host/metadata/metadataflow/agency/id/version/provider?detail
https://host/metadata/structure/type/agency/id/version/provider?detail