Examples of queries - SDMX Web Services

Examples of queries

When we know how the statistical information is structured in the dataset of our interest, we can now define criteria to filter out only the information which is needed. In our example, as shown in the table below, the user would like to obtain a limited range of information related to the gross domestic product for Luxembourg at market prices.

Dimension Value Position Description
FREQ A 1 Data aggregated annually
UNIT CP_MEUR 2 Millions of euro
NA_ITEM B1GQ 3 Gross domestic product at market prices
GEO LU 4 Data for Luxembourg only
TIME_PERIOD 2012 - Since 2012 (included)

The SOAP SDMX 2.1 web-service request ("GetGenericData") which is presented below can be used to obtain data from the nama_10_gdp dataset. The information is limited to the records from the year 2012 (TIME_PERIOD ≥ 2012-01). The information is filtered and we are obtaining only gross domestic product at market prices (NA_ITEM=B1GQ) in millions of euros (UNIT=CP_MEUR) and for Luxembourg only (GEO=LU).

It is possible to further extend this example and create more complex queries. We will only show how to use the 'OR' logical operator to build queries involving alternative choices of data. In the example below we want to again query for the nama_10_gdp dataset, but this time for two countries - Belgium or Luxembourg (GEO=LU OR GEO=BE). For more information about OR and AND logical operators, see also Frequently asked questions (FAQ).

If we want to create a REST query for obtaining the same data, then we would need to consider position of dimensions in the dataset structure which are represented explicitly in the result of the "GetDataStructure" discussed in the previous chapter. It can be found under the Dimension@position attribute in the data structure definition. In our particular case, we already indicated the position of the dimensions in the criteria table at the beginning of the present chapter.

A REST query is created according the scheme as below:

https://ec.europa.eu/eurostat/SDMX/diss-web/rest/resource/flowRef/key[?[startPeriod=yyyy[mmdd]&]endPeriod=yyyy[mmdd]]

where

  • resource is the desired resource or artifact,
  • flowRef is the reference to the dataflow, and
  • key is the set of filters to be applied, plus
  • ?[startPeriod=yyyy[mmdd]&]endPeriod=yyyy[mmdd] for any optional additional time filtering. The Date format could contain only the year or the year and the month or, the detailed information, year, month and day.

In our scenario, the user would like to retrieve data (resource should be replaced by 'data'), related to the dataset nama_10_gdp (flowRef should be replaced by 'nama_10_gdp').

Constructing the REST query key:

The key in the query is constructed as a dot ('.') separated list of dimension filtered values.
Format: key = [dimension1].[dimension2].[dimension3]
Example: A.CP_MEUR.B1GQ.LU

Note:

  • Dimensions which should not be filtered are left empty in the query.
    Example with the 1st dimension absent: .CP_MEUR.B1GQ.LU
  • Logical conjuction (the 'OR' logical operator) is created in the REST query key using the plus '+' character.
    Example of the logical conjunction:A.CP_MEUR.B1GQ.BE+LU
  • The response is provided by default in SDMX-ML 2.1 generic schema. Modify the HTTP request header field "Accept: application/vnd.sdmx.structurespecificdata+xml" to receive a response in SDMX-ML 2.1 structure specific schema. The structure specific schema is more suited for processing of large data amounts.
    More information about SDMX-ML formats is available in document SDMX guidelines for the use of web services

Below, we introduce various examples of REST queries related to the dataset nama_10_gdp created for different configurations of search criteria.

Examples:

 

https://ec.europa.eu/eurostat/SDMX/diss-web/rest/data/nama_10_gdp/A.CP_MEUR.B1GQ.LU/?startPeriod=2012&endPeriod=2015
Position 1 2 3 4
Dimension FREQ UNIT NA_ITEM GEO
Key A CP_MEUR B1GQ LU
Key text A.CP_MEUR.B1GQ.LU
https://ec.europa.eu/eurostat/SDMX/diss-web/rest/data/nama_10_gdp/.CP_MEUR.B1GQ.LU+BE/?startPeriod=2012&endPeriod=2015
Position 1 2 3 4
Dimension FREQ UNIT NA_ITEM GEO
Key - CP_MEUR B1GQ LU or BE
Key text .CP_MEUR.B1GQ.LU+BE
  • Note that the value of the 1st dimension should not be in any way constrained. This is represented in the REST protocol in a way that the value for the position 1 is absent. Values for consecutive dimensions are separated using the dot character ('.') and empty values are completely absent.
  • The 'OR' alternative logical operator applied to the position 4 (LU or BE) and is represented by the plus character ('+') in the REST protocol

 

https://ec.europa.eu/eurostat/SDMX/diss-web/rest/data/nama_10_gdp/.CP_MEUR.B1GQ./?startPeriod=2012&endPeriod=2015
Position 1 2 3 4
Dimension FREQ UNIT NA_ITEM GEO
Key - CP_MEUR B1GQ -
Key text .CP_MEUR.B1GQ.
Note that the absent values for positions 1 and 4 are represented using dot '.'

 

https://ec.europa.eu/eurostat/SDMX/diss-web/rest/data/nama_10_gdp/..../?startPeriod=2013&endPeriod=2013
Position 1 2 3 4
Dimension FREQ UNIT NA_ITEM GEO
Key - - - -
Key text ....
The above query doesn't constraint obtained data in any other way than time period and the full dataset is downloaded for the year 2013. It is worth noticing that both startPeriod and endPeriod time filters are inclusive which translates to the period between 1 Jan 2013 and 31 Dec 2013 in our example.