Does NationsHelm have an API?

Yes. API v1 is plain HTTPS and JSON over the same scored record the site publishes: resolve, nations, nation history, leaders, rankings, nation-vs-nation compare, the metric, indicator and dimension catalogs, snapshots and corrections. There is also an MCP server at /api/v1/mcp for assistants that call tools directly. The machine-readable contract is /api/v1/openapi.json.

How do I get an API key?

Keys are self-serve from /account on every plan. A key is shown once at creation and stored hashed; send it as Authorization: Bearer nh_live_… or the X-API-Key alias, never in a query string. Create several so rotation needs no downtime — revocation is immediate.

Is there a free tier, and what are the limits?

A free key allows 60 requests a minute and 2,000 a day, with history windowed to the last 10 years. Paid tiers raise both and open full history; the per-plan limits are listed on this page.

Will a figure I quote today still check out later?

Every response names the immutable snapshot_id it was served from, and /snapshots independently confirms that vintage was published and when — so a quoted figure stays dated and checkable. v1 serves the active snapshot: ?snapshot= pins to it, and any other id returns 410 snapshot_not_available rather than a silently different vintage. Replaying an earlier snapshot's values is not served yet.

Is there an SDK to install?

No, and none is needed: the API is plain HTTPS and JSON, so any HTTP client works. This reference shows every call in cURL, Python, Node.js, Ruby, PHP, Java, Go and .NET, and the example responses are computed from the active snapshot at render time — real values, not specimens.

Can I redistribute the data or train on it?

Grounding and citation are welcome, with attribution — every payload carries a cite_url for exactly that. Bulk redistribution and silent training on paid-tier data are not licensed; data licensing lives on Enterprise.

Developer record

The API

Introduction

Sourced, deterministic geopolitical scores for nations and their leaders, served from immutable pinned snapshots. Every value is sourced or derived and dated; null means “No data” — never a fabricated number. Every response carries a snapshot_id (current: snap-20260816-15cf102d, scoring model v5.5.0) and a cite_url the attribution terms require surfacing. The machine-readable contract is /api/v1/openapi.json.

The example responses on this page are computed from the active snapshot at render time — they are real values, not specimens. The API is plain HTTPS + JSON, so any HTTP client works and there is no SDK to install.

Request samples

There is no NationsHelm SDK to install — the API is plain HTTPS + JSON, and each sample calls it with the HTTP client named above. The language you pick here rewrites every request on this page.

First call

curl https://nationshelm.com/api/v1/nations/FR \
  -H "Authorization: Bearer $NH_API_KEY"

Authentication

Keys are self-serve from /account on every plan, shown once at creation, stored hashed. Send Authorization: Bearer nh_live_… (primary) or the X-API-Key alias. Never put a key in a query string. Create several keys so rotation needs no downtime; revocation is immediate.

PLAN	BURST	DAILY	HISTORY DEPTH
Free	60/min	2,000/day	last 10 years
Analyst	300/min	30,000/day	full
Team	600/min	100,000/day	full
Enterprise	6,000/min	1,000,000/day	full

Free responses require attribution: surface the cite_url. Team quotas pool across the workspace. Enterprise limits are set per contract — data licensing lives there only.

Header — primary

Authorization: Bearer nh_live_…

Header — alias

X-API-Key: nh_live_…

One key, two accepted headers. A key in a query string is logged by every proxy it passes — the API does not read one there.

The envelope

Every data-bearing response is { data, meta }. The meta block makes a payload citable stand-alone — pasted into a context window, it carries its own provenance with zero extra lookups.

meta — on every response

{
  "snapshot_id": "snap-20260816-15cf102d",
  "scoring_model_version": "5.5.0",
  "scores_refreshed": "2026-08-16T21:28:48.686Z",
  "cite_url": "https://nationshelm.com/nations/france",
  "provenance_legend": "https://nationshelm.com/methodology"
}

Errors & limits

Status codes are honest and distinct: the code says what happened, and the body names the fix. A 429 always carries Retry-After and X-RateLimit-Limit / -Remaining / -Reset, so agents back off machine-readably rather than retry-storming.

CODE	ERROR	MEANING
200	—	Envelope { data, meta }.
400	bad_request	Missing or unknown parameter.
401	unauthorized	Missing, invalid, or revoked key.
403	requires_plan	Valid key, resource above the plan; the body names the plan and upgrade_url.
404	not_found / no_match	Unknown ref or nothing resolved; resolve the mention with /resolve first.
410	snapshot_not_available	That ?snapshot= id is not served here; omit it for the active snapshot.
429	rate_limited	Over plan quota; honor Retry-After.
503	temporarily_unavailable	Key verification is down — retry; the key is not dead.

403 requires_plan

{
  "error": "requires_plan",
  "requires_plan": "analyst",
  "message": "This resource is on the Analyst plan.",
  "upgrade_url": "https://nationshelm.com/pricing"
}

410 snapshot_not_available

{
  "error": "snapshot_not_available",
  "message": "Snapshot snap-20250101-0000abcd is not available from this endpoint yet; only the active snapshot is served. Omit ?snapshot= for the active one.",
  "active_snapshot_id": "snap-20260816-15cf102d"
}

Both bodies are produced by the endpoints’ own error builders — what you see here is what the API returns.

Snapshot pinning

Scores are served from immutable pinned snapshots, and that is part of the contract: ?snapshot=<id> exists on every scored endpoint from day one. v1 serves the active snapshot; any other id returns an honest 410 snapshot_not_available, never a silently different vintage.

What that buys today: every response identifies the immutable published snapshot it came from, and /snapshots independently confirms that vintage was published and when — so a quoted figure stays dated and its snapshot stays checkable. What it does not buy yet: re-reading an earlier snapshot’s values, because v1 will not replay a payload it no longer serves. Serving historical snapshots is the open item on this endpoint.

Pinned request

curl https://nationshelm.com/api/v1/nations/FR?snapshot=snap-20260816-15cf102d \
  -H "Authorization: Bearer $NH_API_KEY"

Resolve

GET /api/v1/resolve

The front door. Maps a natural-language mention to a canonical nation or leader ref plus confidence; every other endpoint takes canonical refs only. Nations resolve by ISO2, slug, or name; leaders by name, slug, or role phrases like “president of france”.

Parameters

qstring · queryRequired: The mention to resolve: a nation name, ISO2, slug, a leader name, or a role phrase ("the president of France"). Max 200 characters.

Request

