API Statistics is a web service for data query where parameters don’t have to respect a specific order opposed to API SDMX 2.1.
This Web Service:
provides data in JSON-stat 2.0 format;
supports only REpresentation State Transfer (REST) protocol;
delivers responses in English, French or German.
The structure of the REST request
The structure to build the REST request is a URL: {host_url}/{service}/{version}/{response_type}/{datasetCode}?{format}&{lang}&{filters}
URL part | Example | Comment |
|---|---|---|
Fixed part | ||
{host_url}/ | https://ec.europa.eu/eurostat/api/dissemination/ https://ec.europa.eu/eurostat/api/comext/dissemination (Comext and Prodcom datasets) | Fixed part of the request related to our website |
{service}/ | statistics/ | Fixed part of the request related to the service |
{version}/ | 1.0/ | Fixed part of the request related to the version of the service |
Dynamic part | ||
{response_type}/ | data/ | Only statistical data are currently returned |
{datasetCode} | nama_10_gdp | Unique code identifier of the queried data product (either a dataset or a predefined extraction) |
?{format} | ?format=JSON | Optional parameter |
&{lang} | &lang=EN | Optional parameter |
&{filters} | &time=2019 | Optional parameters |
The parameters defined in the REST request
The Filter parameters
The Filter parameters defined in the URL are optional. Any dimension present in the data product can be used as filter parameter.
Filters start after the question mark ("?") in the URL. They are separated by an ampersand ("&") if there are several filters.
The structure of a filter parameter: <DIMENSION_CODE>=<VALUE>
DIMENSION_CODE: the code of the dimension used to filter data
the dimension code must be present in the data product
it is not necessary that the order of the filters correspond to the order of the dimensions in the data product
VALUE: value of the filter is the position in the dimension i.e.
time=2019
geo=FR
DIMENSION_CODE and VALUE are case-insensitive; they can be written in lower or uppercase in the URL request.
The Time parameter
Both "time" and "time_period" parameters are accepted in the URL. Both address the TIME_PERIOD dimension.
Below are other Time parameters that can be used:
untilTimePeriod – the specific TIME_PERIOD value to filter the returned file until this value
sinceTimePeriod – the specific TIME_PERIOD value to filter the returned file since this value
lastTimePeriod – a numeric value counting down until the TIME_PERIOD dimension values are included in the returned file
Using more than one Time parameter in the same query is not accepted.
The only exception is using both sinceTimePeriod and untilTimePeriod. This will return the filtered file based on the specific values for the two Time parameters.
The Format and Language parameters
The “format” parameter’s only possible value is "JSON".
The Language parameter (“lang”) can have only three values: “EN”, “FR”, and “DE”. In case the parameter isn’t specified, the default value “EN” is taken.
Error messages returned in case of invalid queries
Fault Code | HTTP Status | Description |
|---|---|---|
Client Errors | ||
100 No results found | 400 Bad request | The result from the query is empty. |
100 No results found | 404 Not Found | The requested resource is not available. |
140 Syntax error | 400 Bad request | The query is invalid. |
150 Semantic error | 400 Bad request | The request is syntactically correct but fails a semantic validation, business rules. |
Server errors | ||
500 Internal Server error | 500 Internal server error | The webservice should return this error code when none of the other error codes better describes the reason for the failure of the service to provide a meaningful response. Also used in case of request not respecting the xsd definition. |
Asynchronous response in case of big extractions
When receiving a request, API can determine if the response can be made synchronously or asynchronously.
In case of an asynchronous response, API will return the following JSON response:
{"warning":{"status":413, "label":"ASYNCHRONOUS_RESPONSE. Your request will be treated asynchronously. Please try again later."}}
API Statistics will not notify the user when the file is ready, the request must be made again to check its status.