get_sdmx_data
Fetch filtered time-series observations from a StatCan table via SDMX REST.
Filtering is done server-side — only the requested slice is returned. Call get_sdmx_structure first to see dimension positions and valid codes.
Key syntax (dot-separated codes in dimension position order): "1.2.1" = Geography=1 (Canada), Gender=2 (Men+), Age=1 (All ages) ".2.1" = all geographies, Gender=2, Age=1 (wildcard — preferred for multi-geo) "1+2.2.1" = Geography 1 or 2, Gender=2, Age=1 (OR)
IMPORTANT — key position codes:
Use member IDs from get_cube_metadata(), NOT SDMX codelist positions from get_sdmx_structure(). Member IDs and SDMX codelist codes are the same numbers.
Wildcard (omit a position) returns EVERY member of that dimension, including totals and parent aggregates — on large dimensions (e.g. 309 NOC occupations) that can exceed the 500-row cap here; use query_sdmx or fetch_sdmx_to_database instead.
To sum or rank across a hierarchy without double-counting totals, use leaf codes: get_sdmx_key_for_dimension(productId, dimension_position) returns them as an OR key.
Time filtering (use one or the other, not both): lastNObservations=12 → last 12 periods (e.g. 1 year of monthly data) startPeriod="2020" → from 2020 onwards (annual); "2020-01" for monthly endPeriod="2023-12" → up to Dec 2023
LIMITATION: StatCan rejects combining lastNObservations with startPeriod/endPeriod (returns 406).
Output is grouped by series: each entry in "series" holds the fields that are constant for that series once (dimension labels, _series_key, VECTOR_ID, UOM, SCALAR_FACTOR, ...) plus "observations" as [period, value] pairs with numeric values (null = suppressed). A third element {field: label} appears only on observations with their own attributes (e.g. a STATUS flag).
Observations are capped at MAX_SDMX_ROWS (500). For larger result sets, narrow the key or use startPeriod/endPeriod/lastNObservations.
Growth, percent change, averages, ranking or comparisons? Use query_sdmx instead of computing by hand from these values. Fetch each series and period range once: do not re-fetch periods you already have from get_sdmx_vector_data.
IMPORTANT: In your final response to the user, you MUST cite the source of your data. This means including the _sdmx_url, table information and productId/key in your response.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Dot-separated dimension codes in position order (e.g. '1.2.1'). Use '+' for OR ('1+2.2.1' = Geography 1 or 2). Omit a value for wildcard ('.2.1' = all geographies, Gender=2, Age=1). Code numbers match WDS memberIds — no translation needed. Call get_sdmx_structure first to see dimension positions and valid codes. | |
| endPeriod | No | End period in YYYY or YYYY-MM format. | |
| productId | Yes | ||
| startPeriod | No | Start period in YYYY or YYYY-MM format. | |
| lastNObservations | No | Return only the last N observations per series (e.g. 12 for one year of monthly data). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| series | Yes | Observations grouped by series. | |
| _message | No | Truncation guidance, when truncated. | |
| _sdmx_url | Yes | SDMX request URL — cite as the data source. | |
| row_count | Yes | Total observations returned by StatCan (before truncation). | |
| _truncated | Yes | True if observations were capped at 500. | |
| series_count | Yes | Number of series in `series`. |