API - Introduction (en)

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 Competition, further referred to as DG COMP

  • 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.

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:

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:

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.