---
title: "Curated cities ranked by a composite desirability score"
method: GET
path: "/v1/cities"
tags: ["data"]
---

# Curated cities ranked by a composite desirability score

`GET /v1/cities`

## Request

- Base URL: `https://api.travelminds.ai`
- URL: `https://api.travelminds.ai/v1/cities`
- Auth: none declared

Filtered by country (iso_alpha2) and minimum score (min_score). The child_city_count and aggregates_neighborhoods markers indicate which rows are megacity rollups (NYC, London, Paris, Tokyo). tier_version pins against a specific quarterly snapshot for reproducibility (default = current; see /v1/cities/tier-versions).

## Query parameters

- `limit` integer
- `offset` integer
- `iso_alpha2` string, nullable
- `min_score` number, nullable
- `tier_version` integer, nullable

## Headers

- `authorization` string, nullable
- `x-rapidapi-proxy-secret` string, nullable
- `x-rapidapi-user` string, nullable
- `x-tmai-proxy-secret` string, nullable
- `x-tmai-proxy-provider` string, nullable
- `x-tmai-proxy-user` string, nullable

## Response `200`

Successful Response

- CityOut[]
  - `id` string, required: Canonical city UUID. Stable across reads.
  - `name` string, required: City name in source script (en preferred when both exist).
  - `iso_alpha2` string, nullable: ISO-3166 alpha-2 country code, uppercase (e.g. 'IN', 'JP').
  - `population` integer, nullable: Latest known population from source metadata.
  - `latitude` string, nullable: Decimal degrees, signed (string for arbitrary precision).
  - `longitude` string, nullable: Decimal degrees, signed (string for arbitrary precision).
  - `master_score` string, nullable: Composite TMAIV2 master score, rounded to 2dp. Range 0-1.
  - `tier` string, nullable: Internal classification tier (e.g. 'tier-1', 'tier-2').
  - `child_city_count` integer, nullable: Number of child neighborhoods/boroughs aggregated under this row (W52 rollup).
  - `aggregates_neighborhoods` boolean: True when this is a megacity row that rolls up child neighborhoods (NYC, London, Paris, Tokyo).
  - `license` string, nullable: License id from the registry (D7 posture). See GET /v1/licenses.
  - `license_url` string, nullable: Public URL of the license text.
  - `attribution_required` boolean, nullable: True if downstream use must cite TravelMindsAI / the upstream source.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/travelminds/apis/travelmindsai-api-gateway.md) · [All operations](https://skmtc.dev/travelminds/apis/travelmindsai-api-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/travelminds/apis/travelmindsai-api-gateway/revisions/d05c8634e340?raw)