The API

v1 · read-only · methodology 0.3.0 · preview

Everything the website publishes about a place, over HTTP: the score, the eight pillars behind it, the confidence on each, the projected pillar values under their named scenario, and the named observations and sources every number resolves to. 7,368 places — 250 countries, 3,234 regions, 3,884 cities — at one methodology version, versioned and immutable: a published score is never rewritten, and a new methodology version is new rows. What the API says today it will still say next year, and the change ledger records when that stops being the current version.

This is a preview. The endpoints below are live and unauthenticated; keys, terms and pricing do not exist yet and are listed at the bottom of this page as the proposals they are.

Endpoints

GET /api/v1/meta

The API's own record: methodology version, corpus counts by level, endpoint list.

curl https://habitance.io/api/v1/meta

GET /api/v1/places/{slug}

The full published record for one place: identity, composite score with confidence and any red flag, all eight pillar scores with per-pillar confidence, every projected pillar value under its family's named scenario, Access score, quadrant, ranks, the indicator observations behind the score, and the sources they resolve to.

curl https://habitance.io/api/v1/places/lisbon-pt

GET /api/v1/places?level=&limit=&offset=

Paginated index of places — slug, name, level, score, confidence, rank. level is L0, L1 or CITY; limit defaults to 100, maximum 500. Ordered by unit_id, which is stable across builds.

curl "https://habitance.io/api/v1/places?level=L0&limit=5"

GET /api/v1/rankings/{level}?horizon=now|2050

The ranked list at one level, from the same ordering the site publishes. Places below the published coverage floor are excluded, and the response states how many. horizon=2050 is the 2050 horizon — climate SSP2-4.5 · demographics UN medium, labelled as such.

curl "https://habitance.io/api/v1/rankings/cities?horizon=2050"

GET /api/v1/changes

The change ledger: each frozen methodology version, each source vintage, each narration run — dated, with the repository path it resolves to. Also served as JSON Feed at /changes.json and Atom at /feed.xml.

curl https://habitance.io/api/v1/changes

The envelope

Every response carries the same wrapper, so a stored payload keeps its provenance: the API version, the methodology version the numbers were computed under, the newest observation date where the payload has one, the attribution line, and the licence note. The payload is under data.

{
  "api_version": "v1",
  "methodology_version": "0.3.0",
  "data_as_of": "2026-07-01",
  "attribution": "Habitance — habitance.io",
  "license": "Preview — no API keys have been issued and no commercial licence is granted yet. …",
  "disclaimer": "Habitance is informational. …",
  "data": { }
}

Errors use the same wrapper with an error object in place of data: 404 for an unknown slug, 400 for a malformed parameter, each with a stable code.

{
  "api_version": "v1",
  "methodology_version": "0.3.0",
  "attribution": "Habitance — habitance.io",
  "error": {
    "status": 404,
    "code": "place_not_found",
    "message": "No place is published under the slug \"atlantis\" at this methodology version. Slugs are listed by /api/v1/places."
  }
}

What the numbers claim, and what they do not

Confidence rides next to every score — the composite, each pillar, each index row. A pillar the place carries no data for is null, never a fabricated number.
Only an indicator that declares a projection carries a 2035 or 2050 value: the climate family under an emissions scenario, and the demographic family under the UN's medium variant. Stability, infrastructure, safety and community hold their current value at every horizon — projecting a government to 2050 is fiction, and the model refuses to. A 2050 composite is projected climate, water, crop yield and the UN's medium population variant, against today's stability, infrastructure, safety and community, and the response says so in a note field wherever one appears. Nothing else is projected, and no field will imply it is.
Ranks obey the published coverage floor: a place below it is scored and served, and excluded from ranked lists — the rankings response counts the exclusions rather than hiding them.
Every observation resolves to (source_id, source_version, indicator_id, methodology_version). Indicator rows whose source licence is not cleared for commercial use are withheld from API responses and shown on the website only; each place response counts what it withheld.

Caching and versioning

Responses are served with Cache-Control: public, max-age=3600, stale-while-revalidate=86400. The data behind them changes only when a methodology version publishes, so a cached response is not a stale one — the envelope’s methodology_version says exactly which record you hold. Within v1, changes are additive: fields are added, never renamed, never removed, and never re-typed. A change that cannot be additive is a v2 under a new path, with v1 kept serving.

Authentication — designed, not yet live

The API will authenticate with a key in the Authorization: Bearer header. No keys have been issued: issuance, rate limits per tier and the abuse policy are specified in docs/API_V1.md and open behind a human decision. Until then the preview is unauthenticated and rate limits are the host’s defaults.

# Not yet live — no keys have been issued. The header the API will accept:
curl -H "Authorization: Bearer hab_live_…" https://habitance.io/api/v1/places/colorado-us

Pricing — proposed, not yet purchasable

Nothing on this page can be bought. The band under consideration for the self-serve commercial licence is $99–$499 per month, tiered by request volume and redistribution rights, with exact tiers pending a human decision. It is stated here so that a reader evaluating the preview knows the order of magnitude, not as an offer. The free website — the globe, the place pages, the methodology, the rankings — stays free.

Preview only. No payment can be taken, no key can be granted, and no commercial use is licensed until terms are published.

Attribution

Any use of this data names its source and the version it was read at. The required line, which every response also carries in its envelope:

Habitance — habitance.io · methodology 0.3.0

Cite the methodology version. A score is a claim under a named method, and the version is what makes the citation checkable next year.