June 8, 2026 · 7 min read · Data
Corrected 14 November 2026: the example responses below are what the API returns today; the earlier version showed routes the API does not have (/v1/cities/nyc, /v1/cities/london), made-up ids, and a Tokyo rollup across its wards that our data does not hold.
When "New York City" really means 87 neighborhoods.
A user types "best restaurants in NYC." Your raw geo store has Manhattan, Brooklyn, Queens, the Bronx, Staten Island, plus 80-something named neighborhoods inside them. If you naively run that query against a flat city table, you get either nothing or five disjoint slices. Megacity rollup is the unglamorous primitive that makes travel APIs actually usable.
Megacities aren't single rows
Open Street Map will happily tell you that Hell's Kitchen, Times Square, the Upper West Side, Williamsburg and Astoria are all valid place polygons. Foursquare has venues attributed to each. Wikidata has sub-articles. None of these are wrong — they're just at the wrong granularity for "give me NYC restaurants."
The problem is structurally identical across every megacity:
- London: 32 boroughs plus the City of London, with hundreds of named neighborhoods on top (Soho, Shoreditch, Camden).
- Paris: 20 arrondissements, plus the Petite Couronne suburbs (Boulogne, Saint-Denis) that tourists treat as Paris.
- Tokyo: 23 special wards, each its own legal municipality, plus 26 cities and 5 towns within Tokyo Metropolis.
- Berlin: 12 boroughs, 96 localities.
- São Paulo: 32 subprefectures, 96 districts.
- Mexico City: 16 alcaldías plus hundreds of colonias.
- Istanbul: 39 districts spanning two continents.
What the rollup looks like in the API
Each city in /v1/cities has two flags that do the work:
GET /v1/cities?iso_alpha2=US&limit=200
[
{
"id": "e507fa30-77fd-4856-b977-89850bec437c",
"name": "New York City",
"iso_alpha2": "US",
"master_score": "91.37",
"tier": "World-Class",
"child_city_count": 87,
"aggregates_neighborhoods": true,
...
},
...
]
aggregates_neighborhoods: true tells the API to fan out:
any sub-query (restaurants, hotels, attractions) traverses the
children before ranking. child_city_count is metadata —
it tells your client how big the underlying union is, which matters
if you're showing a "based on N neighborhoods" disclosure or
paginating.
The same shape works in London:
GET /v1/cities?iso_alpha2=GB&limit=200
[
{
"id": "0c921b48-94e3-4e9c-b319-f9c93e5a4625",
"name": "London",
"iso_alpha2": "GB",
"master_score": "88.61",
"tier": "World-Class",
"child_city_count": 16,
"aggregates_neighborhoods": true,
...
},
...
]
London's 16 child places today are Acton, Bexley, Brent, Chelsea, Croydon, Enfield Town, Greenwich, Harrow, Hounslow, Islington, Kingston upon Thames, Poplar, Putney, Sutton, Tottenham and Twickenham: places within London, not its 32 boroughs.
Why this isn't a join you should write yourself
Every team that builds a travel product hits this and reaches for the same instinct: parent_id self-join, recursive CTE, done. It looks easy until you handle:
- Conflicting parents. Is Yokohama part of Tokyo? For tourists, kind of. For administrative data, no. The rollup needs an opinion that's defensible.
- Asymmetric naming. "Greater London" is a real legal entity. "Greater New York" isn't, but tourists assume it includes Jersey City and Hoboken.
- Tourism vs administrative boundaries. Vatican City is its own country, but every Rome itinerary includes it.
- Sub-rollups. A query for "Manhattan restaurants" should aggregate across Midtown, SoHo, Tribeca, Hell's Kitchen — but stop before pulling in Brooklyn.
Each of these is an editorial call. We make the call once, you consume it as a flag.
Practical example: ranking restaurants in Tokyo
GET /v1/restaurants?city_id=43f3e49b-6d7c-4b69-bc47-6a999cb06eca&limit=8
# returns restaurants of Tokyo and of its child places, ordered by
# rating. Tokyo's row rolls up 2 child places today, Adachi and
# Asakusa; Shibuya, Shinjuku, Minato, Chuo and the other wards are
# not attached to it.
The rollup only reaches the children a city row has. For Tokyo that is two places today, so a "Tokyo" query does not yet cover the central wards; query them by their own city ids as well.
What this means for your product
Megacity rollup is one of those primitives that's invisible when it works and catastrophic when it doesn't. The bug manifests as "user typed Paris, our app showed 12 results from one arrondissement, competitor showed 47 from across the city." You don't lose users to that bug — they leave silently and never come back.
Use aggregates_neighborhoods as a feature flag in
your UI: when it's true, you can confidently show "across N
neighborhoods" framing. When it's false, the city is small
enough that one query is the answer.