Eurostat Online Help for Data Browser
Child pages
  • API - Detailed guidelines - API Statistics

Versions Compared

Old Version 2

changes.mady.by.user Philippe Weber

Saved on

compared with

New Version Current

changes.mady.by.user Philippe Weber

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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 Serviceweb service:

  • provides data in JSON-stat 2.0 format;

  • supports only REpresentation State Transfer (REST) protocol;

  • delivers responses in English, French or German.

...

Excerpt

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


Dynamic part


{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 structure of a filter parameter : <DIMENSIONis DIMENSION_CODE>CODE=<VALUE>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 corresponds 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.

  • if several VALUE are required for a dimension several filter must be used DIMENSION_CODE=VALUE_1&DIMENSION_CODE=VALUE_2

The Time parameter

Both "time" and "time_period" parameters are accepted in the URL . Both to address the TIME_PERIOD dimension.

...

The geoLevel” parameter allows retrieving a list of "GEO" codes according to :

...

their level in the NUTS classification or if they are considered aggretates :

  • geoLevel=aggregate : European aggregates based on a white list - EU15, EU25, EU27_2007, EU27_2019, EU28, EA19, etc.
  • The list of codes stored in the constraint has to be filtered to include only the aggregates (EFTA, BLUE, EU*, EA*...)
  • See the "notGeoElement.regexp" regular expression above.
  • BREXIT (if this actually occurs) codes have to be taken into consideration when BREXIT is applied.

    • geoLevel=country : any country code (EU Member States, or EFTA, or Candidate Countries or other countries) - any 2 digits - i.e. FR

    • The list of codes stored in the constraint has to be filtered to remove the aggregates and other codes not related to NUTS (EFTA, BLUE, EU*, EA*...)
    • See the "notGeoElement.regexp" regular expression above.
    • BREXIT (if it actually occurs) codes have to be taken into consideration when BREXIT is applied.
  • geoLevel=nuts1: NUTS code level 1: major socio-economic regions - any 3 digits - i.e. FR4

  • geoLevel=nuts2: NUTS code level 2: basic regions for the application of regional policies -

    any

    4 digits - i.e. FR41

  • geoLevel=nuts3: NUTS code level 3: small regions for specific diagnoses -

    any

    5 digits - i.e. FR413

  • geoLevel= city: code at city level - any 7 digits - i.e. DE_DEL1 (Karlsruhe)

...


Warning

The "geo" dimension parameter filter and the "geoLevel" parameter are mutually exclusive.

A request must not contain both at the same time. If such a query is sent, the Statistics endpoint should return an error without trying to provide any data:

{"error":{"status":"400","label":"'geo' parameter and 'geoLevel' parameter cannot be set at the same time. Please choose one or the other."}}

...

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 web service should return this error code when none of the other error codes better describes describe 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 returned immediately or asynchronously.

In case of an asynchronous response, API will return the following JSON response:

...