Discover official datasets
discoverFind what official data is available about a topic.
Use this to explore what datasets exist. It returns catalogue metadata,
never observations — and neither do ask and build_url, which
prepare an exact source request that still has to be downloaded and
queried (fetch / stage_url when the client cannot do that itself).
Two response shapes, and shape says which one arrived.
ranked—resultslists matching datasets, best first, each with its dimensions, coverage, and thematchesthat justify it.anchored—topicnamed one concrete code (a place, a country, an indicator) and nothing forced the ranked path. The answer is thenanchor(the code chosen, and what else the topic could have meant),facets(what varies across the datasets publishing it) andanchored_datasets(those datasets, paged bypage.next_offset).resultsis[]on this shape by construction — that is not "nothing found". If the chosen code is wrong, re-query with one ofanchor.alternatives[].name.
The two shapes never both appear. Anything that scopes the search is served
by the ranked path: agencies, region, user_country,
keywords, a non-English language, or an offset past the
anchored page. A code also stays ranked when fewer than max(15, limit)
datasets publish it (it or a code beneath it), and when resolving it or
counting its datasets fails or does not finish in time — that last case,
and only it, carries a retrieval_degraded warning with level
anchor_unavailable; a retry may then anchor.
Anchored rows are datasets that publish the code or one beneath it — never ones merely permitted to carry it, never ones carrying only its parent.
Two keys explain the rest of the response: _k expands the abbreviated
row keys, and _notes explains whatever this particular response
happens to contain, keyed by field or field=value.
Common workflow: discover -> inspect -> ask
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows to return, default 15. The anchored shape needs a family of at least max(15, limit), so a large limit makes the ranked shape more likely. | |
| topic | Yes | What the data is about, in natural language. Naming one concrete code — a country, a city, an indicator — returns the anchored shape when at least max(15, limit) datasets publish it; a retrieval_degraded/anchor_unavailable warning marks a ranked answer whose anchoring failed or timed out. | |
| offset | No | Row offset; pass `page.next_offset` from the previous response. An offset past the anchored page forces the ranked shape. | |
| region | No | Geography the user is asking about; affects coverage ranking, never the agency filter. Forces the ranked shape. | |
| agencies | No | Restrict to these publisher codes (e.g. ["ABS", "OECD"]). Use only when the user names a publisher outright — it hides international sources reporting on a country. For a country use `region`. Forces the ranked shape. | |
| keywords | No | Override the auto-extracted graph-search terms. Rarely needed. Forces the ranked shape. | |
| language | No | ISO search language, default "en". Anything else forces the ranked shape — the anchor name index is English only. | en |
| user_country | No | The country the USER is in. Pass only when the user has stated where they are; never infer it from the question. This is not the country the question is about — that is `region`. Used to prefer data covering the user's country when the question names no geography of its own. Forces the ranked shape. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| _k | Yes | Expands the abbreviated row keys. | |
| page | Yes | ||
| shape | Yes | ranked: the answer is in `results`. anchored: the answer is in anchor + facets + anchored_datasets, and `results` is [] by construction. Read this first. | |
| _notes | No | How to read what this particular response contains, keyed by field or `field=value`. Only conditions that fired are here, so an absent key means the case did not arise. | |
| anchor | No | What the response is anchored on, and what else the query could have meant. | |
| facets | No | What varies across the datasets publishing the anchor code. | |
| results | Yes | Ranked datasets, best first. Always [] on the anchored shape — that is not "nothing found"; the answer is in anchor/facets/anchored_datasets. | |
| warnings | No | ||
| other_agencies | No | Bounded context from sources outside the `agencies` filter. Never displaces a results row. | |
| anchored_datasets | No | Datasets publishing the anchor code, paged by page.next_offset. Pass agency_id + dataflow_id to inspect or build_url. |