Imf Query Dataset
imf_query_dataset
Query an IMF SDMX dataflow by dimension key over a time range. Returns observations with time_period, value, and status, plus the unit, scale, and decimals of each series — a key resolving to several series carries one entry per series in series_metadata, since unit and scale differ between them. An index series also carries the reference_period it is based on (e.g. 2010A, 2010=100) exactly as published, on the series and, where the dataflow publishes one per observation, on each observation. Requires imf_get_database first to obtain the correct key_format and valid dimension codes. Country codes are ISO 3-letter (USA, GBR, DEU — not US, GB, DE). Key format: dot-separated codes in DSD keyPosition order (e.g. USA.NGDP_RPCH.A for WEO). Every position must carry a code: use + to combine codes (e.g. USA+GBR.NGDP_RPCH.A) and * to match every code at a position (e.g. *.NGDP_RPCH.A for all countries); * stands alone and cannot join a + list. Codes are matched case-insensitively and checked against each dimension's codelist before the query — an unknown code is rejected with the nearest valid codes. Codelists from imf_get_database enumerate the code universe, not actual coverage — valid codes can still return no_data if the combination has no series. When a + key returns data for some requested series and none for others, missing_series names each empty one with the reason a query for it alone gives (no_data or no_data_in_range). When the extra request that recovers the unit, scale, or decimals a + key suppresses fails, unresolved_attributes names them and how to get them. start_period and end_period must be valid period strings (YYYY, YYYY-SN, YYYY-QN, YYYY-MM, or a calendar-valid YYYY-MM-DD) with start_period no later than end_period; malformed or reversed ranges are rejected. A bound covers the whole period it names, so end_period 2023 includes 2023-M12 and 2023-Q4. last_n_observations keeps each series' last N observations — 1 is each series' latest value, the cheap way to ask many countries for their latest figure. Values are in base units everywhere, staged canvas rows included: scale is the power of ten the IMF publishes a series in (value / 10^scale is the published figure), never a factor still to apply. An inline response is held to 100,000 serialized characters. With DataCanvas enabled (CANVAS_PROVIDER_TYPE=duckdb), a larger result (multi-country, long time range) spills to it and returns a preview, the attributes of its first 20 series and at most 100 observations: call imf_dataframe_describe first to inspect staged tables and columns, then imf_dataframe_query for SQL analysis. Without DataCanvas, or with it at its canvas cap when an auto-mode call omits canvas_id, a larger result returns its earliest observations with truncated=true, and retrieval_guidance names the last period returned and how to narrow the query.
Schema valid · SHA-256 0bcfb4c42ba4…
View input schema
{
"type": "object",
"properties": {
"dataflow_id": {
"type": "string",
"description": "Dataflow identifier from imf_list_databases, e.g. WEO, BOP, CPI. Matched case-insensitively; the response echoes the catalog spelling."
},
"agency_id": {
"description": "Agency ID, e.g. IMF.RES or IMF.STA, matched case-insensitively. Auto-detected from dataflow list when omitted.",
"type": "string"
},
"version": {
"description": "Dataflow version, e.g. 9.0.0. Auto-detected from dataflow list when omitted.",
"type": "string"
},
"key": {
"type": "string",
"description": "Dot-separated dimension codes in DSD keyPosition order. Call imf_get_database to get key_format and valid codes first. Use + to combine codes at one position (e.g. USA+GBR.NGDP_RPCH.A). Use * to match every code at a position — *.NGDP_RPCH.A returns the indicator for all countries, and CAN.*.A every indicator for Canada. Every position needs a code or a *; an empty segment (USA..A) is rejected. A * stands alone at its position — combined with other codes (USA+*) it is rejected. Codes are trimmed and matched case-insensitively (usa resolves to USA), empty and repeated + members are dropped (USA++GBR+USA is queried as USA+GBR, and notice says so), and the response echoes the canonical key. A code missing from its dimension's codelist is rejected before the query, naming the nearest valid codes. The portal limits the request URL, so a + list of a few hundred codes is rejected as too long — use * there, or split the codes across calls. Country codes are ISO 3-letter: USA not US, GBR not GB, DEU not DE."
},
"start_period": {
"description": "Start of time range (inclusive). Accepts any of YYYY (annual), YYYY-SN (semi-annual, e.g. 2023-S1), YYYY-QN (quarterly, e.g. 2023-Q1), YYYY-MM (monthly), or a calendar-valid YYYY-MM-DD (daily), whatever the dataflow's frequency. The bound covers the whole period it names, so start_period 2023 admits 2023-M01 and 2023-Q1. Observations before this period are excluded from the result.",
"type": "string"
},
"end_period": {
"description": "End of time range (inclusive). Same formats as start_period, and must not be earlier than it. The bound covers the whole period it names, so end_period 2023 admits 2023-M12 and 2023-Q4. Observations after this period are excluded from the result.",
"type": "string"
},
"last_n_observations": {
"description": "Keep only each series' last N observations, an integer from 1 to 1,000,000; 1 returns each series' latest value. Latest is per series: series end at different periods, and a WEO series ends in its projection years (e.g. 2031), so set end_period to stop at a past year. With start_period or end_period, the last N inside that range. A series with fewer than N observations is returned whole. Omit to return every observation.",
"type": "integer",
"minimum": 1,
"maximum": 1000000
},
"canvas_id": {
"description": "Existing canvas ID to accumulate results into across multiple queries. This selects the destination only; it does not force staging. Use output_mode=\"canvas\" to stage an under-budget result. A canvas_id that has expired fails as canvas_not_found once the result is staged: omit it to stage onto a fresh canvas. At the canvas cap only a canvas_id you hold can stage; omitted there, auto mode returns the result inline and output_mode=\"canvas\" fails as canvas_capacity_exhausted.",
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$"
},
"output_mode": {
"description": "Result placement. auto returns an under-budget result inline and spills only when needed. canvas explicitly stages the full result, using canvas_id when supplied or allocating a fresh canvas.",
"default": "auto",
"type": "string",
"enum": [
"auto",
"canvas"
]
}
},
"required": [
"dataflow_id",
"key"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}