Home

The ECB SDMX 2.1 RESTful web service offers programmatic access to the statistical data and metadata disseminated via the ECB Statistical Data Warehouse.

It offers two modes of operation:

Data retrieval: You know the data you want to retrieve (e.g.: daily exchange rates of the Japanese yen against the euro).
Data discovery: Using a metadata-driven approach, you want to discover the data exposed by the web service.

The web service complies with the SDMX 2.1 RESTful web service specification.

Overview

Let's first start with a brief introduction of the SDMX information model.

Concepts and codelists

In order to make sense of some statistical data, we need to know the concepts associated with them. For example, on its own the figure 1.2953 is pretty meaningless, but if we know that this is an exchange rate of the US dollar against the euro on 23 November 2006, it starts making more sense.

Some of the concepts can be free text (such as a comment about a particular observation value) but others take their values from a controlled vocabulary list (such as, for example, a list of countries). These are known as code lists.

Data Structure Definitions

There are two types of concepts: dimensions and attributes. Dimensions, when combined, allow to uniquely identify statistical data. Attributes on the other hand do not help identifying statistical data, but they add useful information (like the number of decimals). Dimensions and attributes are known as components.

All the concepts that describe a particular domain (such as exchange rates or inflation) are grouped in a data structure definition (DSD).

Data

The measurement of some phenomenon (e.g. the figure 1.2953 mentioned above) is known as an observation in SDMX. Observations are grouped together into a data set. However, there can also be an intermediate grouping. For example, all exchange rates for the US dollar against the euro can be measured on a daily basis and these measures can then be grouped together, in a so-called time series. Similarly, you can group a collection of observations made at the same point in time, in a cross-section (for example, the values of the US dollar, the Japanese yen and the Swiss franc against the euro at a particular date). Of course, these intermediate groupings are entirely optional and you may simply decide to have a flat list of observations.

Dataflows represent the data that covers a particular domain (such as, for example, balance of payments). A dataflow provides a reference to the data structure definition that applies for a particular domain, thereby indicating how the data for that domain will look like.

The SDMX information model is much richer than this limited introduction, however the above should be sufficient to understand the basics of this web service. For additional information, please refer to the SDMX documentation.

Data queries

In a nutshell

All the data stored in the Statistical Data Warehouse can be retrieved using the query string described below.

protocol://wsEntryPoint/resource/flowRef/key?parameters

where parameters are defined as such:

startPeriod=value&endPeriod=value&updatedAfter=value&firstNObservations=value&lastNObservations=value&detail=value&includeHistory=value

Syntax definition

Protocol

The web service is available over httpand https.

wsEntryPoint

The web service entry point is available at the following location:
https://sdw-wsrest.ecb.europa.eu/service/

resource

The resource for data queries is data

flowRef Defining the dataflow reference

A reference to the dataflow describing the data that needs to be returned.

The syntax is the identifier of the agency maintaining the dataflow, followed by the identifier of the dataflow, followed by the dataflow version, separated by a ,(comma).
For example: AGENCY_ID,FLOW_ID,VERSION

If the parameter contains only one of these 3 elements, it is considered to be the identifier of the dataflow. The value for the identifier of the agency maintaining the dataflow will default to all, while the value for the dataflow version will default to latest.

If the string contains only two of these 3 elements, they are considered to be the identifier of the agency maintaining the dataflow and the identifier of the dataflow. The value for the dataflow version will default to latest.

In order to see the dataflows available in the ECB statistical data warehouse, a metadata query for all dataflows can be performed:
https://sdw-wsrest.ecb.europa.eu/service/service/dataflow

key Defining the dimension values

As explained in the Overview, the combination of dimensions allows statistical data to be uniquely identified. Such a combination is known as a series key in SDMX and this is what is needed in the key parameter.

Let's say for example that exchange rates can be uniquely identified by the following:

the frequency at which they are measured (e.g.: on a daily basis - code D),
the currency being measured (e.g.: US dollar - code USD),
the currency against which a currency is being measured (e.g.: Euro - code EUR),
the type of exchange rates (Foreign exchange reference rates - code SP00) and
the series variation (such as average or standardised measure for given frequency, code A).

