Basics
All the data stored in the ECB Data Portal can be retrieved using the query string 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
|
As of 28 January 2021 the web service is only available over https. http calls made via a browser will be automatically redirected to https.
|
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 three 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 three elements, they are 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 Data Portal, a metadata query for all Dataflows can be performed: https://data-api.ecb.europa.eu/service/Dataflow
|
resource (Defining the Dimension values)
|
As explained in the Overview section, the combination of Dimensions allows statistical data to be uniquely identified. In SDMX, such a combination is known as a Series key, and this is what needs to be input for the key parameter.
For example, let’s say that exchange rates can be uniquely identified by the following:
-
the frequency at which they are measured (e.g. daily – code D);
-
the currency being measured (e.g. US dollar – code USD);
-
the currency against which the above currency is being measured (e.g. euro – code EUR);
-
the type of exchange rates (e.g. foreign exchange reference rates – code SP00);
-
the Time series variation (e.g. average or standardised measure for a given frequency – code A).
To build the Series key, take the value for each of the Dimensions (following the order in which the Dimensions are defined in the DSD) and join them with a dot (.). The Series key for the example above would therefore be: 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 (+) sign. 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 (code JPY): D.USD+JPY.EUR.SP00.A
You can combine wildcarding and the OR operator. For example, the following key can be used to retrieve daily or monthly exchange rates (codes D for daily and M for monthly) 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 are to 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 ISO 8601 timestamp for the updatedAfter parameter, it is possible to retrieve the latest version of changed values in the database after a certain point in time (i.e. 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 Data Portal 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 that were made in the database after you last performed the same query.
Should you not be able to handle updates and revisions, or if you would prefer to perform a full refresh of your local database when something has changed, you can use an If-Modified-Since header as an alternative to the updatedAfter parameter described above. This triggers a 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.
|
detail (Defining the amount of detail included)
|
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 (Time 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 Time series will be returned, excluding the Attributes and the Observations. This can be used to list Time series that match a certain query without returning the actual data.
-
nodata: the Time series will be returned, including the Attributes, but the Observations will not.
|
firstNObservations & lastNObservations (Defining 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 Time series, starting from the first Observation (firstNObservations) or counting back from the most recent Observation (lastNObservations).
|
includeHistory (Retrieving historical data)
|
Using the includeHistory parameter, you can instruct the web service to return previous versions of the matching data. This allows you to see how the data have evolved over time (i.e. see when new data were released, revised or deleted). Possible options are:
|
format (Retrieving data in different formats)
|
Using the format parameter, you can instruct the web service to return data in different formats (see also the content negotiation tab). Possible options are:
-
csvdata: comma-separated values
-
jsondata: JSON
-
structurespecificdata: SDMX-ML 2.1 Structure Specific Data format
-
genericdata: SDMX-ML 2.1 Generic Data
|
Examples
Please refer to the Useful tips section to see examples of these queries with command line tools such as curl or wget.
