Skip to content
    BestCityToLive.City intelligence by AINT.app

    Build with city intelligence

    Good city answers
    start with sources.

    City dossiers for your research desk, travel workflow or AI-assisted tool. Read the evidence, preserve its context and give every answer a trail back to the source.

    Open API catalog Read the quickstart

    Public HTTP GET · JSON + Markdown · No API key · An AINT.app initiative

    Connect AI assistants or embed a city guide
    GET /api/v1/cities/calgary.json

    "id": "city:calgary"

    "kind": "city"

    "edition.status": "research"

    "observations": {
    "city_context": [...],
    "country_context": [...]
    }

    A schema preview. Open the endpoint for its actual review dates, observations, primary sources and snapshot ID.
    63complete city dossiers
    41countries & territories
    17category decision guides
    8scoped evidence views

    01 / Read the snapshot

    One request. A useful starting point.

    Start with the catalog, download a city or filter the complete directory locally. These are published static resources: query strings do not search or filter the server. The JavaScript example assumes a browser on BestCityToLive; other applications can use a server-side client.

    // Run on BestCityToLive, or fetch server-side.
const response = await fetch('/api/v1/cities.json');
if (!response.ok) throw new Error(response.status);
const snapshot = await response.json();

// Filtering happens locally, after the download.
const canadianCities = snapshot.items.filter(
  city => city.country.iso_3 === 'CAN'
);

