Eurostat Online Help for Data Browser
Child pages
  • API - Detailed guidelines - SDMX2.1 API - data query

Versions Compared

Old Version 2

changes.mady.by.user Philippe Weber

Saved on

compared with

New Version Current

changes.mady.by.user Philippe Weber

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Overview

Data queries allow retrieving statistical data. Entire datasets, individual observations, or anything in between, can be retrieved using filters on dimensions (including time).

The data retrieved can be retrieved in a variety of formats (JSON, XML, CSV, etc.).

Depending on the request, a data query can result in a (potentially very) large response in which case data is delivered asynchronously. For more information please read the page 'API - Detailed guidelines - Asynchronous API'

Warning

It is important to remember that only the last version of each statistical observation is made available in the system. When a statistical observation is being updated, the previous value of the observation is lost and cannot be returned.

Query URL syntax

Generic SDMX2.1 syntax is the following

Code Block
protocol://ws-entry-point/data/{resourceID}/{key}?{format}&{startPeriod}&{endPeriod}&{firstNObservations}&{lastNObservations}&{detail}&{compressed}

Parameter

Description

resourceID

The id of the artefact for which data have been reported.

key

The combination of dimension values identifying the slice of the cube for which data should be returned. Wildcarding is supported via entering no value. For example, if the following key identifies the bilateral exchange rates for the daily US dollar exchange rate against the euro, D.USD.EUR.SP00.A, then the following key can be used to retrieve the data for all currencies against the euro: D..EUR.SP00.A. 

format

format=<value>
To get responses in other format than SDMX-ML 2.1 Generic, which is supported by default.
Supported values are:
SDMX_2.1_STRUCTURED for SDMX-ML 2.1 Structure Specific Data
SDMX-CSV for SDMX-CSV 1.0 flat format
JSON for JSON-stat
TSV for Tab Separated Value

startPeriod

endPeriod

Data filtering on time
startPeriod=<value>&endPeriod=<value>

firstNObservations


The maximum number of observations to be returned for each of the matching series, starting from the first observation

lastNObservations

The maximum number of observations to be returned for each of the matching series, counting back from the most recent observation

detail

Supported values are:
dataonly for each series, only the observations are returned, no attributes are returned
serieskeysonly for each series, only the series key are returned, no data or attributes are returned
nodata for each series, only the series level attributes are returned

compressed

To get responses in .gz compressed format


Key parameter - Data filtering on dimension

The key parameter defines values of the dimensions in the order of structure.

The key is constructed as a dot ('.') separated list of dimension filtered values.

To build the key for a selected dataflow (taking NAMA_10_GDP as example below), you must know beforehand:

  • the structure and order of the dimensions as described in the DSD 

    Code Block
    https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/datastructure/ESTAT/NAMA_10_GDP/latest

  • the available positions in the dataset as described in the Content Constraint

    Code Block
    https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/contentconstraint/ESTAT/NAMA_10_GDP/latest

  • If needed you can download the codelist definition referenced for each DSD dimension

    Code Block
    https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/codelist/ESTAT/FREQ/latest
https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/codelist/ESTAT/UNIT/latest
https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/codelist/ESTAT/NA_ITEM/latest
https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/codelist/ESTAT/GEO/latest

  • Alternatively it could help to work on filtered code lists that can be retrieved with the special query :

    Code Block
    https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/dataflow/ESTAT/NAMA_10_GDP/1.0?references=descendants&detail=referencepartial

In NAMA_10_GDP  example, the structure of seriesKey is [FREQ].[UNIT].[NA_ITEM].[GEO]

An example seriesKey would be A.CP_MEUR.B1GQ.LU, where:

Position

1

2

3

4

Dimension

FREQ

UNIT

NA_ITEM

GEO

Key value

A

CP_MEUR

B1GQ

LU

Meaning

Data aggregated annually

Current prices, million euro

Gross domestic product at market prices

Luxembourg

Dimensions which should not be filtered are left empty in the query. Extending above example all NA_ITEM for Luxembourg could be retrieved with key A.CP_MEUR..LU

Explicit listing of values for a dimension is done using the plus '+' character. For example, retrieving value for a Luxembourg and Belgium would be done with key = A.CP_MEUR.B1GQ.BE+LU

Examples
https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/NAMA_10_GDP/A.CP_MEUR.B1GQ.LU
https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/NAMA_10_GDP/A.CP_MEUR..LU 
https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/NAMA_10_GDP/A.CP_MEUR.B1GQ.BE+LU

Detail parameter - examples

...