curl https://nationshelm.com/api/v1/resolve?q=president+of+france \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "entity_type": "leader",
    "entity_ref": "emmanuel-macron/2017",
    "display_name": "Emmanuel Macron",
    "confidence": 0.9,
    "alternatives": [
      {
        "entity_type": "nation",
        "entity_ref": "FR",
        "display_name": "France",
        "confidence": 0.81
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/leaders/emmanuel-macron/2017",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

Metrics

GET /api/v1/metrics

The series catalog: every id the history endpoint accepts, with its label, unit, group, and source. /resolve maps free text to an entity; this answers what exists — the enumerability a program needs and a matcher cannot give it. availability counts the nations carrying observations. It is null only when coverage could not be read; a series no nation carries yet reports a measured 0, never a fabricated one. Takes no parameters.

Request

curl https://nationshelm.com/api/v1/metrics \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "metrics": [
      {
        "id": "gdpGrowth",
        "label": "GDP Growth",
        "unit": "%",
        "group": "Macro",
        "source": "World Bank",
        "availability": {
          "nations_covered": 192,
          "of": 203
        }
      },
      {
        "id": "inflationAnnual",
        "label": "Inflation",
        "unit": "%",
        "group": "Macro",
        "source": "World Bank",
        "availability": {
          "nations_covered": 184,
          "of": 203
        }
      },
      {
        "id": "unemployment",
        "label": "Unemployment",
        "unit": "%",
        "group": "Macro",
        "source": "World Bank",
        "availability": {
          "nations_covered": 178,
          "of": 203
        }
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/methodology",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

First 3 of 41 series; the endpoint returns the full catalog.

Indicators

GET /api/v1/indicators

Every indicator the scores are computed from — the methodology in machine-readable form. Each row carries its source, published refresh cadence, and lifecycle status: a frozen series is a fixed historical reading and must never be read as live. id is permanent, while name is a display label that may be reworded — store the id. Takes no parameters.

Request

curl https://nationshelm.com/api/v1/indicators \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "indicators": [
      {
        "id": "area",
        "name": "Area",
        "kind": "primary",
        "category_id": "profile",
        "category_label": "Profile / Context",
        "group": "Geography",
        "type": "sourced",
        "source": "CIA World Factbook — total area (primary, 200 nations), then Factbook land area (covers e.g. Chad, whose total is absent), then World Bank (AG.LND.TOTL.K2). No synthetic constant — null where none is sourced",
        "source_short": null,
        "update": "Monthly",
        "status": "active",
        "leader_stat": null
      },
      {
        "id": "population",
        "name": "Population",
        "kind": "primary",
        "category_id": "profile",
        "category_label": "Profile / Context",
        "group": "Geography",
        "type": "sourced",
        "source": "UN World Population Prospects 2024 (medium-variant total population) — the single source, covering all 203 nations and identical to the series the Demographics dimension scores from, so the Geography and Demographics panels can never print two different populations. World Bank SP.POP.TOTL is deliberately NOT used for population: it covers only 173 nations (a strict subset) and diverged from WPP by >2% for 58 of them (Moldova 19.8%, Albania 14.2%). No synthetic fallback — null where WPP omits the nation — 203 nations",
        "source_short": null,
        "update": "Monthly",
        "status": "active",
        "leader_stat": null
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/methodology",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

First 2 of 192 indicators; the endpoint returns the full registry.

Dimensions

GET /api/v1/dimensions

What the score keys in a nation payload mean: where each sits (overall, scores, derived), its 0–100 scale, and which direction is better — risk is the one where higher is worse. indicator_id points at the registry row that owns the methodology, so the two can never contradict each other. Takes no parameters.

Request

curl https://nationshelm.com/api/v1/dimensions \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "dimensions": [
      {
        "key": "overall",
        "label": "Overall",
        "location": "overall",
        "scale": "0-100",
        "direction": "higher_is_better",
        "indicator_id": "overall-score"
      },
      {
        "key": "economy",
        "label": "Economy",
        "location": "scores",
        "scale": "0-100",
        "direction": "higher_is_better",
        "indicator_id": "economy-score"
      },
      {
        "key": "governance",
        "label": "Governance",
        "location": "scores",
        "scale": "0-100",
        "direction": "higher_is_better",
        "indicator_id": "governance-score"
      },
      {
        "key": "quality_of_life",
        "label": "Quality of Life",
        "location": "scores",
        "scale": "0-100",
        "direction": "higher_is_better",
        "indicator_id": "quality-of-life-score"
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/methodology",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

First 4 of 12 keys; the endpoint returns them all.

Nations

GET /api/v1/nations/{ref}

Pillar scores (composite 0–100), derived indices (resilience, risk, opportunity, strategic position), committed momentum, archetypes, coverage, and the current leader.

Parameters

refstring · pathRequired: ISO2 code or site slug; responses canonicalize to ISO2.
snapshotstring · queryOptional: Pin the response to a specific snapshot id. Default: the active snapshot. Ids other than the active one return 410 snapshot_not_available (v1 serves the active snapshot only; the parameter is part of the contract from day one).

Request

curl https://nationshelm.com/api/v1/nations/FR \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "ref": "FR",
    "slug": "france",
    "name": "France",
    "overall": {
      "value": 76,
      "provenance": "derived"
    },
    "scores": {
      "economy": {
        "value": 68,
        "provenance": "derived",
        "coverage": {
          "present": 12,
          "total": 12
        }
      },
      "governance": {
        "value": 72,
        "provenance": "derived",
        "coverage": {
          "present": 8,
          "total": 11
        }
      },
      "quality_of_life": {
        "value": 96,
        "provenance": "derived",
        "coverage": {
          "present": 11,
          "total": 12
        }
      },
      "innovation": {
        "value": 69,
        "provenance": "derived",
        "coverage": {
          "present": 4,
          "total": 4
        }
      },
      "stability": {
        "value": 74,
        "provenance": "derived",
        "coverage": {
          "present": 5,
          "total": 5
        }
      }
    },
    "derived": {
      "resilience": {
        "value": 69,
        "provenance": "derived"
      },
      "risk": {
        "value": 31,
        "provenance": "derived"
      },
      "opportunity": {
        "start_business": {
          "value": 69,
          "provenance": "derived"
        },
        "emigrate_to": {
          "value": 87,
          "provenance": "derived"
        },
        "invest_in": {
          "value": 70,
          "provenance": "derived"
        }
      },
      "strategic_position": {
        "value": 63,
        "provenance": "derived"
      }
    },
    "momentum": {
      "direction": "down",
      "delta": -3,
      "sparse": false,
      "indicator_basis": 33
    },
    "archetypes": [
      "military-power",
      "clean-energy-leader",
      "diplomatic-heavyweight"
    ],
    "coverage": {
      "categories_present": 5,
      "categories_total": 5,
      "metrics_present": 42,
      "metrics_total": 46
    },
    "current_leader": {
      "person": "emmanuel-macron",
      "term": "2017",
      "display_name": "Emmanuel Macron",
      "role": "President"
    }
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/nations/france",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

History

GET /api/v1/nations/{ref}/history

Yearly points for one indicator, ascending, each with period / value / unit plus the series label and source. Free-tier keys receive the last 10 years relative to the series’ freshest point, with truncated: true when older years were cut.

Parameters

refstring · pathRequired: ISO2 code or site slug; responses canonicalize to ISO2.
metricstring · queryRequired: Which indicator series to return. One id per request.41 accepted: gdpGrowth · inflationAnnual · unemployment · debtToGdp · fiscalBalance · meanWage · govEffectiveness · ruleOfLaw · controlOfCorruption · regulatoryQuality · voiceAndAccountability · politicalStability · basicSanitation · safelyManagedSanitation · electricityAccess · cleanCookingAccess · povertyExtreme · airQualityPm25 · patentApplications · tertiaryEnrolment · transparency · vdemElections · vdemCorruption · vdemCensorship · elecSolarPct · elecWindPct · elecHydroPct · elecCoalPct · elecGasPct · elecNuclearPct · selfSufficiencyPct · cerealYieldKgHa · irrigationPctCropland · foodTradeBalanceUsd · foodExportsPct · arableLandPct · arableLandHaPerCapita · freshwaterPerCapitaM3 · mineralLithiumProd · mineralCopperProd · mineralRareEarthsProd

Request

curl https://nationshelm.com/api/v1/nations/FR/history?metric=gdpGrowth \
  -H "Authorization: Bearer $NH_API_KEY"

Leaders

GET /api/v1/leaders/{person}/{term}

Eight dimensions of per-tenure contribution vs global trends — not the country’s level — on the published 0–100 scale, plus archetype, tenure, and the Analyst Outlook: the one AI-labeled field in the API, gated to Analyst keys, always ai_generated: true, never blended into a score. The specimen is a Free-plan response, so the outlook shows its gate.

Parameters

personstring · pathRequired: Person slug, e.g. "emmanuel-macron". Resolve one with /resolve.
termstring · pathRequired: Term slug — the tenure start year. Each tenure is scored separately, so the term is part of the identity, not an optional qualifier.
snapshotstring · queryOptional: Pin the response to a specific snapshot id. Default: the active snapshot. Ids other than the active one return 410 snapshot_not_available (v1 serves the active snapshot only; the parameter is part of the contract from day one).

Request

curl https://nationshelm.com/api/v1/leaders/emmanuel-macron/2017 \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live, Free-plan key

{
  "data": {
    "person": "emmanuel-macron",
    "term": "2017",
    "display_name": "Emmanuel Macron",
    "nation_ref": "FR",
    "role": "President",
    "status": "active",
    "tenure": {
      "start": "2017-05-15",
      "end": null
    },
    "rating_model": "tenure contribution vs global trends, 0-100 published scale",
    "overall": {
      "value": 62,
      "provenance": "derived"
    },
    "ratings": {
      "gov": {
        "value": 57,
        "provenance": "derived"
      },
      "eco": {
        "value": 58,
        "provenance": "derived"
      },
      "dip": {
        "value": 84,
        "provenance": "derived"
      },
      "pol": {
        "value": 62,
        "provenance": "derived"
      },
      "cri": {
        "value": 64,
        "provenance": "derived"
      },
      "vis": {
        "value": null,
        "provenance": "derived"
      },
      "com": {
        "value": 23,
        "provenance": "derived"
      },
      "int": {
        "value": 97,
        "provenance": "derived"
      }
    },
    "archetype": null,
    "sourced_stat_count": 7,
    "analyst_outlook": {
      "available": false,
      "requires_plan": "analyst"
    }
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/leaders/emmanuel-macron/2017",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

Rankings

GET /api/v1/rankings/{slug}

Ordered entries with canonical refs, ranked from the pinned snapshot.

Parameters

slugstring · pathRequired: Which ranked list to return.17 accepted: most-stable-countries · least-stable-countries · strongest-economies · best-governance · worst-governance · highest-quality-of-life · most-innovative-countries · most-resilient-countries · best-countries-to-invest-in · best-countries-to-start-a-business · best-countries-to-emigrate-to · strongest-strategic-position · least-resilient-countries · top-countries-overall · most-undervalued-countries · small-nations-punching-above-their-weight · highest-rated-world-leaders
snapshotstring · queryOptional: Pin the response to a specific snapshot id. Default: the active snapshot. Ids other than the active one return 410 snapshot_not_available (v1 serves the active snapshot only; the parameter is part of the contract from day one).

Request

curl https://nationshelm.com/api/v1/rankings/most-stable-countries \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "slug": "most-stable-countries",
    "title": "Most Politically Stable Countries",
    "entity_type": "nation",
    "metric_label": "Stability",
    "score_kind": "score",
    "entries": [
      {
        "rank": 1,
        "entity_ref": "LU",
        "display_name": "Luxembourg",
        "score": 86
      },
      {
        "rank": 2,
        "entity_ref": "NZ",
        "display_name": "New Zealand",
        "score": 86
      },
      {
        "rank": 3,
        "entity_ref": "DK",
        "display_name": "Denmark",
        "score": 85
      },
      {
        "rank": 4,
        "entity_ref": "NO",
        "display_name": "Norway",
        "score": 85
      },
      {
        "rank": 5,
        "entity_ref": "CH",
        "display_name": "Switzerland",
        "score": 85
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/rankings/most-stable-countries",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

First 5 of 30 entries; the endpoint returns the full list.

Compare

GET /api/v1/compare/nations/{a}/{b}

Both full nation payloads (same shape as the nations endpoint) plus deltas — a minus b per dimension, null when either side is No data: a delta over a missing value would be an invented number.

Parameters

astring · pathRequired: Left nation — ISO2 or site slug. Deltas are a minus b.
bstring · pathRequired: Right nation — ISO2 or site slug.
snapshotstring · queryOptional: Pin the response to a specific snapshot id. Default: the active snapshot. Ids other than the active one return 410 snapshot_not_available (v1 serves the active snapshot only; the parameter is part of the contract from day one).

Request

curl https://nationshelm.com/api/v1/compare/nations/FR/DE \
  -H "Authorization: Bearer $NH_API_KEY"

Response deltas — computed live, FR vs DE

{
  "overall": -5,
  "economy": -7,
  "governance": -12,
  "quality_of_life": 0,
  "innovation": -6,
  "stability": -3,
  "resilience": -3,
  "strategic_position": -2
}

deltas only; data.a and data.b are full nation payloads as shown under Nations.

Snapshots

GET /api/v1/snapshots

The published snapshot registry, newest first — the trust pitch made concrete. Verify that a quoted snapshot_id is a real published vintage. Takes no parameters.

Request

curl https://nationshelm.com/api/v1/snapshots \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "snapshots": [
      {
        "snapshot_id": "snap-20260816-15cf102d",
        "published_at": "2026-08-16T21:28:48.686Z",
        "active": true,
        "scoring_model_version": "5.5.0"
      },
      {
        "snapshot_id": "snap-20260807-15cf102d",
        "published_at": "2026-08-07T12:55:18.451Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260801-c52216ba",
        "published_at": "2026-08-01T21:55:41.835Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260801-1fbafdcc",
        "published_at": "2026-08-01T20:57:11.561Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260801-7bd55011",
        "published_at": "2026-08-01T19:17:06.802Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260801-36da2fab",
        "published_at": "2026-08-01T05:17:04.190Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260801-45730bd3",
        "published_at": "2026-08-01T04:48:24.384Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260731-e3afdc37",
        "published_at": "2026-07-31T19:16:47.917Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260727-315db6f6",
        "published_at": "2026-07-27T02:13:44.806Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260727-118da79a",
        "published_at": "2026-07-27T01:13:01.726Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260727-2c9a4566",
        "published_at": "2026-07-27T00:53:04.949Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260726-860e51b8",
        "published_at": "2026-07-26T23:27:31.266Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260726-eb607e2c",
        "published_at": "2026-07-26T18:36:06.237Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260726-dd76b0cb",
        "published_at": "2026-07-26T17:17:42.182Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260725-62541605",
        "published_at": "2026-07-25T02:32:23.431Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260724-748303ac",
        "published_at": "2026-07-24T23:58:08.349Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260724-153e5aed",
        "published_at": "2026-07-24T16:00:25.455Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260724-03a31240",
        "published_at": "2026-07-24T03:26:13.150Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260724-ec58d08b",
        "published_at": "2026-07-24T02:42:25.082Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260723-3d6ff2f7",
        "published_at": "2026-07-23T13:24:19.120Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260723-f3c79bdd",
        "published_at": "2026-07-23T12:24:24.013Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260723-5ab537d0",
        "published_at": "2026-07-23T04:16:50.450Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260723-911dcddc",
        "published_at": "2026-07-23T04:01:10.223Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260722-52c7eba4",
        "published_at": "2026-07-22T17:29:07.973Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260720-f080bd49",
        "published_at": "2026-07-20T03:04:30.233Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260720-64d15e33",
        "published_at": "2026-07-20T02:46:55.053Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260719-c5957c20",
        "published_at": "2026-07-19T05:49:47.102Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260718-7279fba4",
        "published_at": "2026-07-18T22:08:47.937Z",
        "active": false,
        "scoring_model_version": null
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/methodology",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

Corrections

GET /api/v1/corrections

The append-only public corrections log, newest first. Entries are dated, signed by the editor, and never deleted. Takes no parameters.

Request

curl https://nationshelm.com/api/v1/corrections \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "corrections": [
      {
        "id": "2026-08-18-undervalued-nations-ranking-basis",
        "date": "2026-08-18",
        "entity": null,
        "entity_type": "nation",
        "indicator": "Undervalued Nations (/intelligence)",
        "summary": "Undervalued Nations was ORDERED by the canonical Undervaluation Gap while almost every published number read something else. The ranking row carried each nation's Opportunity Score rather than the gap that had ordered it, so the deterministic facts layer — which re-ranks on whatever the row carries — re-sorted the result by that score, and the headline, leader card, gap-to-#2, field spread, analyst summary and share card then named whichever nation held the highest Opportunity or Overall Rating instead of the widest gap. A screen whose first row was one country announced that a different one \"shows the widest residual\" at a number that was in fact its Overall Nation Rating and could not be a residual at all; the same substitution produced a negative \"gap to #2\", which is impossible when both sides are gaps. The row now carries the Undervaluation Gap itself, so every surface inherits the correct quantity from one canonical result: Opportunity Score, Overall Nation Rating, Strategic Position and the Fundamental Floor (the higher of the latter two) are published beside it as the values it is built from, and the identity Gap = Opportunity Score − Fundamental Floor is verifiable on the page. The Comparison Matrix now centres that decomposition instead of a country-profile board; the Data Table exposes all four quantities under their own names; the share card shows the undervaluation ranking rather than an Overall-score deck. Three counts are kept distinct — eligible candidates, nations with a positive gap, and rows displayed — so a filtered pool cannot read as a global one, and the requested result count is a maximum: a pool with fewer positive gaps returns fewer rows, and one with none returns an explicit empty result. \"Strongest opportunity vector\" replaces \"top driver\": the Opportunity Score is a mean of its vectors, so no vector is shown to have caused the gap. The underlying methodology in lib/opportunitySemantics.ts is unchanged.",
        "before": "The ranking row carried the Opportunity Score while the order came from the Undervaluation Gap, so the leader card, headline, gap-to-#2, spread and OG were computed from a different quantity — publishing an Overall Nation Rating as a \"residual\" and producing a negative gap to second place",
        "after": "The Undervaluation Gap is the published ranked quantity across every output, with the Opportunity Score, Overall Rating, Strategic Position and Fundamental Floor shown beside it as the values it is built from; qualifier, eligible and displayed counts are stated separately and only positive gaps qualify",
        "signed": "C·B"
      },
      {
        "id": "2026-08-18-rising-countries-and-window-framing",
        "date": "2026-08-18",
        "entity": null,
        "entity_type": "nation",
        "indicator": "Rising Countries (/intelligence) · Executive Brief timeframe framing",
        "summary": "Two corrections, both the mirror of ones already logged. (1) Rising Countries carried the same defects Declining Countries did: a requested Top N was filled out with countries that had held flat or moved the other way, and a selected Focus never reached the ranking basis, so \"Rising Countries · Focus Stability\" ranked the aggregate all-category change and omitted every country whose stability rose while its overall score fell. Only strictly positive changes on the active basis now qualify, the requested count is a maximum, a pool where nothing rose returns an explicit empty result, and a selected Focus sets the ranked quantity end to end. Causal wording went with it: the category that gained most is not shown to have caused the ranked change, so the \"Top change driver\" card reads \"Largest category gain\", and the share-card footer states how many of the eligible pool actually rose. (2) The Executive Brief's timeframe framing made claims about the PATH between a window's endpoints that no two-point comparison can support — a five-year read asserted that \"a single-year wobble wouldn't be enough to produce this picture\", and a ten-year read that a change of that size \"reflects systemic change, not a cycle\". Both now state what the window does establish: direction and magnitude, or size, but not whether the change accumulated steadily or in a single period. This line is shared, so the correction applies to every insight whose Brief carries it; the momentum insights state the limit in their own words instead.",
        "before": "Rising Countries returned exactly the requested number of rows, topped up with flat and declining countries, and ranked the aggregate change even when a Focus was selected; the Brief's five- and ten-year framing asserted that the change could not have come from a single period",
        "after": "Only strictly positive changes on the active basis appear in Rising Countries, a selected Focus is the ranking basis, and the requested count is a maximum; the timeframe framing states direction, magnitude and size without claiming how the change accumulated",
        "signed": "C·B"
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/corrections",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

First 2 of 41 entries; the endpoint returns the full log.

MCP server

POST /api/v1/mcp — Streamable HTTP

The same record as tools for agents. Eleven tools mirror the REST surface 1:1 — nationshelm_resolve, nationshelm_get_nation, nationshelm_get_leader, nationshelm_get_ranking, nationshelm_compare_nations, nationshelm_get_history, nationshelm_get_snapshots, nationshelm_get_corrections, nationshelm_list_metrics, nationshelm_list_indicators, nationshelm_list_dimensions — authenticate with the same nh_live_ key as a bearer token, and meter into the same quotas.

Claude Code

claude mcp add --transport http nationshelm https://nationshelm.com/api/v1/mcp \
  --header "Authorization: Bearer $NH_API_KEY"

Any MCP client

{
  "url": "https://nationshelm.com/api/v1/mcp",
  "transport": "streamable-http",
  "headers": {
    "Authorization": "Bearer nh_live_…"
  }
}

Common questions

Does NationsHelm have an API?: Yes. API v1 is plain HTTPS and JSON over the same scored record the site publishes: resolve, nations, nation history, leaders, rankings, nation-vs-nation compare, the metric, indicator and dimension catalogs, snapshots and corrections. There is also an MCP server at /api/v1/mcp for assistants that call tools directly. The machine-readable contract is /api/v1/openapi.json.
How do I get an API key?: Keys are self-serve from /account on every plan. A key is shown once at creation and stored hashed; send it as Authorization: Bearer nh_live_… or the X-API-Key alias, never in a query string. Create several so rotation needs no downtime — revocation is immediate.
Is there a free tier, and what are the limits?: A free key allows 60 requests a minute and 2,000 a day, with history windowed to the last 10 years. Paid tiers raise both and open full history; the per-plan limits are listed on this page.
Will a figure I quote today still check out later?: Every response names the immutable snapshot_id it was served from, and /snapshots independently confirms that vintage was published and when — so a quoted figure stays dated and checkable. v1 serves the active snapshot: ?snapshot=<id> pins to it, and any other id returns 410 snapshot_not_available rather than a silently different vintage. Replaying an earlier snapshot's values is not served yet.
Is there an SDK to install?: No, and none is needed: the API is plain HTTPS and JSON, so any HTTP client works. This reference shows every call in cURL, Python, Node.js, Ruby, PHP, Java, Go and .NET, and the example responses are computed from the active snapshot at render time — real values, not specimens.
Can I redistribute the data or train on it?: Grounding and citation are welcome, with attribution — every payload carries a cite_url for exactly that. Bulk redistribution and silent training on paid-tier data are not licensed; data licensing lives on Enterprise.

Terms

Grounding and citation are welcome, with attribution. Bulk redistribution and silent training on paid-tier data are not licensed — data licensing lives on Enterprise. The methodology behind every number is public at /methodology; corrections are public at /corrections.

Developer record

The API

Introduction

Request samples

There is no NationsHelm SDK to install — the API is plain HTTPS + JSON, and each sample calls it with the HTTP client named above. The language you pick here rewrites every request on this page.

First call

curl https://nationshelm.com/api/v1/nations/FR \
  -H "Authorization: Bearer $NH_API_KEY"

Authentication

PLAN	BURST	DAILY	HISTORY DEPTH
Free	60/min	2,000/day	last 10 years
Analyst	300/min	30,000/day	full
Team	600/min	100,000/day	full
Enterprise	6,000/min	1,000,000/day	full

Free responses require attribution: surface the cite_url. Team quotas pool across the workspace. Enterprise limits are set per contract — data licensing lives there only.

Header — primary

Authorization: Bearer nh_live_…

Header — alias

X-API-Key: nh_live_…

One key, two accepted headers. A key in a query string is logged by every proxy it passes — the API does not read one there.

The envelope

Every data-bearing response is { data, meta }. The meta block makes a payload citable stand-alone — pasted into a context window, it carries its own provenance with zero extra lookups.

meta — on every response

{
  "snapshot_id": "snap-20260816-15cf102d",
  "scoring_model_version": "5.5.0",
  "scores_refreshed": "2026-08-16T21:28:48.686Z",
  "cite_url": "https://nationshelm.com/nations/france",
  "provenance_legend": "https://nationshelm.com/methodology"
}

Errors & limits

CODE	ERROR	MEANING
200	—	Envelope { data, meta }.
400	bad_request	Missing or unknown parameter.
401	unauthorized	Missing, invalid, or revoked key.
403	requires_plan	Valid key, resource above the plan; the body names the plan and upgrade_url.
404	not_found / no_match	Unknown ref or nothing resolved; resolve the mention with /resolve first.
410	snapshot_not_available	That ?snapshot= id is not served here; omit it for the active snapshot.
429	rate_limited	Over plan quota; honor Retry-After.
503	temporarily_unavailable	Key verification is down — retry; the key is not dead.

403 requires_plan

{
  "error": "requires_plan",
  "requires_plan": "analyst",
  "message": "This resource is on the Analyst plan.",
  "upgrade_url": "https://nationshelm.com/pricing"
}

410 snapshot_not_available

{
  "error": "snapshot_not_available",
  "message": "Snapshot snap-20250101-0000abcd is not available from this endpoint yet; only the active snapshot is served. Omit ?snapshot= for the active one.",
  "active_snapshot_id": "snap-20260816-15cf102d"
}

Both bodies are produced by the endpoints’ own error builders — what you see here is what the API returns.

Snapshot pinning

Pinned request

curl https://nationshelm.com/api/v1/nations/FR?snapshot=snap-20260816-15cf102d \
  -H "Authorization: Bearer $NH_API_KEY"

Resolve

GET /api/v1/resolve

Parameters

qstring · queryRequired: The mention to resolve: a nation name, ISO2, slug, a leader name, or a role phrase ("the president of France"). Max 200 characters.

Request

curl https://nationshelm.com/api/v1/resolve?q=president+of+france \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "entity_type": "leader",
    "entity_ref": "emmanuel-macron/2017",
    "display_name": "Emmanuel Macron",
    "confidence": 0.9,
    "alternatives": [
      {
        "entity_type": "nation",
        "entity_ref": "FR",
        "display_name": "France",
        "confidence": 0.81
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/leaders/emmanuel-macron/2017",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

Metrics

GET /api/v1/metrics

Request

curl https://nationshelm.com/api/v1/metrics \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "metrics": [
      {
        "id": "gdpGrowth",
        "label": "GDP Growth",
        "unit": "%",
        "group": "Macro",
        "source": "World Bank",
        "availability": {
          "nations_covered": 192,
          "of": 203
        }
      },
      {
        "id": "inflationAnnual",
        "label": "Inflation",
        "unit": "%",
        "group": "Macro",
        "source": "World Bank",
        "availability": {
          "nations_covered": 184,
          "of": 203
        }
      },
      {
        "id": "unemployment",
        "label": "Unemployment",
        "unit": "%",
        "group": "Macro",
        "source": "World Bank",
        "availability": {
          "nations_covered": 178,
          "of": 203
        }
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/methodology",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

First 3 of 41 series; the endpoint returns the full catalog.

Indicators

GET /api/v1/indicators

Request

curl https://nationshelm.com/api/v1/indicators \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "indicators": [
      {
        "id": "area",
        "name": "Area",
        "kind": "primary",
        "category_id": "profile",
        "category_label": "Profile / Context",
        "group": "Geography",
        "type": "sourced",
        "source": "CIA World Factbook — total area (primary, 200 nations), then Factbook land area (covers e.g. Chad, whose total is absent), then World Bank (AG.LND.TOTL.K2). No synthetic constant — null where none is sourced",
        "source_short": null,
        "update": "Monthly",
        "status": "active",
        "leader_stat": null
      },
      {
        "id": "population",
        "name": "Population",
        "kind": "primary",
        "category_id": "profile",
        "category_label": "Profile / Context",
        "group": "Geography",
        "type": "sourced",
        "source": "UN World Population Prospects 2024 (medium-variant total population) — the single source, covering all 203 nations and identical to the series the Demographics dimension scores from, so the Geography and Demographics panels can never print two different populations. World Bank SP.POP.TOTL is deliberately NOT used for population: it covers only 173 nations (a strict subset) and diverged from WPP by >2% for 58 of them (Moldova 19.8%, Albania 14.2%). No synthetic fallback — null where WPP omits the nation — 203 nations",
        "source_short": null,
        "update": "Monthly",
        "status": "active",
        "leader_stat": null
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/methodology",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

First 2 of 192 indicators; the endpoint returns the full registry.

Dimensions

GET /api/v1/dimensions

Request

curl https://nationshelm.com/api/v1/dimensions \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "dimensions": [
      {
        "key": "overall",
        "label": "Overall",
        "location": "overall",
        "scale": "0-100",
        "direction": "higher_is_better",
        "indicator_id": "overall-score"
      },
      {
        "key": "economy",
        "label": "Economy",
        "location": "scores",
        "scale": "0-100",
        "direction": "higher_is_better",
        "indicator_id": "economy-score"
      },
      {
        "key": "governance",
        "label": "Governance",
        "location": "scores",
        "scale": "0-100",
        "direction": "higher_is_better",
        "indicator_id": "governance-score"
      },
      {
        "key": "quality_of_life",
        "label": "Quality of Life",
        "location": "scores",
        "scale": "0-100",
        "direction": "higher_is_better",
        "indicator_id": "quality-of-life-score"
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/methodology",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

First 4 of 12 keys; the endpoint returns them all.

Nations

GET /api/v1/nations/{ref}

Pillar scores (composite 0–100), derived indices (resilience, risk, opportunity, strategic position), committed momentum, archetypes, coverage, and the current leader.

Parameters

refstring · pathRequired: ISO2 code or site slug; responses canonicalize to ISO2.
snapshotstring · queryOptional: Pin the response to a specific snapshot id. Default: the active snapshot. Ids other than the active one return 410 snapshot_not_available (v1 serves the active snapshot only; the parameter is part of the contract from day one).

Request

curl https://nationshelm.com/api/v1/nations/FR \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "ref": "FR",
    "slug": "france",
    "name": "France",
    "overall": {
      "value": 76,
      "provenance": "derived"
    },
    "scores": {
      "economy": {
        "value": 68,
        "provenance": "derived",
        "coverage": {
          "present": 12,
          "total": 12
        }
      },
      "governance": {
        "value": 72,
        "provenance": "derived",
        "coverage": {
          "present": 8,
          "total": 11
        }
      },
      "quality_of_life": {
        "value": 96,
        "provenance": "derived",
        "coverage": {
          "present": 11,
          "total": 12
        }
      },
      "innovation": {
        "value": 69,
        "provenance": "derived",
        "coverage": {
          "present": 4,
          "total": 4
        }
      },
      "stability": {
        "value": 74,
        "provenance": "derived",
        "coverage": {
          "present": 5,
          "total": 5
        }
      }
    },
    "derived": {
      "resilience": {
        "value": 69,
        "provenance": "derived"
      },
      "risk": {
        "value": 31,
        "provenance": "derived"
      },
      "opportunity": {
        "start_business": {
          "value": 69,
          "provenance": "derived"
        },
        "emigrate_to": {
          "value": 87,
          "provenance": "derived"
        },
        "invest_in": {
          "value": 70,
          "provenance": "derived"
        }
      },
      "strategic_position": {
        "value": 63,
        "provenance": "derived"
      }
    },
    "momentum": {
      "direction": "down",
      "delta": -3,
      "sparse": false,
      "indicator_basis": 33
    },
    "archetypes": [
      "military-power",
      "clean-energy-leader",
      "diplomatic-heavyweight"
    ],
    "coverage": {
      "categories_present": 5,
      "categories_total": 5,
      "metrics_present": 42,
      "metrics_total": 46
    },
    "current_leader": {
      "person": "emmanuel-macron",
      "term": "2017",
      "display_name": "Emmanuel Macron",
      "role": "President"
    }
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/nations/france",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

History

GET /api/v1/nations/{ref}/history

Parameters

refstring · pathRequired: ISO2 code or site slug; responses canonicalize to ISO2.
metricstring · queryRequired: Which indicator series to return. One id per request.41 accepted: gdpGrowth · inflationAnnual · unemployment · debtToGdp · fiscalBalance · meanWage · govEffectiveness · ruleOfLaw · controlOfCorruption · regulatoryQuality · voiceAndAccountability · politicalStability · basicSanitation · safelyManagedSanitation · electricityAccess · cleanCookingAccess · povertyExtreme · airQualityPm25 · patentApplications · tertiaryEnrolment · transparency · vdemElections · vdemCorruption · vdemCensorship · elecSolarPct · elecWindPct · elecHydroPct · elecCoalPct · elecGasPct · elecNuclearPct · selfSufficiencyPct · cerealYieldKgHa · irrigationPctCropland · foodTradeBalanceUsd · foodExportsPct · arableLandPct · arableLandHaPerCapita · freshwaterPerCapitaM3 · mineralLithiumProd · mineralCopperProd · mineralRareEarthsProd

Request

curl https://nationshelm.com/api/v1/nations/FR/history?metric=gdpGrowth \
  -H "Authorization: Bearer $NH_API_KEY"

Leaders

GET /api/v1/leaders/{person}/{term}

Parameters

personstring · pathRequired: Person slug, e.g. "emmanuel-macron". Resolve one with /resolve.
termstring · pathRequired: Term slug — the tenure start year. Each tenure is scored separately, so the term is part of the identity, not an optional qualifier.
snapshotstring · queryOptional: Pin the response to a specific snapshot id. Default: the active snapshot. Ids other than the active one return 410 snapshot_not_available (v1 serves the active snapshot only; the parameter is part of the contract from day one).

Request

curl https://nationshelm.com/api/v1/leaders/emmanuel-macron/2017 \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live, Free-plan key

{
  "data": {
    "person": "emmanuel-macron",
    "term": "2017",
    "display_name": "Emmanuel Macron",
    "nation_ref": "FR",
    "role": "President",
    "status": "active",
    "tenure": {
      "start": "2017-05-15",
      "end": null
    },
    "rating_model": "tenure contribution vs global trends, 0-100 published scale",
    "overall": {
      "value": 62,
      "provenance": "derived"
    },
    "ratings": {
      "gov": {
        "value": 57,
        "provenance": "derived"
      },
      "eco": {
        "value": 58,
        "provenance": "derived"
      },
      "dip": {
        "value": 84,
        "provenance": "derived"
      },
      "pol": {
        "value": 62,
        "provenance": "derived"
      },
      "cri": {
        "value": 64,
        "provenance": "derived"
      },
      "vis": {
        "value": null,
        "provenance": "derived"
      },
      "com": {
        "value": 23,
        "provenance": "derived"
      },
      "int": {
        "value": 97,
        "provenance": "derived"
      }
    },
    "archetype": null,
    "sourced_stat_count": 7,
    "analyst_outlook": {
      "available": false,
      "requires_plan": "analyst"
    }
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/leaders/emmanuel-macron/2017",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

Rankings

GET /api/v1/rankings/{slug}

Ordered entries with canonical refs, ranked from the pinned snapshot.

Parameters

slugstring · pathRequired: Which ranked list to return.17 accepted: most-stable-countries · least-stable-countries · strongest-economies · best-governance · worst-governance · highest-quality-of-life · most-innovative-countries · most-resilient-countries · best-countries-to-invest-in · best-countries-to-start-a-business · best-countries-to-emigrate-to · strongest-strategic-position · least-resilient-countries · top-countries-overall · most-undervalued-countries · small-nations-punching-above-their-weight · highest-rated-world-leaders
snapshotstring · queryOptional: Pin the response to a specific snapshot id. Default: the active snapshot. Ids other than the active one return 410 snapshot_not_available (v1 serves the active snapshot only; the parameter is part of the contract from day one).

Request

curl https://nationshelm.com/api/v1/rankings/most-stable-countries \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "slug": "most-stable-countries",
    "title": "Most Politically Stable Countries",
    "entity_type": "nation",
    "metric_label": "Stability",
    "score_kind": "score",
    "entries": [
      {
        "rank": 1,
        "entity_ref": "LU",
        "display_name": "Luxembourg",
        "score": 86
      },
      {
        "rank": 2,
        "entity_ref": "NZ",
        "display_name": "New Zealand",
        "score": 86
      },
      {
        "rank": 3,
        "entity_ref": "DK",
        "display_name": "Denmark",
        "score": 85
      },
      {
        "rank": 4,
        "entity_ref": "NO",
        "display_name": "Norway",
        "score": 85
      },
      {
        "rank": 5,
        "entity_ref": "CH",
        "display_name": "Switzerland",
        "score": 85
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/rankings/most-stable-countries",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

First 5 of 30 entries; the endpoint returns the full list.

Compare

GET /api/v1/compare/nations/{a}/{b}

Both full nation payloads (same shape as the nations endpoint) plus deltas — a minus b per dimension, null when either side is No data: a delta over a missing value would be an invented number.

Parameters

astring · pathRequired: Left nation — ISO2 or site slug. Deltas are a minus b.
bstring · pathRequired: Right nation — ISO2 or site slug.
snapshotstring · queryOptional: Pin the response to a specific snapshot id. Default: the active snapshot. Ids other than the active one return 410 snapshot_not_available (v1 serves the active snapshot only; the parameter is part of the contract from day one).

Request

curl https://nationshelm.com/api/v1/compare/nations/FR/DE \
  -H "Authorization: Bearer $NH_API_KEY"

Response deltas — computed live, FR vs DE

{
  "overall": -5,
  "economy": -7,
  "governance": -12,
  "quality_of_life": 0,
  "innovation": -6,
  "stability": -3,
  "resilience": -3,
  "strategic_position": -2
}

deltas only; data.a and data.b are full nation payloads as shown under Nations.

Snapshots

GET /api/v1/snapshots

The published snapshot registry, newest first — the trust pitch made concrete. Verify that a quoted snapshot_id is a real published vintage. Takes no parameters.

Request

curl https://nationshelm.com/api/v1/snapshots \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "snapshots": [
      {
        "snapshot_id": "snap-20260816-15cf102d",
        "published_at": "2026-08-16T21:28:48.686Z",
        "active": true,
        "scoring_model_version": "5.5.0"
      },
      {
        "snapshot_id": "snap-20260807-15cf102d",
        "published_at": "2026-08-07T12:55:18.451Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260801-c52216ba",
        "published_at": "2026-08-01T21:55:41.835Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260801-1fbafdcc",
        "published_at": "2026-08-01T20:57:11.561Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260801-7bd55011",
        "published_at": "2026-08-01T19:17:06.802Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260801-36da2fab",
        "published_at": "2026-08-01T05:17:04.190Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260801-45730bd3",
        "published_at": "2026-08-01T04:48:24.384Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260731-e3afdc37",
        "published_at": "2026-07-31T19:16:47.917Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260727-315db6f6",
        "published_at": "2026-07-27T02:13:44.806Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260727-118da79a",
        "published_at": "2026-07-27T01:13:01.726Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260727-2c9a4566",
        "published_at": "2026-07-27T00:53:04.949Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260726-860e51b8",
        "published_at": "2026-07-26T23:27:31.266Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260726-eb607e2c",
        "published_at": "2026-07-26T18:36:06.237Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260726-dd76b0cb",
        "published_at": "2026-07-26T17:17:42.182Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260725-62541605",
        "published_at": "2026-07-25T02:32:23.431Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260724-748303ac",
        "published_at": "2026-07-24T23:58:08.349Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260724-153e5aed",
        "published_at": "2026-07-24T16:00:25.455Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260724-03a31240",
        "published_at": "2026-07-24T03:26:13.150Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260724-ec58d08b",
        "published_at": "2026-07-24T02:42:25.082Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260723-3d6ff2f7",
        "published_at": "2026-07-23T13:24:19.120Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260723-f3c79bdd",
        "published_at": "2026-07-23T12:24:24.013Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260723-5ab537d0",
        "published_at": "2026-07-23T04:16:50.450Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260723-911dcddc",
        "published_at": "2026-07-23T04:01:10.223Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260722-52c7eba4",
        "published_at": "2026-07-22T17:29:07.973Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260720-f080bd49",
        "published_at": "2026-07-20T03:04:30.233Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260720-64d15e33",
        "published_at": "2026-07-20T02:46:55.053Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260719-c5957c20",
        "published_at": "2026-07-19T05:49:47.102Z",
        "active": false,
        "scoring_model_version": null
      },
      {
        "snapshot_id": "snap-20260718-7279fba4",
        "published_at": "2026-07-18T22:08:47.937Z",
        "active": false,
        "scoring_model_version": null
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/methodology",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

Corrections

GET /api/v1/corrections

The append-only public corrections log, newest first. Entries are dated, signed by the editor, and never deleted. Takes no parameters.

Request

curl https://nationshelm.com/api/v1/corrections \
  -H "Authorization: Bearer $NH_API_KEY"

Response — computed live

{
  "data": {
    "corrections": [
      {
        "id": "2026-08-18-undervalued-nations-ranking-basis",
        "date": "2026-08-18",
        "entity": null,
        "entity_type": "nation",
        "indicator": "Undervalued Nations (/intelligence)",
        "summary": "Undervalued Nations was ORDERED by the canonical Undervaluation Gap while almost every published number read something else. The ranking row carried each nation's Opportunity Score rather than the gap that had ordered it, so the deterministic facts layer — which re-ranks on whatever the row carries — re-sorted the result by that score, and the headline, leader card, gap-to-#2, field spread, analyst summary and share card then named whichever nation held the highest Opportunity or Overall Rating instead of the widest gap. A screen whose first row was one country announced that a different one \"shows the widest residual\" at a number that was in fact its Overall Nation Rating and could not be a residual at all; the same substitution produced a negative \"gap to #2\", which is impossible when both sides are gaps. The row now carries the Undervaluation Gap itself, so every surface inherits the correct quantity from one canonical result: Opportunity Score, Overall Nation Rating, Strategic Position and the Fundamental Floor (the higher of the latter two) are published beside it as the values it is built from, and the identity Gap = Opportunity Score − Fundamental Floor is verifiable on the page. The Comparison Matrix now centres that decomposition instead of a country-profile board; the Data Table exposes all four quantities under their own names; the share card shows the undervaluation ranking rather than an Overall-score deck. Three counts are kept distinct — eligible candidates, nations with a positive gap, and rows displayed — so a filtered pool cannot read as a global one, and the requested result count is a maximum: a pool with fewer positive gaps returns fewer rows, and one with none returns an explicit empty result. \"Strongest opportunity vector\" replaces \"top driver\": the Opportunity Score is a mean of its vectors, so no vector is shown to have caused the gap. The underlying methodology in lib/opportunitySemantics.ts is unchanged.",
        "before": "The ranking row carried the Opportunity Score while the order came from the Undervaluation Gap, so the leader card, headline, gap-to-#2, spread and OG were computed from a different quantity — publishing an Overall Nation Rating as a \"residual\" and producing a negative gap to second place",
        "after": "The Undervaluation Gap is the published ranked quantity across every output, with the Opportunity Score, Overall Rating, Strategic Position and Fundamental Floor shown beside it as the values it is built from; qualifier, eligible and displayed counts are stated separately and only positive gaps qualify",
        "signed": "C·B"
      },
      {
        "id": "2026-08-18-rising-countries-and-window-framing",
        "date": "2026-08-18",
        "entity": null,
        "entity_type": "nation",
        "indicator": "Rising Countries (/intelligence) · Executive Brief timeframe framing",
        "summary": "Two corrections, both the mirror of ones already logged. (1) Rising Countries carried the same defects Declining Countries did: a requested Top N was filled out with countries that had held flat or moved the other way, and a selected Focus never reached the ranking basis, so \"Rising Countries · Focus Stability\" ranked the aggregate all-category change and omitted every country whose stability rose while its overall score fell. Only strictly positive changes on the active basis now qualify, the requested count is a maximum, a pool where nothing rose returns an explicit empty result, and a selected Focus sets the ranked quantity end to end. Causal wording went with it: the category that gained most is not shown to have caused the ranked change, so the \"Top change driver\" card reads \"Largest category gain\", and the share-card footer states how many of the eligible pool actually rose. (2) The Executive Brief's timeframe framing made claims about the PATH between a window's endpoints that no two-point comparison can support — a five-year read asserted that \"a single-year wobble wouldn't be enough to produce this picture\", and a ten-year read that a change of that size \"reflects systemic change, not a cycle\". Both now state what the window does establish: direction and magnitude, or size, but not whether the change accumulated steadily or in a single period. This line is shared, so the correction applies to every insight whose Brief carries it; the momentum insights state the limit in their own words instead.",
        "before": "Rising Countries returned exactly the requested number of rows, topped up with flat and declining countries, and ranked the aggregate change even when a Focus was selected; the Brief's five- and ten-year framing asserted that the change could not have come from a single period",
        "after": "Only strictly positive changes on the active basis appear in Rising Countries, a selected Focus is the ranking basis, and the requested count is a maximum; the timeframe framing states direction, magnitude and size without claiming how the change accumulated",
        "signed": "C·B"
      }
    ]
  },
  "meta": {
    "snapshot_id": "snap-20260816-15cf102d",
    "scoring_model_version": "5.5.0",
    "scores_refreshed": "2026-08-16T21:28:48.686Z",
    "cite_url": "https://nationshelm.com/corrections",
    "provenance_legend": "https://nationshelm.com/methodology"
  }
}

First 2 of 41 entries; the endpoint returns the full log.

MCP server

POST /api/v1/mcp — Streamable HTTP

Claude Code

claude mcp add --transport http nationshelm https://nationshelm.com/api/v1/mcp \
  --header "Authorization: Bearer $NH_API_KEY"

Any MCP client

{
  "url": "https://nationshelm.com/api/v1/mcp",
  "transport": "streamable-http",
  "headers": {
    "Authorization": "Bearer nh_live_…"
  }
}

Common questions

Does NationsHelm have an API?: Yes. API v1 is plain HTTPS and JSON over the same scored record the site publishes: resolve, nations, nation history, leaders, rankings, nation-vs-nation compare, the metric, indicator and dimension catalogs, snapshots and corrections. There is also an MCP server at /api/v1/mcp for assistants that call tools directly. The machine-readable contract is /api/v1/openapi.json.
How do I get an API key?: Keys are self-serve from /account on every plan. A key is shown once at creation and stored hashed; send it as Authorization: Bearer nh_live_… or the X-API-Key alias, never in a query string. Create several so rotation needs no downtime — revocation is immediate.
Is there a free tier, and what are the limits?: A free key allows 60 requests a minute and 2,000 a day, with history windowed to the last 10 years. Paid tiers raise both and open full history; the per-plan limits are listed on this page.
Will a figure I quote today still check out later?: Every response names the immutable snapshot_id it was served from, and /snapshots independently confirms that vintage was published and when — so a quoted figure stays dated and checkable. v1 serves the active snapshot: ?snapshot=<id> pins to it, and any other id returns 410 snapshot_not_available rather than a silently different vintage. Replaying an earlier snapshot's values is not served yet.
Is there an SDK to install?: No, and none is needed: the API is plain HTTPS and JSON, so any HTTP client works. This reference shows every call in cURL, Python, Node.js, Ruby, PHP, Java, Go and .NET, and the example responses are computed from the active snapshot at render time — real values, not specimens.
Can I redistribute the data or train on it?: Grounding and citation are welcome, with attribution — every payload carries a cite_url for exactly that. Bulk redistribution and silent training on paid-tier data are not licensed; data licensing lives on Enterprise.