This API is a free of charge programmatic access to statistical metadata and data. This is the interface to use for the automation of metadata and data queries or downloads.
For background information purposes, it may be relevant to consult as well how to perform manual data and metadata downloads through the web based interface.
How are the pages of this API online help structured?
The API online help consists of the following parts:
This introductory page contains mainly basic information about the semantic formats of data and metadata responses. This is particularly relevant for obtaining additional information about SDMX and JSON-stat.
Getting started, the next page, provides a brief overview about the different endpoints supported in the API. It is strongly recommended to read this page, before proceeding to the next pages.
Data discovery provides insights about how to get catalogues and lists of metadata and data.
Metadata query and Data query focus on the basic API calls to request metadata and datasets.
Metadata filtering and Data filtering provide information about more advanced features to request metadata and datasets.
A Frequently asked questions section.
Which organizations expose this API?
This API is exposed by
Eurostat, the statistical office of the European Union
Directorates General of the European Commission:
The Directorate General for Employment, Social Affairs and inclusion, further referred to as DG EMPL
The Directorate General for Internal Market, Industry, Entrepreneurship and SMEs, further referred to as DG GROW
Supported protocol
This API is available using the HTTPS protocol.
Support for SOAP and REST
Depending on the type of operations, the API supports Representation State Transfer (REST) and/or Simple Object Access Protocol (SOAP).
The WSDL for SOAP endpoints and WADL for REST endpoints are explained in Getting started.
Note | This online help describes REST operations, as those are primarily recommended for use. |
Parameter <api_base_uri> in all operations descriptions
This documentation mentions a parameter <api_base_uri> in the operation description for each REST request. This parameter is specific to each organization exposing the API.
The allowed values for parameter <api_base_uri> are:
Agency | <api_base_uri> value to be used |
|---|---|
Eurostat | https://ec.europa.eu/eurostat/api/dissemination https://ec.europa.eu/eurostat/api/comext/dissemination (Comext and Prodcom datasets) |
DG EMPL | https://webgate.ec.europa.eu/empl/redisstat/api/dissemination |
DG GROW | https://webgate.ec.europa.eu/grow/redisstat/api/dissemination |
API for Comext datasets
Important note: dedicated endpoints of the new API allow to download Comext and Prodcom datasets.
For these datasets, the <api_base_uri> is: https://ec.europa.eu/eurostat/api/comext/dissemination
In the URL above, "comext/" is added to differenciate this base URL from the main one: https://ec.europa.eu/eurostat/api/dissemination
Further note concerning Comext datasets: full datasets cannot be downloaded because of their size. They have to be filtered.
Parameter <agencyID> in all SDMX operations descriptions
This documentation mentions a parameter <agencyID> in the operation description for each SDMX REST request and some other data discovery requests. An agency is the organization or other expert body responsible for the operational maintenance of commonly used metadata artefacts.
The allowed values for parameter <agencyID> are:
Agency | <agency_id> value to be used |
|---|---|
Eurostat | ESTAT |
DG EMPL | EMPL |
DG GROW | GROW |
Supported semantic formats
The API provides responses in:
SDMX-ML, i.e. Statistical Data and Metadata Exchange (SDMX) messages as XML document
SDMX-CSV, i.e. Statistical Data and Metadata Exchange (SDMX) messages as SDMX-CSV document
JSON-stat, i.e. a simple lightweight JSON format for data dissemination
TSV (Tab-Separated Values) files that include a ‘tab delimited’ sequence of values in each line
Statistical Data and Metadata Exchange (SDMX)
The Statistical Data and Metadata Exchange (SDMX) initiative is sponsored by a wide range of public institutions, including Eurostat. This standard describes and universalizes the way to exchange statistical data, and provides standard formats for data and metadata, content guidelines as well as IT architecture for exchange of data and metadata.
The vast majority of operations in this API implement the SDMX Guidelines for the use of Web Services.
Below are some terms that are used in SDMX and their definitions:
Dataset: a collection of related observations, organized according to a predefined structure
Data Structure Definition (DSD): metadata describing the structure and organization of a dataset, the statistical concepts and attached to them code lists used within the dataset
Dimensions: concepts that determine the dataset’s "physical" structure
Codelist: a code list is a predefined list from which some statistical coded concepts take their values. Each code list has the following properties:
identifier (it provides a unique identification within the set of code lists specified by a structural definitions maintenance agency);
name (also unique);
description (a description of the purpose of the code list); and
code value length (either an exact or a maximum number of characters and a type, i.e. numeric or alphanumeric).
Attributes: give additional information about the concepts used and do not affect the dataset structure itself
Dataflow: a structure which describes, categorizes and constrains the allowable content of a dataset that providers supply for different reference periods
Concept scheme: the descriptive information for an arrangement or division of concepts into groups based on characteristics, which the objects have in common. A concept scheme is a maintained list of concepts that are used in key family and metadata structure definitions (Definitions from EUROSTAT SDMX info space and OECD Glossary of statistical terms)
Check as well the formal definition of the SDMX information model, and a summary provided by Metadata Technology.
JSON-stat
JSON-stat 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 mixes:
SDMX data coming from Data Set like observations, status
SDMX metadata coming from structure, flow and constraint like dataset title, codelist label, …
Tab-separated values (TSV) file formats
When TSV is specified in the query parameters provided by the user, SDMX 2.1 metadata and data queries can return responses in the corresponding Tab-separated values (TSV) file format.
Does the API provide versioned information?
The API provides:
Following structural artefacts are versioned and final following SDMX specification: code lists, concept schemes and data structure definitions: each version of each item is available and can be downloaded via the API.
For statistical dataset, corresponding SDMX artefacts are non-final and always with version=1.0.
There is no history available on data.