City2Graph: Turn Any City Into a Graph Neural Network

⬅️ Back to Projects

🏙️ City2Graph · GitHub · BSD 3-Clause

City2Graph is a Python library that turns geospatial datasets into graph structures ready for Graph Neural Networks. Streets become edges. Buildings become nodes. Public transport networks become heterogeneous graphs with multiple relationship types.

Yuta Sato built it at the University of Liverpool’s Geographic Data Science Lab, and it shows — this is a research-grade tool designed for real urban analytics, not a toy.

What It Actually Does

It takes geospatial data from sources like OpenStreetMap, Overture Maps, and GTFS feeds, and converts them into NetworkX graphs or PyTorch Geometric Data objects. The library covers five domains:

Morphology — Convert buildings, street segments, and land use into graphs that capture the physical form of a city. You can pull data from OSM or Overture Maps and get a graph within a specified walking distance.

Transportation — Load GTFS feeds into DuckDB-backed tables and build public transport networks. Buses, trams, trains. The library handles the calendar logic, stop sequences, and route aggregation.

Contiguity — Build Queen or Rook adjacency graphs from administrative boundaries or land cover polygons. Classic spatial weights matrix stuff, but output as a graph.

Mobility — Convert origin-destination matrices into weighted graphs. Migration flows, bike-sharing trips, pedestrian counts. Edge weights carry the flow values.

Proximity — Connect points of interest using fixed-radius, Waxman, or KNN methods. Euclidean, Manhattan, or network distance metrics.

The Heterogeneous Bit

This is what sets it apart from simpler spatial analysis tools. City2Graph models complex urban systems as heterogeneous graphs — different node types (buildings, amenities, stops, zones) connected by different edge types (is_nearby, connects, covers, is_contiguous_with). You can define metapaths that traverse multiple relationship types, like connecting amenities through street segments.

All of this can be exported to PyTorch Geometric’s HeteroData for GNN training.

Installation

pip install city2graph or conda install -c conda-forge city2graph. For GPU support, pip install "city2graph[cu130]".

Why It Stands Out

There are plenty of tools that can convert spatial data to graphs. Most are point solutions for one domain. City2Graph is the first library I have seen that treats the whole pipeline — from raw OSM exports and GTFS feeds to PyTorch Geometric tensors — as a single workflow. It integrates GeoPandas, NetworkX, and PyTorch Geometric with minimal friction between them.

If you work in GeoAI, urban analytics, or spatial data science and have ever wanted to run a GNN on actual city data, this is worth a look.

Crepi il lupo! 🐺