# CountryAtlas API — reference

Base URL: https://www.countryatlas.co/api/v1 (proxied by the Next.js app to the FastAPI process on 127.0.0.1:8291). Interactive docs: /api/v1/docs (Swagger) · /api/v1/redoc · spec /api/v1/openapi.json.

• All endpoints are GET (except POST /admin/refresh, POST /admin/cache/clear) and return JSON (gzip when accepted).
• Identifiers: countries by ISO3 or slug (case-insensitive: CAN, can, canada); indicators, topics and groups by slug.
• Every response carries meta: {built_at, run_id, generated_at}; the header X-CountryAtlas-Run repeats the snapshot run id and X-Cache: HIT|MISS tells whether the in-process cache served it (cache keys include the run id, so a new snapshot invalidates everything).
• Errors are RFC 7807 application/problem+json: {"type","title","status","detail","instance",…}. 404 unknown country/indicator/topic/group (with a helpful detail), 400 bad combination, 422 invalid parameter (with errors[]), 429 rate limit (120 req/min/IP, Retry-After), 503 {"title":"Data not built yet"} while no snapshot exists.
• Run locally: CA_DATA_DIR=~/countryatlas-data ca-api (or python -m uvicorn countryatlas.api.main:app --port 8291).

# The provenance object

Every value the API returns (headline metrics, series points, ranking rows, map values, curated lists, changes…) carries a provenance object built from observations → indicator_sources → sources:

{
  "value": 55697.66, "period": "2025-01-01", "year": 2025, "unit": "current US$", "is_estimate": false, "is_forecast": false,
  "status": "imported", "formatted": "55.7k",
  "provenance": {
    "source": "worldbank", "source_name": "World Bank", "dataset": "WDI", "series_code": "NY.GDP.PCAP.CD",
    "retrieved_at": "2026-09-11T06:49:30Z", "source_updated_at": "2026-07-13T00:00:00Z",
    "url": "https://data.worldbank.org/indicator/NY.GDP.PCAP.CD?locations=CA", "transform": null, "licence": "CC BY 4.0"
  }
}

Series responses also list all sources used (sources[], with n_values) and the dominant one as provenance.

# Endpoints

# Health

GET /health          → {status: "ok"|"empty", run_id, built_at, observations, countries, indicators, version, cache}

/health never returns 503; status: "empty" means the pipeline has not produced atlas.duckdb yet.

# Countries

GET /countries?region=&income=&q=&sort=name|population|gdp|gdp_per_capita|coverage&kind=&limit=&offset=
GET /countries/{id}                       overview: country header, groups, coverage, freshness, headline metrics, topics summary, neighbours
GET /countries/{id}/topics/{topic}        indicators of a topic grouped by subtopic (registry order); indicators without data → has_data:false
GET /countries/{id}/series/{indicator}?from=&to=&freq=A|Q|M&include_forecast=true&include_alt=false
GET /countries/{id}/changes?limit=&kind=  recent detected changes (by severity)
GET /countries/{id}/events?limit=&kind=&indicator=   whole-history timeline
GET /countries/{id}/similar?mode=overall|economic|demographic|energy|social&limit=
GET /countries/{id}/insights
GET /countries/{id}/dna
GET /countries/{id}/download.csv|json?include_forecast=&topic=

region accepts any group id or slug (ecs, europe-central-asia, oecd, g7…); income accepts HIC|UMC|LMC|LIC or the slug.

curl -s https://www.countryatlas.co/api/v1/countries/canada | jq '.headline[] | {indicator, formatted, year, rank_world, n_world, source: .provenance.source}'
# {"indicator":"gdp-per-capita","formatted":"55.7k","year":2025,"rank_world":21,"n_world":188,"source":"worldbank"} …
curl -s "https://www.countryatlas.co/api/v1/countries/CAN/series/gdp-per-capita?from=2000" | jq '.stats, .provenance'

