REST SDMX 2.1 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://www.ec.europa.eu/SDMX/diss-web/rest/resource/agencyID/resourceID/version

Dataflow for the list of available datasets Dataflow for the list of available datasets

The structure to build a query for the list of available datasets is

http://www.ec.europa.eu/eurostat/SDMX/diss-web/rest/dataflow/ESTAT/all/latest

More Less

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) Datastructure for a dataset structure definition (DSD)

This is an example of a request of the DSD of the data flow "nama_gdp_c":

http://ec.europa.eu/eurostat/SDMX/diss-web/rest/datastructure/ESTAT/DSD_nama_gdp_c

The AgencyID is always ESTAT and is a required field.

data for retrieving data 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

More Less

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" graduatedin1990 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 cdh_e_fos
  • for all frequencies (FREQ) and year of graduation (Y_GRAD),
  • UNIT=PC (percentage)
  • FOS7(Field of Science)=FOS1(Natural Sciences)
  • GEO=BE(Belgium)
  • from 2005 to 2011

http://ec.europa.eu/eurostat/SDMX/diss-web/rest/data/cdh_e_fos/..PC.FOS1.BE/?startperiod=2005&endPeriod=2011

 

Example of result:

More Less

<?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/XMLSchemainstance">
    <message:Header>
      <message:ID>8d616881a50e6cea3092cd3b2e3acee1</message:ID>
      <message:Test>false</message:Test>
      <message:Prepared>20130528T10:53:21</message:Prepared>
      <message:Sender id="ESTAT">
        <message:Receiver id="RECEIVER"/>
        <message:Structure structureID="ESTAT_DSD_cdh_e_fos_1_0"
          dimensionAtObservation="TIME_PERIOD">
          <common:Structure>
            <Ref agencyID="ESTAT" id="DSD_cdh_e_fos" version="1.0"/>
          </common:Structure>
        </message:Structure>
        <message:DataSetAction>Append</message:DataSetAction>
        <message:DataSetID>cdh_e_fos</message:DataSetID>
      </message:Sender>
    </message:Header>
    <message:DataSet structureRef="ESTAT_DSD_cdh_e_fos_1_0">
      <generic:Series>
        <generic:SeriesKey>
          <generic:Value id="UNIT" value="PC"/>
          <generic:Value id="Y_GRAD" value="TOTAL"/>
          <generic:Value id="FOS07" value="FOS1"/>
          <generic:Value id="GEO" value="BE"/>
          <generic:Value id="FREQ" value="A"/>
        </generic:SeriesKey>
        <generic:Obs>
          <generic:ObsDimension value="2009"/>
          <generic:ObsValue value="NaN"/>
          <generic:Attributes>
            <generic:Value id="OBS_STATUS" value="na"/>
          </generic:Attributes>
        </generic:Obs>
        <generic:Obs>
          <generic:ObsDimension value="2006"/>
          <generic:ObsValue value="NaN"/>
          <generic:Attributes>
            <generic:Value id="OBS_STATUS" value="na"/>
          </generic:Attributes>
        </generic:Obs>
      </generic:Series>
      <generic:Series>
        <generic:SeriesKey>
          <generic:Value id="UNIT" value="PC"/>
          <generic:Value id="Y_GRAD" value="Y_GE1990"/>
          <generic:Value id="FOS07" value="FOS1"/>
          <generic:Value id="GEO" value="BE"/>
          <generic:Value id="FREQ" value="A"/>
        </generic:SeriesKey>
        <generic:Obs>
          <generic:ObsDimension value="2009"/>
          <generic:ObsValue value="43.75"/>
        </generic:Obs>
        <generic:Obs>
          <generic:ObsDimension value="2006"/>
          <generic:ObsValue value="NaN"/>
          <generic:Attributes>
            <generic:Value id="OBS_STATUS" value="na"/>
          </generic:Attributes>
        </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 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