Introduction
Statistics API is dedicated to support online visualisation built on Eurostat data thanks to the JSON-stat Toolkit
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 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 parametersThe structure of the REST request
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 :
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.