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.
|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:
- 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]
- 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.