Raw schema
{
"type": "object",
"properties": {
"dataset_code": {
"type": "string",
"minLength": 1,
"description": "Dataset code (e.g., \"nama_10_gdp\"). Required. A DS-* code — Comext detailed trade or PRODCOM, in any case — is served by the Comext host: filter freq on its trade flows, which mix annual and monthly series, and note that product, reporter and partner carry aggregates (TOTAL, EU27_2020) that double-count when summed with their members."
},
"filters": {
"default": {},
"description": "Dimension filters as a map of dimension code → array of valid values. Example: {\"unit\": [\"CP_MEUR\"], \"na_item\": [\"B1GQ\"], \"geo\": [\"DE\", \"FR\"]}. An empty array is treated as no filter for that dimension and is dropped from the request, and so is a blank or whitespace-only value ([\"\"] is no filter, [\"\", \"DE\"] is [\"DE\"]). No Eurostat code contains \"+\" or \".\": a value holding \"+\" is split into separate values, read as OR ([\"DE+FR\"] is [\"DE\", \"FR\"]), and a value holding \".\" stays one value that matches nothing. Dimension codes match in any case (\"GEO\" is geo). Keys are dimensions only: one naming a request control (lang, format, geoLevel, sinceTimePeriod, untilTimePeriod, lastTimePeriod, in any case) is rejected as invalid_dimension — use the lang, geo_level, since_period, until_period and last_n_periods inputs. Do not include \"geo\" here if using geo_level, nor \"time\"/\"time_period\" if using since_period, until_period or last_n_periods. A value that matches nothing contributes no rows rather than an error; the response names it in unmatchedValues, or in the no_results error when nothing matched at all. A valid value with no cell in the selected periods contributes no rows either; the response names it in emptyValues. eurostat_get_dimension_values lists the valid values.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"geo_level": {
"description": "Filter by NUTS hierarchy level. Mutually exclusive with a \"geo\" key in filters. Options: \"aggregate\" (EU/EA totals), \"country\" (member and candidate states), \"nuts1\" (major regions), \"nuts2\" (basic regions), \"nuts3\" (small regions). How many codes a level holds varies by dataset; a code of the level with no cell in the match is named in emptyValues.",
"type": "string",
"enum": [
"aggregate",
"country",
"nuts1",
"nuts2",
"nuts3"
]
},
"since_period": {
"description": "Start of the time range, inclusive. Accepted forms: YYYY, YYYY-MM, YYYY-MM-DD, YYYY-Qn (1–4), YYYY-Sn (1–2), YYYY-Tn (1–3), YYYY-Mnn (01–12), YYYY-Wnn (a week the year has, up to 53) or YYYY-Dnnn (a day the year has, up to 366) (e.g., \"2020\", \"2023-Q1\", \"2024-01\"). Extra leading zeros after the letter are dropped (\"2020-Q01\" is sent as \"2020-Q1\"), a day of the year is sent as three digits (\"2026-D1\" as \"2026-D001\"), and YYYY-A1 is sent as YYYY. Any form works on any dataset, read as a span of days, but Eurostat keeps only periods wholly inside the range, per frequency: \"2022-06\" on annual data excludes 2022, which starts before the bound, and a notice names that period when the response shows its frequency. A range whose first and last day are the same day is sent as that one date. A malformed or non-existent period (e.g., \"2020-13\") is rejected as invalid_period. Mutually exclusive with last_n_periods.",
"type": "string"
},
"until_period": {
"description": "End of the time range, inclusive (e.g., \"2024\"), in the same forms as since_period. Omit for data through the latest available period. A bound that falls inside a period excludes it here too: \"2023-06\" on annual data excludes 2023, which ends after the bound. The range must hold at least one day: a since_period that starts after until_period ends is rejected as invalid_period, and bounds of different frequencies are compared by day. Mutually exclusive with last_n_periods.",
"type": "string"
},
"last_n_periods": {
"description": "Return only the N most recent dataset time positions. Selected periods without populated cells for this slice are disclosed in a notice on successful queries, which advises a larger N only when every such period follows the slice's latest period with a cell. N counts back from the dataset's latest period, not from the latest period published for this slice, so a slice that lags can come back empty — increase N, or replace last_n_periods with a since_period/until_period range ending at a period the slice has published (until_period alone selects every period up to it). Mutually exclusive with since_period and until_period.",
"type": "number",
"minimum": 1,
"multipleOf": 1
},
"preview_limit": {
"default": 25,
"description": "How many matched observations to return inline, from the deterministic start of the JSON-stat cell order. Default 25; positive integers above 500 are clamped to 500 with a notice. This changes only the inline prefix: it does not reduce obsCount, missingObsCount, timeRange, the upstream response, or staged rows. Use filters or period controls to reduce the match itself.",
"type": "number",
"minimum": 1,
"multipleOf": 1
},
"stage": {
"default": false,
"description": "Stage every matched observation on a dataframe canvas, regardless of preview length or match size. Default false preserves automatic staging only above 5,000 observations. Ignored with an unavailable-staging notice on deployments without a canvas.",
"type": "boolean"
},
"lang": {
"default": "EN",
"description": "Language for labels in the response. Default is \"EN\". Options: \"EN\", \"FR\", \"DE\".",
"type": "string",
"enum": [
"EN",
"FR",
"DE"
]
},
"canvas_id": {
"description": "Reuse an existing dataframe canvas, so a result staged by this call lands beside earlier ones and can be joined against them. Pass the canvasId a previous eurostat_query_dataset or eurostat_download_dataset response returned; omit to start a fresh canvas. Used only when staging: stage=true or a match above 5,000 observations, on a canvas-enabled deployment.",
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$"
}
},
"required": [
"dataset_code"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}