In order to build the series key, you need to take the value for each of the dimensions (in the order in which the dimensions are defined in the DSD) and join them with a .(dot). The series key for the example above therefore becomes: D.USD.EUR.SP00.A

Wildcarding is supported by omitting the value for the dimension to be wildcarded. For example, the following series key can be used to retrieve the data for all daily currencies against the euro: D..EUR.SP00.A

The OR operator is supported using the + (plus) character. For example, the following key can be used to retrieve the exchange rates against the euro for both the US dollar and the Japanese Yen: D.USD+JPY.EUR.SP00.A

You can of course combine wildcarding and the OR operator. For example, the following key can be used to retrieve daily or monthly exchange rates of any currency against the euro: D+M..EUR.SP00.A

startPeriod & endPeriod Defining a date range

It is possible to define a date range for which observations should be returned by using the startPeriod and/or endPeriod parameters. The values should be given according to the syntax defined in ISO 8601 or as SDMX reporting periods. The format will vary depending on the frequency.

The supported formats are:

YYYY for annual data (e.g.: 2013).
YYYY-S[1-2] for semi-annual data (e.g.: 2013-S1).
YYYY-Q[1-4] for quarterly data (e.g.: 2013-Q1).
YYYY-MM for monthly data (e.g.: 2013-01).
YYYY-W[01-53] for weekly data (e.g.: 2013-W01).
YYYY-MM-DD for daily data (e.g.: 2013-01-01).

updatedAfter Retrieving deltas

By supplying a percent-encoded timestamp to the updatedAfter parameter, it is possible to retrieve the latest version of changed values in the database since a certain point in time (so-called updates and revisions).

This will include:

The observations that have been added since the supplied timestamp.
The observations that have been revised since the supplied timestamp.
The observations that have been deleted since the supplied timestamp.

For example, the percent-encoded representation for 2009-05-15T14:15:00+01:00 would be:
2009-05-15T14%3A15%3A00%2B01%3A00.

Developers who update their local databases with data stored in the ECB Statistical Data Warehouse should make use of the updatedAfter parameter as this will significantly improve performance: Instead of systematically downloading data that have not changed, you will only receive the changes made in our database since the last time you performed the same query.

Using an If-Modified-Since header constitutes a good alternative to the updatedAfter parameter mentioned above should you not be able to handle updates and revision, or should you prefer to perform a full refresh of your local database when something has changed. This triggers a so-called HTTP conditional request, which will return the data only if something has changed since the timestamp supplied in the If-Modified-Since header. If nothing has changed, the server will respond with a HTTP 304 response code.

detailDefining the amount of details

Using the detail parameter, it is possible to specify the desired amount of information to be returned by the web service.

Possible options are:

full: The data (series and observations) and the attributes will be returned. This is the default.
dataonly: The attributes will be excluded from the returned message.
serieskeysonly: Only the series, but without the attributes and the observations, will be returned. This can be used for example to list series that match a certain query, without returning the actual data.
nodata: The series, including the attributes, will be returned, but the observations will not.

firstNObservations & lastNObservationsDefining the number of observations

Using the firstNObservations and/or lastNObservations parameters, it is possible to specify the maximum number of observations to be returned for each of the matching series, starting from the first observation (firstNObservations) or counting back from the most recent observation (lastNObservations).

dimensionAtObservationDefining the way the data should be organized

Using the dimensionAtObservation parameter, you can define the way data should be organized in the returned message.

Possible options are:

TIME_PERIOD: This will return a timeseries view of the data. This is the default.
AllDimensions: This will return a "flat" view of the data, with no groupings.

includeHistoryRetrieving how data evolved over time

Using the includeHistory parameter, you can instruct the web service to return previous versions of the matching data. This is useful to see how the data have evolved over time, i.e. when new data have been released or when data have been revised or deleted.

Possible options are:

false: Only the version currently in production will be returned. This is the default.
true: The version currently in production, as well as all previous versions, will be returned.

