{
  "schema_version": "1.0.0",
  "api_version": "v1",
  "snapshot_id": "bctl-7eb7c1c7524bb525d233",
  "edition": {
    "name": "Civometra Index",
    "label": "2026 Q4",
    "status": "research",
    "methodology_version": "1.0.0",
    "official_city_results_released": false
  },
  "as_of": "2026-10-27",
  "as_of_meaning": "Last complete source check recorded in the research snapshot; not a common observation period or a new editorial review. A separately validated source may have a later retrieved_at date; inspect each observation.",
  "dates": {
    "source_checked_at": "2026-10-27",
    "last_complete_source_check_at": "2026-10-27",
    "latest_observation_retrieved_at": "2026-10-27",
    "observations_changed_at": "2026-10-21",
    "editorial_review_earliest": "2026-10-11",
    "editorial_review_latest": "2026-10-27",
    "urban_context_retrieved_at": "2026-10-26",
    "index_evidence_evaluated_at": "2026-10-27",
    "air_quality_retrieved_at": "2026-10-26",
    "geography_candidates_evaluated_at": "2026-10-26",
    "protocols_prepared_at": "2026-10-26",
    "scoring_geographies_reviewed_at": "2026-10-26",
    "pm25_evidence_reviewed_at": "2026-10-26",
    "heat_evidence_reviewed_at": "2026-10-26",
    "rental_vacancy_evidence_reviewed_at": "2026-10-26",
    "housing_supply_evidence_reviewed_at": "2026-10-26",
    "life_expectancy_evidence_reviewed_at": "2026-10-26",
    "road_deaths_evidence_reviewed_at": "2026-10-27"
  },
  "publisher": {
    "name": "BestCityToLive Intelligence",
    "initiative": "AINT.app",
    "url": "https://aint.app"
  },
  "notice": "Civometra is a research edition, with no official quarterly city results. Current engine-accepted index inputs are explicitly separated from editorial guides, contextual observations and inherited legacy scores. An accepted indicator does not establish an eligible city score or ranking. National context never measures a city.",
  "rights": "No new licence is granted by this API. BestCityToLive editorial material retains its existing rights. Third-party observations and sources retain their own licences and attribution requirements; consult each primary publisher before reuse. Source catalog links do not imply permission to reproduce full source content.",
  "kind": "catalog",
  "id": "catalog",
  "self": "https://bestcitytolive.com/api/v1/catalog.json",
  "canonical_url": "https://bestcitytolive.com/developers",
  "description": "Public static HTTP GET snapshots for readers, research tools and AI-assisted workflows. No API key or server-side query support. Filter the downloaded collection locally.",
  "counts": {
    "cities": 63,
    "countries": 41,
    "evidence_views": 8,
    "categories": 17,
    "articles": 10,
    "observations": 229,
    "source_references": 529,
    "observatory_cities": 63,
    "index_indicators": 30,
    "index_evidence_cells": 1890,
    "distinct_urban_centres": 62,
    "urban_destination_crosswalks": 63,
    "air_context_records": 55,
    "air_context_cities": 25,
    "geography_candidate_cities": 63,
    "measurement_protocol_drafts": 24,
    "frozen_protocols": 6,
    "current_index_inputs": 145,
    "distinct_index_measurements": 143,
    "reviewed_scoring_geographies": 145
  },
  "endpoints": [
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/catalog.json",
      "description": "Discovery catalog, snapshot identity and limitations"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/cities.json",
      "description": "All city summaries with JSON and Markdown links"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/categories.json",
      "description": "Lifestyle decision guides and dated legacy category snapshots"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/countries.json",
      "description": "Country/territory coverage with covered city links and separate national context"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/evidence-views.json",
      "description": "Comparable contextual series with sorting scope, shared ties and uncertainty retained"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/observatory.json",
      "description": "Every destination, urban-centre context and all configured index-evidence cells, including missing evidence"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/index-history.json",
      "description": "Complete reviewed input history, exact current selections, immutable review/protocol/geography/source identities and unchanged UTC age eligibility"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/index-metrics.json",
      "description": "All fixed metric definitions, published pillar weights, units, anchors and coverage gates"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/urban-centres.json",
      "description": "Deduplicated physical urban centres and the destination crosswalk; projected population and contextual geography"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/air-quality.json",
      "description": "Separate EPA monitor summaries and EEA modelled two-year city exposure; original scope, quality flags, dates and archives; no rankings or index inputs"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/geography-candidates.json",
      "description": "All destination geography candidates, shared and unresolved identities, original official codes and unknown vintages; no scoring approvals"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/index-protocols.json",
      "description": "Draft operational measurement protocols and the independently enforced evidence-admission policy; drafts are not frozen approvals"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/index-observations.json",
      "description": "Only current engine-accepted index inputs, with deduplicated physical measurements, actual eras, scope, frames and a separately dated historical review"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/scoring-geographies.json",
      "description": "Reviewed source-specific area bindings and exact archive identities, limited to their approved protocol scope"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/heat-exposure.json",
      "description": "Reviewed historical annual and dependent monthly modelled heat exposure; source eras, archives and exact current engine match retained"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/housing-supply.json",
      "description": "Reviewed gross new-build completions per preliminary midyear population; exact source identities, construction milestone and both licences"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/life-expectancy.json",
      "description": "Original ABS Persons three-year life expectancy at birth; source precision, native GCCSA geometry, point adapter, method unknowns and rights"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/road-deaths.json",
      "description": "Territorial FARS motor-vehicle-involved traffic deaths per same-year midyear residents; provisional source classification, complete MSA counties, unknowns, separate source universes and exact split archives"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/road-deaths.md",
      "description": "Citation-friendly road source desk with alphabetical source operands and all63 destination availability"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/rental-vacancy.json",
      "description": "Scoped Canadian CMA2021 CMHC October survey rates, original quality/precision and conditional downstream licence; not a global ranking"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/articles.json",
      "description": "Research articles and explainers"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/observations.json",
      "description": "Contextual observations with source, period, unit and geography"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/sources.json",
      "description": "Deduplicated primary-source reference catalog"
    },
    {
      "method": "GET",
      "url": "https://bestcitytolive.com/api/v1/openapi.json",
      "description": "OpenAPI 3.1 specification listing every concrete GET URL"
    }
  ],
  "discovery": {
    "llms": "https://bestcitytolive.com/llms.txt",
    "llms_full": "https://bestcitytolive.com/llms-full.txt",
    "rss": "https://bestcitytolive.com/feed.xml",
    "human_documentation": "https://bestcitytolive.com/developers"
  },
  "transport": {
    "authentication": "none",
    "query_parameters": "unsupported",
    "pagination": "none; bounded complete snapshots",
    "mutations": "unsupported",
    "cors": "Host-dependent. Cross-origin browser fetch support is not asserted; use a same-origin browser or server-side client."
  },
  "citation_policy": "Cite the human canonical URL and displayed editorial review/publication date for narrative claims. Cite the original publisher, indicator, observation period and geography for quantitative claims. Preserve the snapshot_id for reproducibility. Country context and legacy scores must retain their labels.",
  "index_readiness": {
    "methodology_url": "https://bestcitytolive.com/methodology",
    "readiness_url": "https://bestcitytolive.com/data/index-readiness.json",
    "evidence_url": "https://bestcitytolive.com/data/index-evidence.json",
    "observatory_url": "https://bestcitytolive.com/api/v1/observatory.json",
    "metric_definitions_url": "https://bestcitytolive.com/api/v1/index-metrics.json",
    "verified_results_available": false
  },
  "urban_context": {
    "source": {
      "name": "GHS Urban Centre Database 2025",
      "publisher": "European Commission, Joint Research Centre",
      "release": "GHS-UCDB R2024A",
      "version": "V1-2",
      "sourceUrl": "https://data.jrc.ec.europa.eu/dataset/1a338be6-7eaf-480c-9664-3a8ade88cbcd",
      "downloadUrl": "https://jeodpp.jrc.ec.europa.eu/ftp/jrc-opendata/GHSL/GHS_UCDB_GLOBE_R2024A/GHS_UCDB_THEME_GLOBE_R2024A/GHS_UCDB_THEME_GENERAL_CHARACTERISTICS_GLOBE_R2024A/V1-2/GHS_UCDB_THEME_GENERAL_CHARACTERISTICS_GLOBE_R2024A_V1_2.zip",
      "methodologyUrl": "https://human-settlement.emergency.copernicus.eu/documents/GHSL_UCDB_R2024_V1_2.pdf",
      "populationSourceUrl": "https://data.jrc.ec.europa.eu/dataset/2ff68a52-5b5b-4a22-8f40-c41da8332cfe",
      "retrievedAt": "2026-10-26",
      "boundaryNotice": "Morphological urban centres are not municipalities or commuting functional urban areas. These contextual records are excluded from Civometra scoring.",
      "populationNotice": "2025 population is a short-range projection, based on GHS-POP R2023A. It is not a current census count. Density is a derived projection divided by footprint area.",
      "licence": "European Commission reuse notice: reuse authorised with source acknowledgement; underlying third-party terms remain applicable.",
      "distinctCentres": 62,
      "matchedCities": 63,
      "sourceCRS": "ESRI:54009",
      "archiveUrl": "/data/source-frames/ghsl-ucdb-general-v1_2-bc879d823205.zip",
      "archiveSHA256": "bc879d82320504f89df2041b7936221c8239cd808abe93980493aed062b4f3d6",
      "citation": "Mari Rivero et al. (2024). GHS-UCDB R2024A – GHS Urban Centre Database 2025. European Commission, JRC. doi:10.2905/1a338be6-7eaf-480c-9664-3a8ade88cbcd. V1-2.",
      "source_ref": "source-1b70a5d9dd81952b",
      "download_source_ref": "source-8a0d0bd6daefabdd",
      "methodology_source_ref": "source-c063b7ae6502f0c7",
      "population_source_ref": "source-f3189a9194a27e72"
    },
    "distinct_urban_centres": 62,
    "destination_crosswalks": 63,
    "reference_epoch": "2025",
    "population_is_projection": true,
    "index_eligible": false,
    "url": "https://bestcitytolive.com/api/v1/urban-centres.json"
  },
  "air_quality_context": {
    "url": "https://bestcitytolive.com/api/v1/air-quality.json",
    "record_count": 55,
    "covered_city_count": 25,
    "evidence_types": [
      "modelled-city-period-average",
      "monitor-annual-summary"
    ],
    "index_eligible": false,
    "notice": "Separate contextual evidence classes: EPA annual monitor/site summaries and EEA two-year modelled city/greater-city exposure. Monitor rows are not city averages, independent urban areas or population-weighted FUA exposure. EEA values are 2024–2025 modelled city-boundary averages, not annual monitor statistics. Do not pool, average, rank or convert these classes into index inputs. Missing destinations are not assigned a substitute value."
  },
  "geography_candidates": {
    "url": "https://bestcitytolive.com/api/v1/geography-candidates.json",
    "evaluated_at": "2026-10-26",
    "summary": {
      "destinations": 63,
      "oecd_boundary_matched_destinations": 41,
      "distinct_oecd_boundary_candidates": 40,
      "oecd_identifier_only_destinations": 2,
      "oecd_unresolved_destinations": 22,
      "estimated_fua_2015_point_matches": 63,
      "eurostat_2024_research_point_matches": 18,
      "approved_scoring_boundaries": 0
    },
    "scoring_approved": false
  },
  "index_protocols": {
    "url": "https://bestcitytolive.com/api/v1/index-protocols.json",
    "admission_policy_url": "https://bestcitytolive.com/data/index-admission-policy.json",
    "official_results_released": false
  }
}