SDMX Web Services
REST SDMX 2.1
The SDMX REST API is based on following principles:
- In REST, specific information is known as "Resource". In a SDMX context specific resources would be, for example, code lists, concept schemes, data structure definitions, dataflows, etc. Each resource is addressable via a global identifier (i.e.: a URI).
- Manipulating resources is done using methods defined in the HTTP protocol
(e.g.: GET, POST, PUT, DELETE). This API focuses on data retrieval, and, therefore, only the usage of HTTP GET is covered in this document - A resource can be represented in various formats (such as the different flavours and versions of the SDMX-ML standard). Selection of the appropriate representation is done using HTTP Content Negotiation and the HTTP Accept request header.
The format for creating a REST request is:
http://ec.europa.eu/eurostat/SDMX/diss-web/rest/resource/agencyID/resourceID/version
Dataflow for the list of available datasets
The structure to build a query for the list of available datasets is
http://ec.europa.eu/eurostat/SDMX/diss-web/rest/dataflow/ESTAT/all/latest
| Parameter | Type | Description | Sample |
|---|---|---|---|
| agencyID | A string compliant with the SDMX common:NCNameIDType | The agency maintaining the artefact to be Returned. In Dissemination Web Service ESTAT is the only allowed agencyID. | |
| resourceID | A string compliant with the SDMX common: IDType | The id of the artefact to be returned When not specified it is assumed to be "all" | all: coming from any resource |
| version | A string compliant with the SDMX common:VersionType | The version of the artefact to be returned. The latest version is returned when not specified. | Always 1.0 at Eurostat |
The resource element is required, but the other elements are optional.
Datastructure for a dataset structure definition (DSD)
This is an example of a request of the DSD of the data flow "nama_10_gdp":
http://ec.europa.eu/eurostat/SDMX/diss-web/rest/datastructure/ESTAT/DSD_nama_10_gdp
The AgencyID is always ESTAT and is a required field.
data for retrieving data
The structure to build the query is:
http://ec.europa.eu/eurostat/SDMX/diss-web/rest/resource/flowRef/key/providerRef
The response is provided by default in SDMX-ML 2.1 generic schema. Modify the HTTP header field "Accept" with 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 the processing of large amounts of data.
For more information about SDMX-ML formats, see also : SDMX GUIDELINES FOR THE USE OF WEB SERVICES
| Parameter | Type | Description |
|---|---|---|
| flowRef | A string identifying the dataflow. The syntax is agency id, artefact id, version, separated by a ",". For example: AGENCY_ID,FLOW_ID,VERSION In case the string only contains one out of these 3 elements, it is considered to be the flow id, i.e. ALL,FLOW_ID,LATEST In case the string only contains two out of these 3 elements, they are considered to be the agency id and the flow id, i.e. AGENCY_ID,FLOW_ID,LATEST | The data (or metadata) flow of the data (or metadata) to be returned |
| key | A string compliant with the KeyType defined in the SDMX WADL. | The key of the artifact to be returned. Wildcarding is supported by omitting the dimension code for the dimension to be wild carded. For example, if the following series key identifies the " Employed doctorate holders in non managerial and non professional occupations by fields of science" graduated in 1990 or after, in percentage as unit, in natural sciences, in Belgium: /Y_GE1990.PC.FOS1.BE/ then the following one would identify the same for all years of graduation: /.PC.FOS1.BE/ The OR operator is supported using the + character. For example, the following series key would identify the same for Belgium or Germany: /.PC.FOS1.BE+DE/ |
| providerRef | A string identifying the provider. The syntax is agency id, provider id, separated by a ",". For example: AGENCY_ID,PROVIDER_ID. In case the string only contains one out of these 2 elements, it is considered to be the provider id, i.e. ALL,PROVIDER_ID. | The provider of the data (or metadata) to be retrieved. If not supplied, the returned message will contain data (or metadata) provided by any provider. Eurostat is considered as the data provider for all datasets. |
For instance , the request below demands
- the data of nama_10_gdp
- for all frequencies (FREQ),
- UNIT=CLV10_MEUR (Chain linked volumes (2010), million euro)
- NA_ITEM (National accounts indicator (ESA 2010))=B1GQ (Gross domestic product at market prices)
- GEO=BE (Belgium)
- from 2005 to 2011
Example of result:
<?xml version="1.0" encoding="UTF8" ?>
<message:GenericData xmlns:footer="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message/footer" xmlns:generic="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/data/generic" xmlns:common="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/common" xmlns:message="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<message:Header>
<message:ID>58758c0037cecb39b61a10b07ce2c27c</message:ID>
<message:Test>false</message:Test>
<message:Prepared>2019-07-22T10:05:39</message:Prepared>
<message:Sender id="ESTAT">
<common:Name xml:lang="en">Eurostat</common:Name>
<message:Timezone>+01:00</message:Timezone>
</message:Sender>
<message:Receiver id="RECEIVER"/>
<message:Structure structureID="ESTAT_DSD_nama_10_gdp_1_0" dimensionAtObservation="TIME_PERIOD">
<common:Structure>
<Ref agencyID="ESTAT" id="DSD_nama_10_gdp" version="1.0"/>
</common:Structure>
</message:Structure>
<message:DataSetAction>Append</message:DataSetAction>
<message:DataSetID>nama_10_gdp</message:DataSetID>
</message:Header>
<message:DataSet structureRef="ESTAT_DSD_nama_10_gdp_1_0">
<generic:Series>
<generic:SeriesKey>
<generic:Value id="UNIT" value="CLV10_MEUR"/>
<generic:Value id="NA_ITEM" value="B1GQ"/>
<generic:Value id="GEO" value="BE"/>
<generic:Value id="FREQ" value="A"/>
</generic:SeriesKey>
<generic:Obs>
<generic:ObsDimension value="2011"/>
<generic:ObsValue value="371666.1"/>
</generic:Obs>
<generic:Obs>
<generic:ObsDimension value="2010"/>
<generic:ObsValue value="365100.5"/>
</generic:Obs>
<generic:Obs>
<generic:ObsDimension value="2009"/>
<generic:ObsValue value="355348.9"/>
</generic:Obs>
<generic:Obs>
<generic:ObsDimension value="2008"/>
<generic:ObsValue value="363540.1"/>
</generic:Obs>
<generic:Obs>
<generic:ObsDimension value="2007"/>
<generic:ObsValue value="360715.1"/>
</generic:Obs>
<generic:Obs>
<generic:ObsDimension value="2006"/>
<generic:ObsValue value="348688.9"/>
</generic:Obs>
<generic:Obs>
<generic:ObsDimension value="2005"/>
<generic:ObsValue value="340163.9"/>
</generic:Obs>
</generic:Series>
</message:DataSet>
</message:GenericData>
For more information about parameters, see also: SDMX GUIDELINES FOR THE USE OF WEB SERVICES
Not supported operations
| metadatastructure | provisionagreement |
| categoryscheme | structureset |
| conceptscheme | process |
| codelist | categorisation |
| hierarchicalcodelist | contentconstraint |
| organisationscheme | attachementconstraint |
| agencyscheme | structure |
| dataproviderscheme | metadata |
| dataconsumerscheme | schema |
| organisationunitscheme | contentconstraint |
| metadataflow | attachementconstraint |
| reportingtaxonomy |