StatsMapped Public Data

Use when the question is how areas rank or compare on a stat, or whether two stats can be compared fairly. For one area's own figures use `query_data`. Four modes, depending on which arguments are given -- consolidates what were four separate tools (rank_areas, list_comparisons, get_comparison, check_comparability) behind one, since they are all really "how does this stat compare" at different scopes. Exactly one mode's arguments should be given; mixing arguments from different modes (e.g. both `stat_key` and `pair_key`, or only one of `stat_key_a`/`stat_key_b`) raises an error rather than silently guessing which mode was meant. 1. `stat_key` alone (no `pair_key`, no `stat_key_a`/`stat_key_b`): ranks every area at one geography level by its latest figure for that stat, for one country -- e.g. "which counties have the highest median sale price" (country="ireland"). `stat_key` comes from `query_data`'s dataset-listing mode, for the SAME country. `level` omitted uses this ranking's own default level; pass one of that dataset's own `compatible_levels` for a different one -- a level this ranking doesn't have registered returns an empty list rather than an error. Where the underlying stat has no honest per-area denominator (crime, homelessness, live_register and similar -- StatsMapped's own RANKING_NO_DENOMINATOR_STATS), each row's `rate_per_1000` is the real figure to rank/compare by, not `latest_value`, which is a raw count dominated by area population size. Always carry forward every entry in `caveats` when using a row in an answer. 2. `pair_key` alone: full detail for one registered comparison pair -- each axis's label, unit and publisher, the correlation stats (r, rho, and a leave-one-out sensitivity range naming the single most influential area), and caveats. `pair_key` comes from mode 4's own response, for the SAME country. 3. Both `stat_key_a` and `stat_key_b` given: does StatsMapped have a registered, hand-vetted comparison between these two stats? Registry- backed only -- never computes a fresh correlation for an arbitrary pair. Both stat_keys come from `query_data`'s dataset-listing mode, for the SAME country. `verdict` is one of `"SUPPORT"` (a real, hand-vetted registered pair with no open caveats -- may be treated as a confirmed relationship), `"QUALIFY"` (hand-vetted, but the evidence carries real caveats -- e.g. no robustness check for outliers, or an unverified geography-level join; read `uncertainty` and `reasons` before presenting it as confirmed), `"REJECT"` (a real structural impossibility or a human-vetted "no" -- the two stats share no geography level at all, or a reviewer rejected this exact pairing), or `"INSUFFICIENT"` (not registered, not ruled out either -- StatsMapped genuinely hasn't vetted this pair; never treat this as "probably comparable"). `uncertainty` names 4 separate dimensions (data_quality, comparability, statistical_strength, causal_strength) -- `causal_strength` is always `"not_established"`, since no comparison here implies causation regardless of verdict. `comparable` (DEPRECATED, kept only for callers that haven't migrated) collapses `verdict` to the old 3-way yes/no/unknown -- `"yes"` for both `SUPPORT` and `QUALIFY` (both mean "hand-vetted", the old `comparable` meaning this field has always carried; the caveats a `QUALIFY` pair carries live in `uncertainty`/`reasons`, not in demoting `comparable`), `"no"` for `REJECT`, `"unknown"` for `INSUFFICIENT`. Prefer `verdict` directly when you need to distinguish a fully-confirmed `SUPPORT` from a caveated `QUALIFY`. Read `reasons` before presenting any answer other than `"SUPPORT"` as unqualified. 4. None of the above given: lists every registered cross-dataset comparison pair for one country -- e.g. "median sale price vs new dwelling completions per 1,000 residents". A small, hand-curated set, not an arbitrary-pair engine: pass one of the returned `pair_key` values to mode 2 for the real correlation and axis detail. `level` is only meaningful together with `stat_key` (mode 1); giving it without `stat_key` raises rather than silently dropping it and falling through to mode 4's unrelated pair listing.

Use when the question is what a metric means or how it is measured; for a figure use `query_data`. Definition, methodology and standing caveats for ONE stat ('ireland' or 'united-kingdom') -- never a current figure. Call this when the question is about what a metric MEANS or how it's measured ("how is the claimant count defined", "is this a mean or a median"), not about a specific area's value -- `query_data`/`compare` already answer that. `stat_key` comes from `query_data(country=...)` for the SAME country.

Use when asked for a chart, still or short clip of a figure you can cite: returns the data to DRAW one scene, nothing rendered. Today one scene exists, "ireland-builds" (Ireland's homes granted permission, with a commencement notice and completed, by quarter from 2018Q1). The licence DIFFERS BY STAGE (see `licence.stages`): a stage whose licence is unconfirmed or ShareAlike is withheld (its cells are absences, not zeros) and the licence line names its holder. You get rows, a table twin, alt text, notes, `absences` (a missing figure is a typed absence, never a zero), the licence block, `scene_hash`, a `receipt` and the canonical URL. YOU draw it, and the last frame must match the table. Print the `scene_hash` and the licence `line` in the first, middle and last frame, quote only numbers that are in `rows`, do not loop, and keep the "stages are not a cohort" note. `purpose` is "analytical" (default) or "promotional": a promotional use of a source whose licence forbids advertising is refused (licence_refused). `vintage` (ISO date) omitted = the current data; an earlier vintage is not stored and returns unknown_vintage. Example: get_scene(scene_id="ireland-builds").

Use when you need the ids and names of the areas (counties, local authorities, districts) to pass to `query_data`. List every geography at one boundary level, for one country ('ireland' or 'united-kingdom'). `level` defaults to "county" (Ireland's 26 counties); the UK's own primary level is "lad" (local authority districts), not "county". Other levels exist per country (e.g. Ireland's "local_authority", "garda_division") -- see a dataset's own `compatible_levels` from `query_data` for which levels a given stat is actually published at. Returns each area's `id` (used by `query_data`'s area-scoped modes, always paired with the SAME `country`), `name` and `level`. Slim by default; `include_parents=True` adds each area's `parents` (the regions it sits in) and Irish-language name.

Use when the question is what changed lately, which figures moved most, or what is new; for one area's full history use `query_data`. Returns statistical movements databeat flagged as notable, not verdicts on what they mean; `limit` is 1 to 50 (default 8), and `stat_key` or `geography_id` narrows the list. Ireland and united-kingdom. Cite StatsMapped (https://statsmapped.com) as the source. Source: GET /{country}/api/v1/alerts/notable.

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.