Examples

Please refer to the Useful tips section to see examples of these queries with command line tools such as curl or wget.

Retrieve the data for the series M.USD.EUR.SP00.A for the EXR dataflow

https://sdw-wsrest.ecb.europa.eu/service/data/EXR/M.USD.EUR.SP00.A

Retrieve the data for the series M.USD.EUR.SP00.A for the EXR dataflow

https://sdw-wsrest.ecb.europa.eu/service/data/EXR/M.USD.EUR.SP00.A

Retrieve the data for the EXR dataflow, matching the supplied series keys, using wildcarding for the second dimension

https://sdw-wsrest.ecb.europa.eu/service/data/EXR/M..EUR.SP00.A

Retrieve the updates and revisions for the data matching the supplied series keys, using the OR operator for the second dimension
As mentioned previously, the ISO 8601 timestamp needs to be percent-encoded.

https://sdw-wsrest.ecb.europa.eu/service/data/EXR/M.USD+GBP+JPY.EUR.SP00.A?updatedAfter=2009-05-15T14%3A15%3A00%2B01%3A00

Retrieve the data matching the supplied series key and restricting the start and end dates

https://sdw-wsrest.ecb.europa.eu/service/data/EXR/D.USD.EUR.SP00.A?startPeriod=2009-05-01&endPeriod=2009-05-31

Retrieve all the data for the EXR dataflow
Please note that depending on the dataflow size, retrieving all its data could take a significant amount of time to process.

https://sdw-wsrest.ecb.europa.eu/service/data/EXR

Metadata queries

In a nutshell

All metadata can be retrieved using the query string described below.

protocol://wsEntryPoint/resource/agencyID/resourceID/version?detail=value&references=value

Syntax definition

Protocol

The web service is available over httpand https.

wsEntryPoint

The web service entry point is available at the following location:
https://sdw-wsrest.ecb.europa.eu/service/

resource

The following resources are supported by the web service, but please note that not all of them are used at the moment: datastructure, metadatastructure, categoryscheme, conceptscheme, codelist, hierarchicalcodelist, organisationscheme, agencyscheme, dataproviderscheme, dataconsumerscheme, organisationunitscheme, dataflow, metadataflow, reportingtaxonomy, provisionagreement, structureset, process, categorisation, contentconstraint, attachmentconstraint and structure.

agencyID Identifying the maintainer

Organisations defining metadata are known as agencies in SDMX. In order to retrieve an artefact, you should know the identifier of its maintainer.

resourceID Identifying the artefact

The identifier of the resource, such as CL_FREQ for the frequency codelist maintained by the ECB.

version Getting the right version

The version of the artefact to be returned. When the version number is not supplied, the latest version of the resource is returned.

detailDefining the amount of detail

Using the detail parameter, you can specify the desired amount of information to be returned. For example, it is possible to instruct the web service to return only basic information about the resource (i.e.: its id, agency id, version and name. This is also known in SDMX as a stub).

The allowed values are:

full: All available information for all artefacts will be returned. This is the default.
allstubs: All artefacts will be returned as stubs.
referencestubs: The referenced artefacts will be returned as stubs.

referencesResolving dependencies

Using the references parameter, you can instruct the web service to return (or not) the artefacts referenced by the artefact to be returned (for example, the code lists and concepts used by the data structure definition matching the query). You can also retrieve the artefacts that use the matching artefact (for example, the dataflows that use the data structure definition matching the query).

Possible values are:

none: No references will be returned. This is the default.
parents: The artefacts that use the artefact matching the query (for example, the dataflows that use the data structure definition matching the query) will be returned.
parentsandsiblings: The artefacts that use the artefact matching the query, as well as the artefacts referenced by these artefacts will be returned.
children: The artefacts referenced by the matching artefact will be returned (for example, the concept schemes and code lists used in a DSD).
descendants: References of references, up to any level, will also be returned.
all: The combination of parentsandsiblings and descendants.
In addition, a concrete type of resource, may also be used (for example, references=codelist).

Examples

