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:

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:

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.

Sign up — free See India coverage →