const calgaryResponse = await fetch(
  '/api/v1/cities/calgary.json'
);
const calgary = await calgaryResponse.json();
console.log(calgary.citation);
console.log(calgary.observations.city_context);

    02 / Resource directory

    Small surface. Deep records.

    Every link below opens a real published file. City and category directories contain the available slugs; the OpenAPI document lists each concrete URL.

    GET

    Metropolitan motor-vehicle traffic fatalities

    /api/v1/road-deaths.json

    Calendar 2024 · crash year provisional ARF fatalities / matching July 1 population on reviewed OMB2023 source MSAs. Keep original counts, event definition, complete counties, source unknowns, binary archive manifests and current engine identity.

    GET

    Current admitted research inputs

    /api/v1/index-observations.json

    Only observations accepted by the current index engine, with observation periods, scoped geography, source frames and review proof. Historical approval alone does not imply current admission.

    GET

    Historical annual + monthly heat

    /api/v1/heat-exposure.json

    2025 modelled outdoor heat, 2020 population weights and 2015 estimated areas. 63 destination bindings; exact source frames, dependent monthly contributions and current engine admission are separate.

    GET

    Canadian rental-vacancy survey

    /api/v1/rental-vacancy.json

    October 2025 combined private apartment and row rates across 4 Canadian destination bindings. Original CMA identifiers, source precision/quality, seasonal month and conditional reuse terms; not global coverage.

    GET

    Canadian housing construction

    /api/v1/housing-supply.json

    Calendar 2025 gross new dwelling completions per 1,000 preliminary July 1 residents across 4 reviewed CMA2021 bindings. Preserve the structural milestone, exact source identifier roles, integer operands and conditional rights.

    GET

    Published Australian period life expectancy

    /api/v1/life-expectancy.json

    Original ABS Persons at-birth cells for 2022–2024, across 4 reviewed GCCSA2021 regions. Original one-decimal values, native GDA2020 source/adapter, explicit method/CI/SE unknowns, CC BY 4.0 attribution and current admission remain separate.

    GET

    Reviewed analytical geography

    /api/v1/scoring-geographies.json

    Protocol-scoped analytical boundaries, original identities and exact archive hashes. Repeated permissions for the same physical area do not create new areas; each record declares its own approved protocol references.

    GET

    Air evidence desk

    /api/v1/air-quality.json

    Separate EPA annual monitor summaries and EEA modelled city-period exposure, with original scopes, periods, source records and licences.

    GET

    Operational definitions

    /api/v1/index-protocols.json

    30 measurement definitions: 6 frozen after completed review and 24 drafts. Primary references, calculation choices and the separate evidence-admission policy. A draft never authorizes scoring.

    GET

    Geography research

    /api/v1/geography-candidates.json

    All 63 destination crosswalks, source-qualified OECD and older estimated-area candidates, unknown vintages and explicit non-approval.

    GET

    Start here

    /api/v1/catalog.json

    Snapshot identity, resource counts, discovery links and data limitations.

    GET

    City directory

    /api/v1/cities.json

    All city summaries. Each entry links to its complete JSON and readable Markdown dossier.

    GET

    City dossier

    /api/v1/cities/calgary.json

    The editorial guide, primary references, contextual evidence and dated category scores.

    GET

    Citation brief

    /api/v1/cities/calgary.md

    The same city guide in plain Markdown, with review date, scope, sources and a suggested citation.

    GET

    Coverage atlas

    /api/v1/countries.json

    Countries and territories with published city dossiers. Coverage counts are not national rankings.

    GET

    Country coverage

    /api/v1/countries/canada.json

    Covered city guides and their review dates, with national contextual observations in a separate array.

    GET

    Evidence directory

    /api/v1/evidence-views.json

    Eight scoped comparisons with explicit periods, geographic boundaries and source definitions.

    GET

    Evidence comparison

    /api/v1/evidence-views/canada-unemployment.json

    Sorted comparable point estimates, shared ranks for exact ties and preserved source uncertainty.

    GET

    Ranking directory

    /api/v1/categories.json

    Lifestyle decision frameworks, with their actual review and legacy snapshot dates.

    GET

    Category detail

    /api/v1/categories/overall.json

    An editorial decision guide and exact, explicitly labeled legacy ranking rows.

    GET

    Evidence snapshot

    /api/v1/observations.json

    City context and country context in separate arrays, preserving units, periods and geographic scope.

    GET

    Source catalog

    /api/v1/sources.json

    Stable source IDs, original URLs, scope notes and available licence information.

    GET

    Research library

    /api/v1/articles.json

    Article summaries with links to full JSON text and canonical research pages.

    GET

    Complete city observatory

    /api/v1/observatory.json

    All 63 destinations, source urban footprints and every assessed Civometra indicator, including missing evidence.

    GET

    Source urban geography

    /api/v1/urban-centres.json

    62 deduplicated JRC urban centres, 63 destination crosswalks and projected 2025 population with boundary qualifications.

    GET

    Civometra indicator catalog

    /api/v1/index-metrics.json

    The 30 fixed model definitions, required units, weights, normalization anchors and evidence-age limits.

    GET

    OpenAPI 3.1

    /api/v1/openapi.json

    Every concrete read endpoint in this edition, documented as an HTTP GET operation.

    Reviewed source desks

    Carry the source into your product.

    These endpoints retain a historical reviewed estimate alongside its actual current engine state, evaluated 2026-10-27. Preserve both. An expired or replaced observation remains inspectable; its review flag does not keep it admitted. Query parameters do not filter these static files.

    GET /api/v1/heat-exposure.json

    A year of heat, with its monthly detail.

    63 destination bindings across 62 physical estimated areas; 63 exact historical annual inputs currently admitted. Evidence reviewed 2026-10-26.

    Keep weather 2025, population weights 2020, boundary 2015, UTC days and the 38°C outdoor UTCI threshold. The unit is person-days/person. The twelve monthly contributions are dependent parts of one annual input, not twelve separately admitted metrics.

    The provider revision is not returned: preserve null and the exact original chart-response archive hash. This is regional model weather, not a forecast, climate normal or clinical risk estimate. Original C3S/ECMWF chart facts retain their data licence, modification attribution and responsibility notice; no provider frontend-code grant is implied.

    Open JSON ↗Human source desk ↗Protocol ↗

    GET /api/v1/rental-vacancy.json

    One Canadian survey cohort.

    4 destination bindings in October 2025; 4 exact historical survey inputs currently admitted. Evidence reviewed 2026-10-26. This subset does not establish worldwide vacancy coverage.

    Preserve the combined private apartment and row universe, official CMA 2021 identifiers, source quality flags and one-decimal published precision. Calendar bounds identify the survey month; no exact fieldwork day or independently observed vacant-unit count is invented.

    The engine ages month-precision evidence conservatively from its first possible day. The API keeps the original temporal basis and published-rate derivation. CMHC conditional data terms and acknowledgements accompany each record; this API grants no additional reuse rights.

    Open JSON ↗Human source desk ↗Reuse conditions ↗

    GET /api/v1/housing-supply.json

    A construction flow, with its denominator.

    Calendar 2025 gross new dwelling completions per 1,000 preliminary July 1 residents. 4 of 4 exact reviewed Canadian inputs currently admitted; evidence reviewed 2026-10-26.

    CMHC's structural milestone may allow up to 10% unfinished work in some circumstances; it is not occupancy certification. Preserve all intended markets, original integer operands and the preliminary population status.

    Native publication notes assign CMA2021 scope. Keep the completion CSV's 2011-prefixed DGUID, the population's national CMA2021 DGUID and the boundary's provincial-part DGUID in their original roles. CMHC conditional terms and separate Statistics Canada rights follow the data; this API grants no additional reuse rights.

    Open JSON ↗Human source desk ↗Protocol & source terms ↗

    GET /api/v1/life-expectancy.json

    The original cell, with its qualifications.

    ABS Persons life expectancy at birth for 2022–2024, original one-decimal cells on native GCCSA2021 functional regions. 4 of 4 exact historical inputs currently admitted; evidence reviewed 2026-10-26.

    The derivation keeps original workbook/header/cell references, native EPSG:7844 geometry and the reviewed destination-point adapter. GCCSA algorithm, terminal age, overseas-death rule and source CI/SE remain null; the SA4 method and a male/female average are not substituted.

    Preserve CC BY 4.0 source credit, adaptation responsibility and exact current identity, including reviewed_at. A historical review does not override expiry or replacement, or establish quarterly comparison clearance.

    Open JSON ↗Human source desk ↗Published-value protocol ↗

    GET /api/v1/road-deaths.json

    An event count with a matching region.

    7 of 7 original Calendar 2024 · crash year inputs currently admitted. Preserve motor-vehicle involvement, territorial crash-year allocation, source 30-day classification, provisional ARF, exact fatal-person counts and the compatible Vintage 2024 midyear population denominator.

    The source covers complete county-based MSAs, rather than a city centre or the old PM footprint. Unknown injury categories and individual death times remain unknown. Missing point coordinates do not remove county-qualified cases. Later-vintage comparisons are separate; no resident or visitor injury probability is inferred.

    Large original archives retain ordered binary parts and a whole-file manifest. A part is not a standalone ZIP. Exact reconstruction, source-specific government-data terms and attributions, reviewed method versions and current/historical status accompany the public records.

    Open JSON ↗Human source desk ↗Initial global convention ↗
    Inspect only the currently admitted observations ↗

    03 / Evidence contract

    Keep the distinctions that make data useful.

    Editorial guides

    Authored interpretation, suggested itineraries and practical questions. Each city keeps its actual review date and official reference links. Narrative assessments never enter index scores.

    Geographic scope

    City-context observations and national context are separate arrays. Each record retains its own boundary label. A national average does not establish a local condition.

    Observation provenance

    Records include a stable ID, source reference, publisher, unit, observation period, retrieval date and limitation. Derived changes retain their calculation and base/current values.

    Dated ranking baseline

    Exact inherited score values and recomputed ordinal positions are explicitly labeled legacy-unverified. Category snapshots can have different dates. No official Civometra city results are available.

    Three different clocks: period describes the measured condition; retrieved_at describes the source check; reviewed_at describes editorial review. Save snapshot_id with your output. The v1 path names the schema generation; it is not an immutable archive of every past snapshot.

    Working with a comparison

    Read the boundary before the number.

    An evidence view includes every matching observation. Ordering is available only when records share an observation period, boundary type, unit, source table and universe, with one record per city. If those conditions change, ordering_status becomes suspended-incomparable and ordered_rows is empty; original records remain in observations.

    Exact point-estimate ties share competition ranks: 1, 1, 3. ACS estimates retain their source-reported margin of error, 90% confidence level, universe and table ID. A numerical order does not establish statistically different positions. The country atlas describes published city coverage, with national context separate; it supplies no countrywide ranking.

    Inspect an ACS evidence view →Explore the coverage atlas →

    04 / Trace an answer

    A citation is part of the answer.

    1. 1

      For a narrative claim

      Use citation.title, citation.author, the guide’s reviewed_at date and citation.canonical_url. Link to the human city or research page.

    2. 2

      For a numerical observation

      Also identify the original publisher, indicator, unit, observation period and geography. Link source_url, and retain the source_ref and observation ID for your audit trail.

    3. 3

      For a rank or score

      Keep its legacy-unverified status and calculation_date alongside the number. Do not describe an inherited score as a current Civometra result.

    Read a complete citation-ready city brief

    05 / For research tools and assistants

    Readable by people. Structured for tools.

    Public JSON, Markdown and discovery files make these resources easier to inspect and integrate. An application can retrieve them as part of a ChatGPT, Claude or other research workflow. Availability does not imply a native integration, guaranteed model access or inclusion in AI search results.

    ChatGPT and Claude directory submissions remain unsubmitted. A working public endpoint is not a directory listing or a completed platform review. See integration details for the read-only MCP server and partner gateway.

    Discovery map

    A concise guide to datasets, methods and attribution.

    /llms.txt

    Editorial text collection

    A bounded collection of city guides, category frameworks and research articles.

    /llms-full.txt

    OpenAPI definition

    Explicit GET operations for the files in this snapshot.

    /api/v1/openapi.json

    The practical boundaries

    Transport. Published HTTP GET snapshots, with no API key, writes, server-side filtering or live booking data. Cross-origin browser access depends on the serving host; use a same-origin browser request or a server-side client. Cache responsibly and handle failed requests.

    MCP and partner access. The read-only MCP service and protected partner REST gateway are separate from this static API. The gateway requires authorized credentials for server-side use; static snapshots remain public GET files. Inspect the service endpoints and connection contract.

    Reuse. This interface grants no new content licence. Editorial material retains its existing rights; third-party observations keep the original publisher’s terms. Consult the source catalog and primary agency before redistributing source material.

    MethodologyEditorial standardsRelease historyMedia resources