Use when you need to find which datasets exist, which exist for one area, or the figures and history
for one area and dataset (or a council planning view). For what a metric means use `explain_metric`;
for how areas rank use `compare`.
Three modes, depending on which of `area_id`/`dataset` are given (plus a planning mode, `council`, described last) --
consolidates what were three separate tools (list_datasets,
list_area_datasets, get_dataset_for_area) behind one, since they are all
really "how do I get data" at different levels of specificity:
1. Neither `area_id` nor `dataset`: lists every dataset (stat) StatsMapped
tracks for one country ('ireland' or 'united-kingdom'), with its key,
human label, and which geography levels it can be shown at. Ireland and
the UK track genuinely different datasets -- call this first for the
right country before assuming a stat_key exists there, to find the
right `stat_key` for `compare`'s ranking mode.
2. `area_id` given, `dataset` omitted: lists every dataset available for
that one area (e.g. "county:kerry" for Ireland, "uk:lad:e09000033" for
the UK), with its latest figure, year-on-year change, and caveat labels
only (not full caveat text -- use mode 3 for the full detail on any one
dataset that matters). Pass `stat_key` (from mode 1) to list only that
stat's series for the area: a full listing is tens of KB, one stat is a
few hundred bytes. `area_id` comes from `list_areas`; `country`
must match whichever country that call used, or this simply 404s
("unknown geography").
3. Both `area_id` and `dataset` given: full detail for one dataset in one
area -- the latest figure, a written summary, full caveat text, and (if
`history_months` is set) recent history. `dataset` is a `series_key`
from mode 2's own response. `history_months` means actual months of
history (0 = everything) -- e.g. 24 returns 2 years of an annual
series, not 24 years. `country` must match `area_id`'s own country. A stat key from mode 1 is also
accepted as `dataset` when the area has exactly one series for it (the reply says `resolved_from_stat_key`);
with several, the error names the series keys to use.
4. `council` alone (an Irish council slug, e.g. "cork-city-council"; country "ireland" only; no other argument): that council's planning
applications by year received -- count, grant and refusal share of decided applications, median days to a decision -- with source, licence,
the last data date, a receipt, plain notes, and typed `absences` instead of zeros. A council the national planning feed has stopped carrying
(for example Cork City, last record 2025-11-04) says `status: "stopped_reporting"`: a low recent figure is a feed gap, not fewer applications.
Example: query_data(council="cork-city-council").
`dataset` and `history_months` are only meaningful together with
`area_id` (and, for `history_months`, `dataset` too, since it only
applies to mode 3); giving either without its real precondition
raises rather than silently dropping the argument and dispatching to
the wrong mode.
