The Cities Engine is a working atlas of 11,422 cities, more than 200 metrics, and 24 urban archetypes, built so that the people closest to local problems can find what already works and help it travel to the next city. This piece opens the hood: the software that runs it, the data behind it, and the way we group cities so that comparisons actually mean something.

Under the hood: the programs that make it run

The application itself is a Next.js web app, written in React and TypeScript, and deployed on Vercel. When you load a city, the app fetches a compact catalogue first, then fills in analytics and per-city detail in the background, so the map stays responsive while the heavier numbers arrive.

Behind the app sits Supabase, which gives us a PostgreSQL database, user accounts and sign-in, and row-level security that decides who can see and change what. Sensitive credentials — the keys for our AI providers and search tools — are kept in Supabase Vault rather than in the code. The heavy analytical work (aggregating, ranking and matching across thousands of cities) is pushed down into the database itself as purpose-built functions, so a single question doesn't drag the whole dataset across the network.

The things you see and touch are drawn with dedicated tools: interactive maps are rendered with Mapbox, and the dashboards and charts with ECharts. The look and feel comes from an in-house design system we call “c7”.

Two kinds of intelligence run on top of the data. The first is semantic search: organisation records are turned into numerical “embeddings” stored in Postgres (using the pgvector extension), so a search for an idea — not just a keyword — can find the closest-matching groups. The second is João, the in-app assistant (a friendly Brazilian sea turtle), built on the CopilotKit framework. João can search and rank cities, run bounded analytical queries, and even drive the interface for you. Crucially, João can never run arbitrary database commands: every tool it uses is defined and permission-checked on the server, and any change it proposes goes through a human confirmation step.

Feeding the directory is a separate discovery pipeline that runs off-platform on Modal (a Python cloud service). For a given city it drafts locale-appropriate search queries, searches the live web with Exa, removes duplicates, vets each candidate with an AI model, enriches the survivors, and follows partner links one hop outward. Everything it finds lands in a review queue — nothing is published to the directory without a person approving it. Finally, a small read-only interface (an MCP server) lets trusted tools pull monthly “what changed” summaries without touching anything they shouldn't.

The data, and how we made it

The backbone of the platform is the Global Human Settlement Urban Centre Database (GHS-UCDB), a European Commission dataset describing roughly 11,400 urban centres worldwide — their population, economic output, built form, climate, road density and exposure to hazards like flooding. On top of that we layer several trusted global sources: the World Bank's What a Waste datasets for municipal solid waste, Transparency International's Corruption Perceptions Index for governance quality, the World Happiness Report, and Natural Earth country boundaries used to place each city in the right nation.

An ingestion pipeline loads these raw sources into the database, reconciles them geographically (matching each city to its country, even when names and spellings disagree), and stitches organisations to the cities they work in.

Some of the most useful numbers are ones we modelled rather than measured. Because ground-truth waste figures exist for only a fraction of cities, we trained models to estimate waste generation, composition and collection for every city across 2019, 2025 and 2030; we project GDP forward; and we compute an Urban Sustainability Risk Score. We are deliberately candid about these: modelled values are flagged as synthetic, they carry uncertainty ranges, and some are harder to predict than others — city-level waste generation, in particular, is genuinely difficult to forecast, while collection and disposal pathways are more reliable. The goal is honest estimates with their limits attached, not false precision.

In practice, this data supports three everyday jobs: benchmarking a city against genuinely comparable peers; forecasting waste out to 2030 for planning; and giving a single city a clear, at-a-glance risk picture.

Archetypes of cities

Comparing a wealthy, cold European capital directly to a fast-growing tropical one rarely tells you much. So instead of grouping cities by geography, we group them by two questions: what can a city afford to do, and what shape is it. We call the result the Capacity-Morphology Matrix.

First, every city is sorted into one of six “universes” — a combination of climate (tropical or non-tropical) and institutional capacity (fragile, transitional or high-capacity, blending wealth and governance). Then, within each universe, an unsupervised machine-learning method (K-means, with four groups per universe) clusters cities purely by their physical structure, using five features: density, sprawl (built-up area per person), verticality (building height), road connectivity, and primacy (whether it dominates its country). Six universes with four clusters each gives us 24 archetypes, each named and profiled by Google's Gemini models based on its statistical fingerprint.

As with any model, there are caveats worth stating plainly: some of the underlying built-form imagery dates from 2015–2018, so the fastest-changing cities may have moved on, and forcing exactly four groups per universe is a simplification we accept for the sake of consistency. Used with that in mind, the archetypes are a powerful way to find your city's true peers — and to learn from what's working in cities that share its challenges.

That's the machine. If you'd like to see what it feels like to use, start with a first look at the Cities Engine.