Introduction

Statistics API is dedicated to support online visualisation built on Eurostat data thanks to the JSON-stat Toolkit

Pre-requisite

It is strongly recommended to read through the introduction of the JSON-stat toolkit by its author

Short word about JSON-stat

JSON-stat.org describe the format that is a simple lightweight JSON dissemination format best suited for data visualisation, mobile apps or open data initiatives.

It is based on a cube model that arises from the evidence that the most common form of data dissemination is the tabular form.

In this cube model, datasets are organised in dimensions. Dimensions are organised in categories.

The particularity of this format is that it intend to provide ready-to-use content for visualisations from a single API call

JSON-stat.com describe the toolkit(s) to take full advantages of the JSON-stat format.

For further usage details of the toolkit, please consult the or the README of the jsonstat-toolkit

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
{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

Retrieving your first content

Usage of API statistics starts when a dataset is selected for data retrieval, knowing the dataset online data code, that can be easily found.

In case the language of the response should be other than English (default language), a specific Query parameter should be added to the URL

https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DATASET_CODE?lang=EN

DATASET_CODE in the URL above is a placeholder to be replaced with the dataset code of choice, for example :

https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DEMO_R_D3DENS?lang=EN

Finding the online data code

In Eurostat website navigation tree

The online data code is always next to the dataset title in between parentheses.

In Databrowser navigation tree

The online data code is present below the dataset title in between square brackets.

In Databrowser dataset view

The online data code is present in the information panel about the dataset

The online data code is present in the title section of the visualisations panel

Thus on this example, the JSON-stat data for this DEMO_R_D3DENS dataset can be retrieved via the URL

https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DEMO_R_D3DENS?lang=EN

Understanding response metadata

Dataset metadata

The first elements of the JSON-stat response are the metadata indicating the type of JSON-stat response, the title of the dataset its source and its last update data.

   "version":"2.0",
   "class":"dataset",
   "label":"Population density by NUTS 3 region",
   "source":"ESTAT",
   "updated":"2023-04-19T11:00:00+0200",

Dimension metadata : id and size

Then the dimensional structure of the dataset is summarized in two arrays indicating the code and size of each dimension used by the dataset.

We can observe that the GEO dimension is quite large (2031 positions) as this dataset is a Eurostat regional datasets, meaning that it contains statistical data for countries and their subdivision in statistical regions also called NUTS regison (see more information on NUTS classification)

"id":[
      "freq",
      "unit",
      "geo",
      "time"
   ],
   "size":[
      1,
      1,
      2031,
      33
   ],

Dimension metadata : index and label

The dimension object in the response contains for each dimension code an object with its title and for each position (called category in JSON-stat) a list of code and their corresponding order and label.

"dimension":{
      "freq":{
         "label":"Time frequency",
         "category":{
            "index":{
               "A":0
            },
            "label":{
               "A":"Annual"
            }
         }
      },
     [...]

Preview this data on JSON-stat Explorer ( this can take up to one minute to preview the content as the JSON-stat is large, please see below for ways to filter the data)

Filter data

Filtering on geoLevel

As the above dataset have more than 2000 positions for the GEO dimension and is a regional dataset, it is interesting to make use of the special filter geoLevel to help retireving content for a specific NUTS level

Following table list the filter value and example for DEMO_R_D3DENS dataset.

Value	Description
aggregate	European aggregates based on a white list - EU15, EU25, EU27_2007, EU27_2019, EU28, EA19, etc. https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DEMO_R_D3DENS?lang=EN&geoLevel=aggregate
country	country code (EU Member States, or EFTA, or Candidate Countries or other countries) https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DEMO_R_D3DENS?lang=EN&geoLevel=country
nuts1	NUTS code level 1: major socio-economic regions https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DEMO_R_D3DENS?lang=EN&geoLevel=nuts1
nuts2	NUTS code level 2: basic regions for the application of regional policies https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DEMO_R_D3DENS?lang=EN&geoLevel=nuts2
nuts3	NUTS code level 3: small regions for specific diagnoses https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DEMO_R_D3DENS?lang=EN&geoLevel=nuts3

Filtering on Time

It is possible to restrict the response to a specific time value or time value range.

Value	Description
time=YYYY or time_period=YYYY	Filter on a specific time value (ie. time=2020) https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DEMO_R_D3DENS?lang=EN&geoLevel=country&time=2020
sinceTimePeriod=YYYY	Filter on all time values since the specified value included (i.e sinceTimePeriod=2020 means "all time values since 2020, 2020 included") https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DEMO_R_D3DENS?lang=EN&geoLevel=country&sinceTimePeriod=2020
untilTimePeriod=YYYY	Filter on all time values until the specified value included (i.e untilTimePeriod=2010 means "all time values until 2000, 2000 included") https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DEMO_R_D3DENS?lang=EN&geoLevel=country&untilTimePeriod=2000
sinceTimePeriod=YYYY AND untilTimePeriod=YYYY	Both filter above can be combined to define a FROM-TO range (i.e sinceTimePeriod=2010&untilTimePeriod=2020 means "all time values from 2010 to 2020, included") https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DEMO_R_D3DENS?lang=EN&geoLevel=country&sinceTimePeriod=2010&untilTimePeriod=2020
lastTimePeriod=N	This fitler allows to always retrieve the N latest positions for TIME dimension (i.e lastTimePeriod=1 means 'most recent data" or lastTimePeriod=3 means "last 3 positions") https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DEMO_R_D3DENS?lang=EN&geoLevel=country&lastTimePeriod=3

Filtering on other dimensions

Any dimension present in the data product can be used as filter parameter with the syntax &dimension_code=position_code.

For example to retrieve only EU27 data for 2022 from example dataset, the following query should be used

https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/DEMO_R_D3DENS?lang=EN&geo=EU27_2020&time=2022

Need help in building your API query

From Eurostat query builder

Eurostat continue to provide a Query Builder on its website.

From Databrowser

The advanced menu for download in DataBrowser is providing a query based on the currently visualized data if you open the menu via Download > Options and other formats and then select the following options as shown in below screenshot


File format	JSON-stat (.json)
Data scope	Data on this page only
Endpoint	JSON

From JSON-stat

JSON-stat community is maintaining a showcase on Eurostat data that could also be used as a query builder or a data previewer

From detailed documentation

Please consult the detailed documentation for further details.

Expand all Collapse all

Child pages

API - Getting started with statistics API