get_sdmx_data
Fetch filtered time-series observations from Statistics Canada tables via SDMX REST. Specify dimensions, time periods, and observation limits to get only the data slice you need.
Instructions
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 a SPARSE SAMPLE for large dimensions — do NOT use wildcard for dimensions with >30 codes (e.g. NOC occupations, CMA geographies). Use explicit member IDs joined with '+' instead.
To get all leaf IDs for a large dimension as a ready-to-use OR string, call get_sdmx_key_for_dimension(productId, dimension_position) first.
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). NOTE: OR syntax (+) triggers a StatCan SDMX-JSON encoding bug (non-positional series keys). This is automatically corrected before rows are returned, so all OR-ed dimension labels should be present.
Output rows contain: dimension values, "period", "value", SCALAR_FACTOR, UOM, VECTOR_ID, STATUS, and other SDMX attributes.
Rows are returned inline, capped at MAX_SDMX_ROWS (500). For larger result sets, narrow the key or use startPeriod/endPeriod/lastNObservations.
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). |