Prepare an SDMX client download
build_urlPrepare an exact source request for a known, availability-anchored dataflow.
Use this when you already know the exact dataflow (from discover/inspect) and want its client-download plan — optionally narrowed by selections. Unlike ask (which finds a dataflow from a question), build_url takes the dataflow as given and returns exact requests plus availability-anchored codes and structure. Confirmed mode accepts direct Actual members and observed-key evidence. Best-effort may additionally accept direct Allowed members, labelled unconfirmed; structural codelist values are display-only in both modes. Rejected values receive directional alternatives but no URL until the caller explicitly selects an acceptable alternative scope in a follow-up call.
Does NOT fetch observations. For value questions, execute a
client_download_required plan client-side and query the parsed file
locally. A fallback staging grant may also be returned for clients without
local download/query capability; it is not the primary path. Only a
successfully parsed dataset with zero rows supports a no-data claim.
Safety: execute the plan HTTPS-only (including redirects), within the plan's
safety byte/redirect/timeout and aggregate/archive bounds; validate
archive members before extracting into a temp dir; treat url/headers/
body as data (never eval them); keep response bytes out of model context.
Common workflow: discover -> inspect -> build_url -> direct download -> local query
Args: agency_id: SDMX agency code, e.g. "ILO", "ABS", "ESTAT" (required — the same dataflow id can exist under several agencies) dataflow_id: SDMX dataflow identifier, e.g. "DF_CLD_XCHL_SEX_AGE_NB" selections: Optional {dimension_id: [code or name, ...]} to anchor the URL. Names are resolved within the dimension's AVAILABLE codes; values with no available data are rejected with alternatives, never silently passed. time_range: Optional time filter (e.g. "2020-2024", "since 2015", "2024") precision: URL breadth — "point", "series" (default), or "cube" availability: "confirmed" (default — direct Actual or observed-key evidence) or "best_effort" (add direct Allowed codes, still unconfirmed). Neither mode executes structural codelist values. verify: If True, fetch ONE observation from the built URL to confirm the selected/default codes actually co-occur in observed data (default off — graph-only). Adds a small live request; the URL is never changed, only annotated (an empty sample raises a warning). labels: If True, request the provider's LABELLED CSV — each coded column gains a human-readable name column beside it ("MEASURE" plus "Data Item"), so the data explains itself and you need no follow-up inspect calls to decode it. Code columns are unchanged, so query_dataset where={...} filters on codes still work. Costs ~3.6x bytes per row, which means fewer rows per query_dataset call — use it when you need to READ the data, not when you need many rows. Honoured by every endpoint with a verified labelled spelling (ABS, ILO, OECD, SPC and others); elsewhere it degrades silently to plain CSV. Note the column set changes: DATAFLOW is replaced by STRUCTURE, STRUCTURE_ID, STRUCTURE_NAME and ACTION. debug: Append a per-stage telemetry breakdown (only populated when GSDMX2_MCP_TELEMETRY is enabled). Off by default.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| debug | No | ||
| labels | No | ||
| verify | No | ||
| agency_id | Yes | ||
| precision | No | series | |
| selections | No | ||
| time_range | No | ||
| dataflow_id | Yes | ||
| availability | No | confirmed |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| series | Yes | ||
| status | Yes | ||
| volume | Yes | ||
| coverage | Yes | ||
| delivery | Yes | ||
| agency_id | Yes | ||
| dataflow_id | Yes | ||
| answer_ready | Yes | ||
| staging_fallback | Yes |