Child pages
  • API Statistics - data query

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.

This online help is outdated and will be deleted soon. Please consult our Data Browser user guide on the Eurostat website. Don’t forget to update any bookmarks you might have saved!