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…

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) -…