Please refer to the Authentication & Access guide section to understand the authentication and authorization principles and correctly adapt the elow examples with your IAM credentials for command line tools such as curl, wget or powershell.

Retrieve version 1.0 of the DSD with id ECB_EXR1 maintained by the ECB, as well as the code lists and the concepts used in the DSD

wget -O md.xml --header 'authorization: Basic ZXV1c2VybmFtZTpwYXNzd29yZA==' https://sdw-wsrest.ecb.europa.eu/service/datastructure/ECB/ECB_EXR1/1.0?references=children

Retrieve the latest version in production of the DSD with id ECB_EXR1 maintained by the ECB, without the code lists and concepts of the DSD

wget -O md.xml --header 'authorization: Basic ZXV1c2VybmFtZTpwYXNzd29yZA==' https://sdw-wsrest.ecb.europa.eu/service/datastructure/ECB/ECB_EXR1

You can also use the keyword latest:

wget -O md.xml --header 'authorization: Basic ZXV1c2VybmFtZTpwYXNzd29yZA==' https://sdw-wsrest.ecb.europa.eu/service/datastructure/ECB/ECB_EXR1/latest

Retrieve all DSDs maintained by the ECB, as well as the dataflows using these DSDs

wget -O md.xml --header 'authorization: Basic ZXV1c2VybmFtZTpwYXNzd29yZA==' https://sdw-wsrest.ecb.europa.eu/service/datastructure/ECB?references=dataflow

You can also use the keywords all and latest:

wget -O md.xml --header 'authorization: Basic ZXV1c2VybmFtZTpwYXNzd29yZA==' https://sdw-wsrest.ecb.europa.eu/service/datastructure/ECB/all/latest?references=dataflow

Retrieve the latest version in production of all code lists maintained by all maintenance agencies, but without the codes

wget -O md.xml --header 'authorization: Basic ZXV1c2VybmFtZTpwYXNzd29yZA==' https://sdw-wsrest.ecb.europa.eu/service/codelist?detail=allstubs

You can also use the all and latest keywords:

wget -O md.xml --header 'authorization: Basic ZXV1c2VybmFtZTpwYXNzd29yZA==' https://sdw-wsrest.ecb.europa.eu/service/codelist/all/all/latest?detail=allstubs

The structure keyword can be used to retrieve metadata regardless of their type (code list, concept scheme, etc.). For example, the following retrieves, as stubs, the latest version in production of all maintainable artefacts maintained by the ECB

wget -O md.xml --header 'authorization: Basic ZXV1c2VybmFtZTpwYXNzd29yZA==' https://sdw-wsrest.ecb.europa.eu/service/structure/ECB?detail=allstubs

Again, you can also use the all and latest keywords:

wget -O md.xml --header 'authorization: Basic ZXV1c2VybmFtZTpwYXNzd29yZA==' https://sdw-wsrest.ecb.europa.eu/service/structure/ECB/all/latest?detail=allstubs

Schema queries

In a nutshell

XML schemas can be used to validate SDMX-ML Structure Specific Data messages and can be retrieved using the query string described below.

protocol://wsEntryPoint/resource/context/agencyID/resourceID/version

Syntax definition

Protocol

The web service is available over http and https.

wsEntryPoint

The web service entry point is available at the following location:
https://sdw-wsrest.ecb.europa.eu/service/

resource

The resource for schema queries is schema

context Applying the right constraints

The context determines the constraints that need to be taken into account when generating the schema.

Possible values are:

datastructure: constraints attached to the DSD will be used in the schema
dataflow: constraints attached to the dataflow, and to the DSD referenced by the dataflow, will be used in the schema
provisionagreement: constraints attached to the provision agreement, as well as to the dataflow referenced by the agreement and to the DSD referenced by the dataflow will be available in the schema

agencyID Identifying the maintainer

The identifier of the maintainer of the context.

resourceID Identifying the artefact

The identifier of the context, such as EXR for the dataflow about exchange rates maintained by the ECB.

version Getting the right version

The version of the context to be returned. When the version number is not supplied, the latest version of the context is returned.

