June 12, 2026 · 6 min read · Data
Corrected 14 November 2026: the example responses below are what the API returns today; the earlier version showed a route the API does not have (/v1/cities/tokyo), made-up fields, and a rollup of all 23 wards that our data does not hold: Tokyo's row rolls up two child places today.
Tokyo's 23 special wards: not boroughs, not cities, something else.
Tokyo doesn't have a mayor. It has a governor of Tokyo Metropolis, plus 23 special-ward mayors, plus 26 city mayors, plus a handful of town and village heads. There is no single municipal entity called "Tokyo." Every travel app pretends there is, and so must your data.
The legal structure
Tokyo Metropolis (Tōkyō-to) is a prefecture. Inside it sit:
- 23 special wards (tokubetsu-ku): Chiyoda, Chuo, Minato, Shinjuku, Bunkyo, Taito, Sumida, Koto, Shinagawa, Meguro, Ota, Setagaya, Shibuya, Nakano, Suginami, Toshima, Kita, Arakawa, Itabashi, Nerima, Adachi, Katsushika, Edogawa. Each has its own mayor, ward office, and budget. Legally they're closer to cities than to boroughs.
- 26 western cities: Hachioji, Tachikawa, Musashino, Mitaka, etc. Suburban-to-rural municipalities that nobody calls "Tokyo" outside of postal addresses.
- 5 towns and 8 villages: Including the Izu and Ogasawara island chains, which are legally Tokyo but 1,000 km offshore.
When a tourist says "Tokyo," they mean the 23 wards plus maybe Mitaka (for Ghibli Museum) and Tachikawa (sometimes, for Showa Memorial Park). They almost never mean Hachioji or the Ogasawara Islands.
Why this breaks naive APIs
A flat city table that treats Shibuya, Shinjuku, and Minato as separate top-level cities (because legally they are) will fail on every "Tokyo" query. The user types "best ramen in Tokyo," your code looks up city_id for "Tokyo," gets back nothing or the prefecture-level row with no venues attached, and returns an empty list.
A flat city table that treats only "Tokyo Metropolis" as the entity has the opposite problem: every venue is attributed to the prefecture, you can't distinguish Shibuya from Adachi, and your "near me" queries lose all neighborhood-level granularity.
Both are wrong. The correct shape is a hierarchical city that exposes a Tokyo entity for human-facing queries while preserving ward-level attribution underneath.
What the API returns
GET /v1/cities?iso_alpha2=JP&limit=1
[
{
"id": "43f3e49b-6d7c-4b69-bc47-6a999cb06eca",
"name": "Tokyo",
"iso_alpha2": "JP",
"master_score": "92.35",
"tier": "World-Class",
"child_city_count": 2,
"aggregates_neighborhoods": true,
...
}
]
A query for restaurants in Tokyo fans out across the Tokyo row and its child places and ranks the results as one list. Today those children are only Adachi and Asakusa; Shibuya, Shinjuku, Minato, Chuo and the other wards are separate city rows, not yet attached to Tokyo, so query them by their own ids as well:
GET /v1/restaurants?city_id=43f3e49b-6d7c-4b69-bc47-6a999cb06eca&limit=5
Each row in the answer carries its licence tag.
The same pattern, elsewhere
Tokyo isn't unique in being legally fragmented:
- Seoul: 25 autonomous districts (gu) plus a Special Metropolitan City status that makes it co-equal with provinces.
- Berlin: A city-state, simultaneously a city and one of the 16 federal Bundesländer.
- Vienna: A federal state and a municipality in the same body.
- Shanghai & Beijing: Province-level municipalities that report directly to Beijing.
- Brussels: 19 communes that together form the Brussels-Capital Region. Tourists never distinguish.
For each, aggregates_neighborhoods: true is the
flag that says "treat this as one city for query purposes,
even though the law says otherwise." The
child_city_count tells you how big the union is.
One practical caveat
The 23-ward rollup excludes the western cities and the islands. If your user is genuinely planning a trip to Hachioji or Ogasawara, the right call is to query those as separate cities. The Tokyo rollup is a tourist abstraction; don't confuse it with administrative truth, and don't confuse administrative truth with what tourists need.