Step-by-Step Usage Example for SDMX API

Retrieving the List of Structural Elements

Use Case:

  1. The user wants to find out which types of data (datasets) are available.
  2. The user is looking for a list of all available dataflows, including their metadata and descriptions.

What should the user do?

  1. Retrieve the list of all current dataflows published by the State Statistics Service of Ukraine (SSSU), along with their complete metadata (e.g., identifier, version, description, structure of dimensions, attributes, etc.).

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0/structure/dataflow/all/all/latest?detail=full&references=none

How to read the response (SDMX 2.1 example)?

The response contains a list of structures, specifically dataflows.

Example:

<str:Dataflow urn="urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=SSSU:DF_SUPPLY_USE_ENERGY(14.0.0)" agencyID="SSSU" id="DF_SUPPLY_USE_ENERGY" version="14.0.0" isFinal="true" isExternalReference="false"> 
<com:Annotations> 
<com:Annotation id="dataEngineSettings"/> 
<com:Annotation id="origin"/> 
<com:Annotation id="DataEngine"> 
<com:AnnotationTitle>timeseries_v2</com:AnnotationTitle> 
</com:Annotation> 
<com:Annotation id="isFinal"/> 
<com:Annotation id="lastUpdatedAt"/> 
</com:Annotations> 
<com:Name xml:lang="uk">Постачання та використання енергії</com:Name> 
<com:Name xml:lang="en">Supply and use of energy</com:Name> 
<com:Description xml:lang="uk">2.03.08.02</com:Description> 
<com:Description xml:lang="en">2.03.08.02</com:Description> 
<str:Structure> 
<Ref agencyID="SSSU" id="DSD_SUPPLY_USE_ENERGY" version="9.0.0" package="datastructure" class="DataStructure"/> 
</str:Structure> 
</str:Dataflow>

From this response, you can extract the dataflow name and its latest version, e.g.:

SSSU:DF_SUPPLY_USE_ENERGY(14.0.0)

as well as the DSD version:

DSD_SUPPLY_USE_ENERGY(9.0+.0)

 

Alternatively, you can request a specific dataflow:

SDMX 2.1:

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/2.1/dataflow/SSSU/DF_SUPPLY_USE_ENERGY/14.0.0?detail=full&references=none

SDMX 3.0:

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0/structure/dataflow/SSSU/DF_SUPPLY_USE_ENERGY/14.0.0?detail=full&references=none

 

Retrieving DSD Information

Use Case:

  1. The user wants to learn about the structure of a dataset: which dimensions and attributes are available.

What should the user do?

  1. Retrieve the data structure definition (DSD) for the selected dataflow.

Examples of queries:

SDMX 2.1:

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/2.1/datastructure/SSSU/DSD_SUPPLY_USE_ENERGY/9.0.0?detail=full&references=descendants

SDMX 3.0:

https://stat.gov.ua/sdmx/workspaces/default:integration/registry/sdmx/3.0/structure/datastructure/SSSU/DSD_SUPPLY_USE_ENERGY/9.0+.0?detail=full&references=descendants

How to read the response (SDMX 2.1 example)?

The response contains a list of structures, specifically the list of dimensions, measures, and attributes.For example, the section:

<str:DimensionList id="DimensionDescriptor">

contains the list of all dimensions for the dataset and their display order.For instance, the dimension "INDICATOR" is at position 0 (displayed first) and is based on the concept scheme

CS_SUPPLY_USE_ENERGY version 5.0.0

 
<str:Dimension id="INDICATOR" urn="urn:sdmx:org.sdmx.infomodel.datastructure.Dimension=SSSU:DSD_SUPPLY_USE_ENERGY(9.0.0).INDICATOR" position="0">
<str:ConceptIdentity>
<Ref maintainableParentID="CS_SUPPLY_USE_ENERGY" maintainableParentVersion="5.0.0" agencyID="SSSU" id="INDICATOR" package="conceptscheme" class="Concept"/>
</str:ConceptIdentity>
</str:Dimension>
 

Reviewing Concept Scheme Structure

Use Case:

  1. The user wants to find out the possible values for dimensions in a dataset.

What should the user do?

  1. Retrieve the structure of the concept scheme.

The response contains a list of concepts, indicating the codelists on which the concepts are based.

For example:

<str:Concept id="INDICATOR" urn="urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=SSSU:CS_SUPPLY_USE_ENERGY(5.0.0).INDICATOR">
<com:Name xml:lang="uk">Показник</com:Name>
<com:Name xml:lang="en">Indicator</com:Name>
<str:CoreRepresentation>
<str:Enumeration>
<Ref agencyID="SSSU" id="CL_SUPPLY_USE_ENERGY_INDICATOR" version="2.0.1" package="codelist" class="Codelist"/>
</str:Enumeration>
</str:CoreRepresentation>
</str:Concept>

This indicates that the indicators for the "Supply and use of energy" dataset take their values from the codelist

CL_SUPPLY_USE_ENERGY_INDICATOR version 2.0.1

 

Retrieving Codelist Values

Use Case:

  1. The user wants to find out the values used in a specific codelist for a given dataset.

What should the user do?

  1. Retrieve the structure of the codelist for the required version.

For example:

<str:Code id="ELECTRICITY_USE" urn="urn:sdmx:org.sdmx.infomodel.codelist.Code=SSSU:CL_SUPPLY_USE_ENERGY_INDICATOR(2.0.1).ELECTRICITY_USE">
<com:Name xml:lang="uk">Обсяг використаної електроенергії</com:Name>
<com:Name xml:lang="en">Amount of electricity used</com:Name>
</str:Code>
This means there is an indicator with the identifier ELECTRICITY_USE, which translates as "Обсяг використаної електроенергії" or "Amount of electricity used".
 

Retrieving Statistical Data

Use Case:

  1. The user wants to obtain data (time series) for a specific dataset.

What should the user do?

  1. Make a data request.
  1. DF_SUPPLY_USE_ENERGY - dataset identifier;
  2. *.*.*.*.*.*.* - asterisks mean the request does not filter by any specific category (all possible values); the number of asterisks corresponds to the number of dimensions from the DSD structure;
  3. /SSSU - data source (State Statistics Service of Ukraine).

You can insert specific values instead of * to refine your request.