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:
The web service complies with the SDMX 2.1 RESTful web service specification.
Let's first start with a brief introduction of the SDMX information model.
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.
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).
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.
All the data stored in the Statistical Data Warehouse can be retrieved using the query string described below.
protocol://wsEntryPoint/resource/flowRef/key?parameterswhere parameters are defined as such:
startPeriod=value&endPeriod=value&updatedAfter=value&firstNObservations=value&lastNObservations=value&detail=value&includeHistory=value
https
as of 28 January 2021. http calls made via a browser will be automatically redirected to https
.
https://sdw-wsrest.ecb.europa.eu/service/
data
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:
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:
D
),USD
),EUR
),SP00
) andA
).
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
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.
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).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).
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.
Using the detail
parameter, it is possible to specify the desired amount of information to be returned by the web service.
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.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
).
Using the dimensionAtObservation
parameter, you can define the way data should be organized in the returned message.
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.
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.
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.Using the format
parameter, you can instruct the web service to return data in different formats (see also Content negotiation tab).
csvdata
Comma-separated valuesjsondata
JSON structurespecificdata
SDMX-ML 2.1 Structure Specific data formatgenericdata
SDMX-ML 2.1 Generic DataPlease refer to the Useful tips section to see examples of these queries with command line tools such as curl
or wget
.
M.USD.EUR.SP00.A
for the EXR
dataflow
M.USD.EUR.SP00.A
for the EXR
dataflow
EXR
dataflow, matching the supplied series keys, using wildcarding for the second dimension
EXR
dataflow
All metadata can be retrieved using the query string described below.
protocol://wsEntryPoint/resource/agencyID/resourceID/version?detail=value&references=value
Learn about the SDMX standard and SDMX metadata.
https
as of 28 January 2021. http calls made via a browser will be automatically redirected to https
.
https://sdw-wsrest.ecb.europa.eu/service/
datastructure
, metadatastructure
, categoryscheme
, conceptscheme
, codelist
, hierarchicalcodelist
, organisationscheme
, agencyscheme
, dataproviderscheme
, dataconsumerscheme
, organisationunitscheme
, dataflow
, metadataflow
, reportingtaxonomy
, provisionagreement
, structureset
, process
, categorisation
, contentconstraint
, attachmentconstraint
and structure
.
Organisations defining metadata are known as agencies in SDMX. In order to retrieve an artefact, you should know the identifier of its maintainer.
The identifier
of the resource, such as CL_FREQ
for the frequency codelist maintained by the ECB.
The version
of the artefact to be returned. When the version number is not supplied, the latest version of the resource is returned.
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).
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.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).
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.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
.
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
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_EXR1You 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
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=dataflowYou 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
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=allstubsYou 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
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=allstubsAgain, 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
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
https
as of 28 January 2021. http calls made via a browser will be automatically redirected to https
.
https://sdw-wsrest.ecb.europa.eu/service/
schema
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 schemadataflow
: constraints attached to the dataflow, and to the DSD referenced by the dataflow, will be used in the schemaprovisionagreement
: 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 schemaThe identifier
of the maintainer of the context.
The identifier
of the context, such as EXR
for the dataflow about exchange rates maintained by the ECB.
The version
of the context to be returned. When the version number is not supplied, the latest version of the context is returned.
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
.
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
The following data formats are supported by the web service:
application/vnd.sdmx.genericdata+xml;version=2.1
. This is the default for data queries.application/vnd.sdmx.structurespecificdata+xml;version=2.1
application/vnd.sdmx.data+json;version=1.0.0-wd
text/csv
application/vnd.ecb.data+csv;version=1.0.0
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.
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.
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. |
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