Examples

Retrieve XML schema that defines the validation rules for data structured according to version 1.0 of the ECB_EXR1 DSD maintained by the ECB

                  wget -O s.xsd --header 'authorization: Basic ZXV1c2VybmFtZTpwYXNzd29yZA==' https://sdw-wsrest.ecb.europa.eu/service/schema/datastructure/ECB/ECB_EXR1/1.0

Content negotiation

Using the HTTP content negotiation mechanism, you can select the representation to be returned and you can also instruct the service to compress the data to be returned.

Format selection

The following data formats are supported by the web service:

Data formats:
- SDMX-ML 2.1 Generic Data format: application/vnd.sdmx.genericdata+xml;version=2.1. This is the default for data queries.
- SDMX-ML 2.1 Structure Specific Data format: application/vnd.sdmx.structurespecificdata+xml;version=2.1
- SDMX-JSON: application/vnd.sdmx.data+json;version=1.0.0-wd
- CSV: text/csv
- CSV, optimised for pivot tables: application/vnd.ecb.data+csv;version=1.0.0
Metadata formats:
- SDMX-ML Structure format: application/vnd.sdmx.structure+xml;version=2.1

For additional information about the various SDMX-ML formats, please refer to the SDMX documentation.

Generic mime types (application/json, application/xml) are also supported but they will always point to the most recent version of the SDMX formats supported by these web services. That version will change in the future, whenever new versions of the various SDMX formats are made available.

Is it therefore highly recommended that implementers use one of the specific mime types above rather than a generic one, to avoid issues when new versions of the formats are released.

Output compression

You can also enable data compression using the Accept-Encoding HTTP header field. Compressed messages are typically significantly smaller than uncompressed messages, which can lead to improvements when transferring large amount data over the network.

Status codes

The web service returns the following HTTP status codes.

Code	Status	Description
200	OK	Your query could be successfully processed and the data have been returned.
304	No changes	No changes since the timestamp supplied in the `If-Modified-Since` header.
400	Syntax error	If there is a syntactic or semantic issue with the parameters you supplied, a 400 HTTP status code will be returned.
404	No results found	A 404 HTTP status code will be returned if there are no results matching the query.
406	Not Acceptable	If you ask for a resource representation that we don't support, a 406 HTTP status code will be returned. See the section about content negotiation, to view the supported representations.
500	Internal Server Error	When there is an issue on our side, a 500 HTTP status code will be returned. Feel free to try again later or to contact our support hotline.
501	Not implemented	This web service offers a subset of the functionality offered by the SDMX RESTful web service specification. When you use a feature that we have not yet implemented, a 501 HTTP status code will be returned.
503	Service unavailable	If our web service is temporarily unavailable, a 503 HTTP status code will be returned.

Tips & tricks

The SDMX Technical Working Group publishes a list of tips and tricks for web service clients, which is well worth reading.

The SDMX Technical Working Group has also published a cheatsheet which summarises, in 2 A4 pages, the main points of the SDMX 2.1 RESTful API.

If the documentation does not contain the information you require, or if you have any general comments or feedback regarding our web service, please contact us.

All sample queries in this tutorial can also be executed using command-line tools such as curl or wget:

wget -O data.xml \
        --header="Accept:application/vnd.sdmx.structurespecificdata+xml;version=2.1" \
        https://sdw-wsrest.ecb.europa.eu/service/data/EXR/M.NOK.EUR.SP00.A

curl -k -o data.xml \
        --header "Accept:application/vnd.sdmx.structurespecificdata+xml;version=2.1" \
        https://sdw-wsrest.ecb.europa.eu/service/data/EXR/M.NOK.EUR.SP00.A

Table of contents

Home

Overview

Concepts and codelists

Data Structure Definitions

Data

Data queries

In a nutshell

Syntax definition

Examples

Metadata queries

In a nutshell

Syntax definition

Examples

Schema queries

In a nutshell

Syntax definition

Examples

Content negotiation

Format selection

Output compression

Status codes

Tips & tricks