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.

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 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 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.