Headline metric object (MetricValue): value, formatted, period, year, unit, is_estimate, is_forecast, status, prev{period,value}, change{abs,pct,formatted}, change_10y{…}, rank_world/n_world, rank_region/n_region (World Bank region), rank_income/n_income, rank_year, rank_is_stale (rank computed on a year > 2 years older than the indicator's latest year), higher_is_better, sparkline [[year, value]…] (last 30 non-forecast points), provenance.

# Indicators

GET /indicators?topic=&q=&featured=&source=&with_data=
GET /indicators/{slug}                    definition, sources (priority order, deep links), coverage (+ by_year), world_latest, freshness, top5/bottom5, years, topics
GET /indicators/{slug}/map?year=&nearest=false&classes=6
GET /indicators/{slug}/trend?group=world&from=&to=&min_n=5
GET /indicators/{slug}/download.csv|json?from=&to=&include_forecast=

• world_latest is computed across countries (World Bank aggregates such as WLD are not stored): kind is sum for additive indicators, weighted_mean (population-weighted) for per-capita / share indicators, median otherwise; median, mean, weighted_mean and n are always returned.
• map: without year, the latest year with ≥ 50 countries is used (year_used). With nearest=true each country's latest value within 3 years of the reference year is used and years{ISO3: year} says which. legend.breaks are quantile breaks (5–7 classes).
• trend: per year median, mean, weighted_mean (population) for per-capita/percent indicators, sum for additive ones, n; preferred says which to plot.

curl -s "https://www.countryatlas.co/api/v1/indicators/life-expectancy/map?year=2023" | jq '{year_used, n, legend, CAN: .values.CAN}'
curl -s "https://www.countryatlas.co/api/v1/indicators/gdp/trend?group=oecd" | jq '.points[-1]'

# Series bundle

GET /series?country=CAN,FRA&indicator=gdp-per-capita,inflation&from=1990&to=2026&freq=A&include_forecast=true

Returns series[] (one per indicator × country), each with values[] (per-point provenance), sources[], provenance, stats{min,max,first,last,cagr}.

# Rankings

GET /rankings?topic=                      rankable indicators (featured first) with ranking_year / ranking_n
GET /rankings/{indicator}?year=&group=world&sort=asc|desc&limit=50&offset=0&sparkline=true
GET /rankings/{indicator}/history?countries=CAN,USA&from=&to=

Rows: rank (within the requested group), rank_world/n_world (from the snapshot), pct_rank, country{id,slug,name,flag,region,income}, value, formatted, year, change_1y, change_10y, sparkline, provenance. Default sort is asc when higher_is_better=false (e.g. infant mortality), otherwise desc. year_used falls back to the nearest available year; years_available lists them.

curl -s "https://www.countryatlas.co/api/v1/rankings/gdp-per-capita?limit=3" | jq '.rows[] | [.rank, .country.name, .formatted, .change_1y.formatted]'
# [1,"Luxembourg","147.3k","+6.9 %"] [2,"Ireland","131.6k","+16.6 %"] [3,"Switzerland","114.8k","+6.6 %"]

# Compare

GET /compare?countries=CAN,USA,FRA&indicators=gdp,gdp-per-capita&from=&to=&mode=absolute|per-capita|index100|pct&include_forecast=
GET /compare/snapshot?countries=CAN,USA&topic=economy   (or &indicators=a,b; default = headline indicators)
GET /compare/download.csv|json?countries=&indicators=&from=&to=

Modes: index100 rebases each series to 100 at the first available year ≥ from; per-capita divides additive (aggregation=sum) indicators by the population series of the same year (already per-capita indicators are left unchanged, transform.applied=false); pct = % change vs previous period. snapshot returns one row per indicator with a values{ISO3: MetricValue} map and best (when higher_is_better is known).

# Regions / groups

GET /regions?kind=world|region|continent|income|org
GET /regions/{slug}?indicator=gdp-per-capita&sort=asc|desc

Group page: members with headline values (+ provenance), aggregates (sum population/GDP, population-weighted GDP per capita, median life expectancy…, each with kind), and a member ranking on the chosen indicator.

# Search

GET /search?q=&limit=10&type=country|indicator|topic|region|source

Typed hits {type, id, slug, name, hint, score, url} from search_index (exact → prefix → word → substring → Jaro-Winkler fuzzy). Hints: Country · North America, Indicator · Economy · annual %, Topic · 12 indicators, Region · Organisation · 38 members. Two-word combos such as housing canada or canada gdp also return country_topic / country_indicator hits with a ready URL (/countries/canada/housing).

# Home

GET /home

snapshot (world population / GDP sums, median life expectancy, counts, built_at), lists (largest economies; fastest GDP growth, fastest population growth, highest life expectancy and energy transition leaders among countries ≥ 1 M; highest GDP per capita PPP; lowest unemployment among countries ≥ 5 M — 8 rows each with provenance, filter_note), recent_changes (12 most severe), recently_updated, featured_indicators, trending.

# Changes, sources, methodology

GET /changes?limit=&offset=&kind=&indicator=&country=&topic=&min_severity=
GET /sources                              n_observations, n_indicators, licence, last_retrieved_at
GET /sources/{id}                         indicators mapped, datasets, import_runs, freshness
GET /methodology                          registry-derived: topics, units/formats, source priority rule + URL patterns, validation rules, derived computations, DNA dimensions

# Downloads

CSV is streamed with a leading # CountryAtlas export · run … · built … comment line and the columns country_id, country_name, indicator_id, indicator_name, period, year, frequency, value, unit, is_estimate, is_forecast, status, source, source_name, dataset, series_code, retrieved_at, source_updated_at, url, licence. JSON returns {meta, n, columns, rows}.

# Admin (header X-Admin-Token: $CA_ADMIN_TOKEN)

GET  /admin/overview          db, meta, table counts, connectors health (import_runs), sources freshness/stale counts, scheduler heartbeat (data_dir/scheduler.json + scheduler.pid), cache stats
GET  /admin/runs?limit=&connector=&status=
GET  /admin/issues?severity=&connector=&indicator=&code=&run_id=&limit=
GET  /admin/coverage          indicator × n_countries / last_year matrix + per-country coverage
GET  /admin/raw?run_id=       raw files stored for a run
POST /admin/refresh           sends SIGUSR1 to the scheduler pid (409 when no scheduler)
POST /admin/cache/clear

403 on a wrong/missing token, 503 {"title":"Admin disabled"} when CA_ADMIN_TOKEN is not set.

# Operations notes

• Snapshot swap: the API opens ~/countryatlas-data/atlas.duckdb read-only and compares st_ino/st_mtime_ns on every request; when the pipeline os.replace()s a new file, the old connection is closed and the new one opened (DuckDB caches instances per path, so the close must happen first). Responses are cached in-process per (run_id, path, query); nothing survives a new run id.
• Performance (real snapshot, 2.0 M observations): country overview ≈ 12 ms warm (≈ 170 ms on the very first request while static lookups load), rankings ≈ 20 ms, home ≈ 33 ms, map ≈ 4 ms, cached hits ≈ 1 ms.
• Formatting: formatted strings use the indicator's format: currency compact with the registry unit_short prefix (US$53.4k, US$1.2T, intl $45.3B), number compact (41.7M), percent 3.4 %, years 82.1 yrs, tonnes 5.2 t, per-1000 3.2 per 1,000, per-100k 1.2 per 100k. formatted_short is the same value without prefix/unit (53.4k, 3.4) for tight cells.
• Registry reloads: the headline list (topics.yaml), indicator metadata and groups are re-read from the YAML registry each time a new snapshot run id is opened (the loaders' lru_cache is cleared), so registry edits take effect with the next build.
• Home lists: each curated list carries min_population and filter_note (e.g. "Countries above 1M inhabitants") when a population floor applies (fastest GDP growth, fastest population growth, highest life expectancy, energy transition leaders: ≥ 1M; lowest unemployment: ≥ 5M).

# Analytics endpoints (API 1.1 — contract, 2026-09-11)

All additive, read-only, GET, cached per snapshot like the rest. Paths stay under /api/v1. Country-only pools (kind='country'), annual canonical frequency, non-forecast, non-quarantined. Every value object still carries provenance where a single source applies; aggregates carry provenance[] (one per contributing source, with n_values). Neutral wording everywhere: a change is an increase / decrease; it is called an improvement / deterioration only when the indicator declares higher_is_better.

GET /pulse                                         World Pulse — what is changing globally (latest year vs previous)
GET /movers?window=1|5|10&category=&kind=&limit=&min_population=      Biggest movers by window / category / kind
GET /extremes?window=1|5|10|25|since1990&topic=&min_population=        Curated extremes facets (fastest ageing, urbanising…)
GET /scatter?x=&y=&size=&year=&group=&log_x=&log_y=                      Cross-section scatter + Pearson / Spearman / OLS
GET /trajectory?x=&y=&size=&from=&to=&group=                           Gapminder-style frames (compact arrays per country)
GET /finder?f=slug:op:value&f=…&mode=and|or&region=&income=&sort=&limit= Structured country finder over `latest`
GET /peers?y=&x=&year=&method=theil-sen|ols&log_x=                      Above / below expected (robust cross-sectional fit)
GET /indicators/{slug}/related?limit=&min_n=                           Statistically related indicators (descriptive)
GET /indicators/{slug}/distribution?year=&highlight=&bins=              Histogram + medians (world / region / income) + percentile
GET /indicators/{slug}/frames?from=&to=&step=&group=                    Multi-year map frames for the time machine
GET /indicators/{slug}/quality                                         Coverage / freshness / continuity summary
GET /rankings/{indicator}/race?from=&to=&top=&group=                    Rank race frames (top N per year)
GET /regions/compare?a=&b=&indicators=                                 Group vs group aggregates + history
GET /countries/{id}/story                                              "How X changed": long-run indicators, templated text
GET /countries/{id}/dna?reference=world|region|income|<ISO3>           DNA + reference profile
GET /countries/{id}/quality                                            Per-indicator data quality for a country
GET /updates                                                           Freshness dashboard (sources, runs, changed values)
GET /search?q=compare canada usa                                       Intent hits (type action) — see below

# Shapes

MoverItem — {country: CountryCard, indicator: IndicatorCard, kind, year, ref_year, value, ref_value, delta, delta_pct, formatted, formatted_ref, severity (0–1), direction: "up"|"down", interpretation: "improvement"|"deterioration"|null, headline, provenance}. kind ∈ yoy_jump | yoy_drop | record_high | record_low | n_year_high | n_year_low | sign_flip | accelerating | decelerating | structural_break | trend_reversal | volatility_spike | change_5y | change_10y. Categories: economic = economy+government+trade+income, demographic = population, health, energy, climate = climate+environment, digital = digital+innovation, housing, labor. Kinds filter: improvement | deterioration | increase | decrease | record | reversal | acceleration | structural | all.

/pulse → {meta, year_reference, summary: {n_indicators, n_countries_reporting, n_record_highs, n_record_lows, n_changes}, items: [{indicator, year, n, n_up, n_down, n_flat, share_up, share_down, median_change_abs, median_change_pct, direction_semantics: "higher_is_better"|"lower_is_better"|"neutral", record_highs, record_lows, headline, top_up: MoverLite, top_down: MoverLite, convergence: {direction, cv_start, cv_end, n, from_year} | null, provenance}]} where MoverLite = {country, value, ref_value, delta, delta_pct, formatted, year}. Only headline + featured indicators whose latest year is ≥ reference − 1. Headlines are templates, e.g. "Inflation fell in 73 % of 176 reporting countries" (share_down ≥ 60), "Population is shrinking in 31 countries", "Renewable electricity hit a record high in 42 countries".

/extremes → {meta, window, from_year, to_year, min_population, filter_note, facets: [{id, title, indicator, direction: "up"|"down", metric: "abs"|"pct"|"points", rows: [{country, value_start, value_end, year_start, year_end, delta, delta_pct, formatted_start, formatted_end}], n, provenance}]}. Facets (fixed, in this order, skipped when the indicator has < 30 countries in the window): aging median-age ↑ · urbanizing urban-population-share ↑ · fertility-decline fertility-rate ↓ · life-expectancy-gains ↑ · gdp-transformations gdp-per-capita-ppp ↑ (pct) · digital-adoption internet-users ↑ · renewable-transitions renewable-electricity-share ↑ · co2-reductions co2-per-capita ↓ (pct) · population-decline population ↓ (pct) · population-boom population ↑ (pct) · inflation-surges inflation ↑ (points) · debt-buildup general-government-gross-debt-pct-gdp ↑ (points) · unemployment-falls ↓ (points). topic filters facets by their indicator topic. window=since1990 → from_year 1990.

/scatter → {meta, x, y, size, year, year_used, nearest_years: 3, group, n, points: [{id, slug, name, flag, region, income, x, y, size, year_x, year_y}], stats: {n, pearson, spearman, ols: {slope, intercept, r2} | null, log_x, log_y}, note}. log_x/log_y accept true|false|auto (auto = true when the indicator's format is currency/number with bounds ≥ 0 and max/min > 50). size defaults to population; size=none disables. Each axis uses the country's value in year_used or the nearest within 3 years.

/trajectory → {meta, x, y, size, group, years: [int…], countries: [{id, slug, name, flag, region, income}], series: {ISO3: {x: [num|null…], y: [...], size: [...]}}, domains: {x: [min,max], y: [min,max], size: [min,max]}, log_x, log_y, provenance: [...]} — arrays aligned on years, no interpolation. Default from = first year with ≥ 50 countries on both axes, to = last year with ≥ 50. Countries with < 30 % of frames on both axes are dropped.

/finder → filters f=slug:op:value (repeatable; ops gt gte lt lte eq between — between uses a..b), mode=and|or (default and), region/income group slug, sort=slug:asc|desc (default: first filter, desc), limit ≤ 218. Response {meta, mode, filters: [{indicator, op, value, value2, year_used}], n_matching, n_evaluated, items: [{country: CountryCard, matched: [slug…], values: {slug: {value, year, formatted, provenance}}}]}. year_used = latest year of each country (mixed years, honest).

/peers → {meta, x, y, year_used, n, method, fit: {slope, intercept, r2, log_x, residual_scale}, points: [{id, slug, name, flag, region, income, x, y, expected, residual, residual_z}], above: [top 12 by residual_z], below: [bottom 12], pairs: [{x, y, label}], note, methodology}. residual_z = residual / (1.4826·MAD of residuals). Default pair y=life-expectancy, x=gdp-per-capita-ppp, log_x=true. Suggested pairs: (life-expectancy, gdp-per-capita-ppp), (expected-years-of-schooling, gdp-per-capita-ppp), (co2-per-capita, gdp-per-capita-ppp), (life-expectancy, health-expenditure-per-capita), (internet-users, gdp-per-capita-ppp), (infant-mortality-rate, gdp-per-capita-ppp). Wording must stay descriptive: "above the fitted line", never "outperforms because".

/indicators/{slug}/related → {meta, indicator, year_used, n_candidates, items: [{indicator, pearson, spearman, n, year, log_x, log_y, direction: "positive"|"negative"}], note: "Correlation does not imply causation."} — cross-section on latest (values within 3 years of the indicator's max year), pairs need n ≥ min_n (default 40), sorted by |Spearman| desc, self and per-capita twins of the same quantity excluded when both are present (e.g. gdp vs gdp-ppp is allowed; gdp-per-capita vs gdp-per-capita-ppp is allowed — no hand rules beyond self).

/indicators/{slug}/distribution → {meta, indicator, year, year_used, n, log, histogram: {edges, counts, log}, stats: {min, p10, p25, median, mean, p75, p90, max}, highlight: {country: CountryCard, value, percentile, rank, n, region: GroupCard|null, region_median, income: GroupCard|null, income_median} | null, by_region: [{group: GroupCard, median, n}], by_income: [{group, median, n}], provenance}.

/indicators/{slug}/frames → {meta, indicator, group, years: [...], values: {ISO3: [num|null…]}, legend: {min, max, breaks: [...], n_classes}, n_by_year: [...], provenance} — breaks are quantiles over the pooled values of all years (a stable legend while scrubbing). Years limited to those with ≥ 20 countries; ≤ 80 frames.

/indicators/{slug}/quality → {meta, indicator, n_countries, n_countries_total, coverage_pct, first_year, last_year, latest_common_year, n_years, years_with_50plus, median_points_per_country, sparse_countries, stale_countries, flagged_values, sources: [...], badges: [...]}. Badges vocabulary (shared with the country endpoint): fresh (latest year ≥ reference − 1), historical (first year ≤ 1970), sparse (median points per country < 10), limited-coverage (< 50 % of countries), stale (latest year ≤ reference − 3), flagged (> 5 % of values with status warning), forecast (chosen source publishes projections).

/rankings/{indicator}/race → {meta, indicator, group, top, years: [...], frames: [{year, rows: [{id, value, rank}]}], countries: {ISO3: CountryCard}, max_value, provenance}. Union of countries that appear in the top N in any frame; only years with ≥ 20 ranked countries.

/regions/compare → {meta, groups: [GroupCard, GroupCard], rows: [{indicator, kind: "sum"|"median"|"weighted_mean", label, values: {<group id>: {value, formatted, n, year}}}], shares: {<group id>: {population_share_pct, gdp_share_pct}}, history: {<indicator slug>: {years: [...], <group id>: [num|null…]}}} for indicators (default) population, gdp, gdp-per-capita, life-expectancy, co2-per-capita, internet-users, gdp-growth, inflation; history for the first four (sum/weighted/median per year, ≥ 60 % of members reporting).

/countries/{id}/story → {meta, country, since, items: [{indicator, first: {year, value, formatted}, last: {year, value, formatted}, change_abs, change_pct, cagr, peak: {year, value}, trough: {year, value}, rank_first: {rank, n, year} | null, rank_last: {...} | null, series: [[year, value]…], text, provenance}]} — indicators in this order when ≥ 10 annual points: population, gdp-per-capita-ppp (fallback gdp-per-capita), life-expectancy, fertility-rate, urban-population-share, co2-per-capita, internet-users, renewable-electricity-share, general-government-gross-debt-pct-gdp, median-age, energy-use-per-capita, unemployment-rate; max 10 items. text template: "{country}'s {indicator} {rose|fell} from {first} in {y0} to {last} in {y1} ({signed pct} / {signed points})."

/countries/{id}/dna (extended) → adds reference: {kind: "world"|"region"|"income"|"country", id, label, dims: {...}} | null (world → 50 on every dimension; region/income → median of the members' dims; country → that country's dims).

/countries/{id}/quality → {meta, country, summary: {n_indicators, n_with_data, coverage_pct, latest_year, n_fresh, n_stale, n_sparse, n_flagged}, items: [{indicator, latest_year, first_year, n_points, expected_points, missing_years, continuity_pct, status, source, source_updated_at, retrieved_at, badges: [...]}]}.

/updates → {meta, snapshot: {run_id, built_at, observations, indicators, countries, values_changed, values_changed_by_source: {...}}, sources: [{source: Source, status: "ok"|"partial"|"failed"|"stale"|"unknown", last_success_at, last_retrieved_at, source_updated_at, n_datasets, n_indicators, n_observations, latest_year, values_changed, countries_affected}], recent_runs: [{run_id, connector, dataset, started_at, finished_at, status, rows_valid, warnings, errors, message}], indicators_recently_updated: [IndicatorSummary…]}. No file paths, hosts or secrets in the payload.

/search intents — deterministic parsing before the index lookup; each intent yields a hit {type: "action", action, id, name, hint, url, score: 1.0}: compare <c1> <c2> [<c3>…] → /compare/<slugs>; rank[ing] <indicator> → /rankings/<slug>; <indicator> <country> (already country_indicator); <indicator> <group> → /rankings/<slug>?group=<group>; <indicator> map|explore → /explore?indicator=; <c1> vs <c2> → compare.

# Change detection 2.0 kinds (pipeline)

structural_break (single mean shift with gain ≥ 0.5 and shift ≥ 1.5 × series sd, segments ≥ 5 years, break within the last 10 years for changes), trend_reversal (three consecutive yearly moves of one sign after three of the opposite sign), volatility_spike (sd of the last 5 yearly differences ≥ 3 × the sd of the previous 15). Same row shape; detail documents the parameters.

# Implementation notes (as built, 2026-09-12 — deviations from the contract above)

• /pulse takes min_population (default 1 000 000, 0 disables) that filters the top movers only (top_up/top_down); counts and shares use every reporting country. The response echoes min_population and filter_note. Pools need ≥ 30 reporting countries (not 20) so a thin indicator (Gini, 25 countries) never headlines; year_reference is the latest year of the annual pillars population / GDP / life expectancy (monthly/quarterly series already carry the current year). Convergence compares max-year vs max-year − 10.
• /movers windows 5/10 report kinds change_5y / change_10y (direction in direction), keep moves with robust |z| ≥ 1.5 and rank by severity = min(1, |z|/4) × importance; kind=record|reversal|acceleration|structural are only meaningful for window=1 and return an empty list otherwise. Window 1 reads the changes table (any kind, including the pipeline's structural_break / trend_reversal / volatility_spike).
• /extremes facets each carry their own from_year / to_year (the indicator's latest common year and its window start); the top-level pair is the min/max across facets. Start values use the nearest observation within ±2 years of the window start.
• /indicators/{slug}/related: min_n accepts ≥ 5 (default 40). Pearson is computed on the association scale (log10 for level series, flagged log_x/log_y), Spearman on raw values.
• /indicators/{slug}/distribution: highlight also returns year; group medians need ≥ 2 members with data.
• /regions/compare history[slug] also carries kind; /updates sources carry runs {n, n_failed} and snapshot.reference_year.
• /countries/{id}/story text template is "{Country}: {Indicator} rose|fell from {first} in {y0} to {last} in {y1} ({signed change}[, ±x % a year])." (colon form keeps acronyms such as GDP / PPP intact); /countries/{id}/dna adds note.
• /search intents: countries are resolved by ISO2/ISO3 code first, then exact single word, then (near-)exact 2–3-word names, then fuzzy.