Eurostat

Eurostat

This connector reads the public dissemination APIs of Eurostat, the statistical office of the European Union (https://ec.europa.eu/eurostat/api/dissemination): about 8,000 datasets on the economy, prices, labour market, population, health, education, energy, environment, agriculture, transport and regions (NUTS 1 to 3), plus the detailed Comext trade and PRODCOM production databases. Everything is read-only.

Setup: nothing to configure. The APIs are free and need no account or key. Data is reusable under the Eurostat copyright notice (cite "Source: Eurostat" and the dataset code).

Finding a dataset

• The model has to know or guess the dataset code; there is no keyword search endpoint small enough to return here. Well known codes: nama_10_gdp (annual GDP and components), namq_10_gdp (quarterly GDP), nama_10_pc (GDP per capita), prc_hicp_manr (HICP inflation, annual rate, monthly), prc_hicp_midx (HICP index), une_rt_m (unemployment rate, monthly), une_rt_a (annual), lfsi_emp_a (employment rate), demo_pjan (population on 1 January), demo_gind (population change), tps00001 (population, short table), gov_10dd_edpt1 (government deficit and debt), ei_bssi_m_r2 (economic sentiment), sts_inpr_m (industrial production), sts_trtu_m (retail trade), nrg_bal_c (energy balances), nrg_pc_204 (household electricity prices), env_air_gge (greenhouse gas emissions), tour_occ_nim (tourism nights), ilc_li02 (at-risk-of-poverty rate), earn_nt_net (net earnings), irt_lt_mcby_m (long-term interest rates), ert_bil_eur_m (euro exchange rates), nama_10r_2gdp (regional GDP by NUTS 2), demo_r_pjangrp3 (regional population).
• Eurostat's Data Browser (https://ec.europa.eu/eurostat/databrowser) shows the code of every dataset in its URL and title; the user can look one up there.
• eurostat_list_recent_updates lists new, deleted and updated datasets of the last 7 days with their codes.
• eurostat_list_comext_datasets lists the Comext and PRODCOM datasets.

Workflow

1. eurostat_get_dataset_info: title, observation count, oldest and latest period (OBS_PERIOD_OVERALL_OLDEST / _LATEST), last update (UPDATE_DATA) and the methodology link (ESMS_HTML).
2. eurostat_get_dataset_codes: the dimensions in key order and the codes used in the dataset, with labels. Pick filter values here. eurostat_get_dataset_availability gives the same codes without labels plus the periods with data; eurostat_get_dataset_structure gives the dimension order, code list ids and attributes; eurostat_get_codelist returns a full code list with labels (GEO is large).
3. eurostat_get_data: values with filters. geo, time, unit and freq take lists; any other dimension goes in filters as dim=value&dim2=value (one value per dimension; dimension names in lower case as in step 2). Use lastTimePeriod 1 for the latest value or sinceTimePeriod/untilTimePeriod for a range; only these two time parameters can be combined. geoLevel (country, nuts2 ...) replaces geo.
4. eurostat_get_series: the same data by SDMX key, when a dimension other than geo, time, unit or freq needs several values (A.CP_MEUR.B1GQ+P3.DE+FR), with startPeriod, endPeriod and lastNObservations per series.
5. Trade and production: eurostat_list_comext_datasets, then eurostat_get_comext_data, e.g. DS-045409 with reporter DE, partner US, product 87 (HS chapter vehicles), flow 2 (exports), indicators VALUE_IN_EUROS, freq A, sinceTimePeriod 2022. In Comext lastTimePeriod counts empty future months too: prefer sinceTimePeriod.

Reading JSON-stat 2.0 (eurostat_get_data, eurostat_get_series, eurostat_get_comext_data)

• id lists the dimensions in order and size the number of codes returned per dimension. dimension.<id>.category.index maps each code to its position and .label gives its name.
• value is an object keyed by the flat index of the cell: index = sum over dimensions of position x (product of the sizes of the dimensions after it), row-major in the order of id (time is usually last). With one value per dimension except time, the key is simply the position of the period. Missing cells are absent from value.
• status holds flags for the same keys: p provisional, e estimated, b break in time series, c confidential, u low reliability, d definition differs, s Eurostat estimate, f forecast, n not significant, r revised, z not applicable, : not available.
• updated is the last data update. Units come from the unit dimension label: check it before comparing (million euro vs percent vs index). Periods: 2024, 2024-Q3, 2024-09, 2024-09-30; Eurostat publishes with a lag, so quote the latest period returned, not today.
• Labels come in English by default; set lang to FR or DE (fr, de for the SDMX tools).

Limits and errors

• Requests estimated above 500,000 cells are not answered at once and above 5,000,000 cells are refused (HTTP 413 "EXTRACTION_TOO_BIG"). A JSON answer with warning.status 413 "ASYNCHRONOUS_RESPONSE" means Eurostat is preparing the extract: narrow the filters or call again a little later. Filter by geo, unit and time to keep answers small.
• HTTP 400 with error[0].label names the problem, e.g. "Dimension "FOO" is not defined" (a filter for a dimension the dataset does not have), or geo and geoLevel sent together. HTTP 404 "is not available for dissemination" means an unknown or removed dataset code. An answer with an empty value means no data for that combination: check the codes with eurostat_get_dataset_availability.
• Codes are case-insensitive in the statistics API; dataset codes in the SDMX tools work in lower or upper case.

Out of scope: the bulk TSV/SDMX download files, the full table of contents (several megabytes) and the asynchronous extraction API are not part of this connector.