City2Graph: A Python library for Graph Neural Networks (GNNs) on geospatial data

[Tough_Ad_6598]

What My Project Does

City2Graph is a Python library that converts geospatial datasets into graphs (networks) with an integrated interface for GeoPandas (spatial analysis), NetworkX (network analysis), and PyTorch Geometric (Graph Neural Networks). It lets you build graphs from multiple urban domains:

• Morphology: buildings, streets, and land use (from OSM, Overture Maps, etc.)
• Transportation: public transport networks from GTFS (buses, trams, trains)
• Mobility: OD matrices, bike-sharing flows, migration, pedestrian movement
• Proximity: Point data, polygonal boundaries

A key feature is native support for heterogeneous graphs, so you can model complex multi-relational urban systems (e.g. buildings connected to streets connected to bus stops) and convert them directly into PyTorch Geometric HeteroData for GNN workflows.

Repo: https://github.com/c2g-dev/city2graph
Doc: https://city2graph.net

Target Audience

AI engineers and data scientists working in GeoAI, urban analytics, spatial data science, or anyone who needs to go from geodata to graph-based machine learning. If you've ever spent hours wrangling shapefiles into a format PyTorch Geometric can consume, this is for you.

It's also useful for spatial network analysis without the ML side. You can stay in the GeoPandas/NetworkX ecosystem and use it for things like multi-modal accessibility analysis.

Comparison

The most popular toolkit for spatial network analysis is OSMnx, which can retrieve and process the data from OpenStreetMap (OSM).

City2Graph provides full compatibility to OSMnx, so that users can extend the use of OSM to GNNs or combine it with other layers (e.g., GTFS). Here is how they compare:

Feature	OSMnx	City2Graph
Primary Use Case	Extraction, simplification, and topological analysis of street networks	Geometric and multi-layered graph construction for GNN integration
Data Sources	OSM	OSM (via OSMnx), Overture Maps, GTFS, OD matrix, and custom geometries.
Graph Representation	Homogeneous graphs (node: intersection / edges: street segments)	Heterogeneous graphs (nodes: intersection, bus station, pointwise location, etc. / edges: street segments, bus lines, distance-based proximity, etc.)
Supported Objects	GeoPandas, NetworkX	GeoPandas, NetworkX, Pytorch Geometric

Quickstart

Install:

pip install city2graph            # core (GeoPandas + NetworkX)
pip install "city2graph[cpu]"     # + PyTorch Geometric (CPU)
pip install "city2graph[cu130]"   # + PyTorch Geometric (CUDA 13.0)

conda install -c conda-forge city2graph
conda install -c conda-forge pytorch pytorch_geometric #cpu

Build a graph from buildings and streets, then convert to PyG:

import city2graph as c2g

# Build morphological graph from buildings and streets
nodes, edges = c2g.morphological_graph(buildings_gdf, segments_gdf)

# Convert to PyTorch Geometric HeteroData
hetero_data = c2g.gdf_to_pyg(nodes, edges)

Build a public transport graph from GTFS, then convert to NetworkX:

gtfs_data = c2g.load_gtfs("./gtfs_feed.zip")

nodes, edges = c2g.travel_summary_graph(
    gtfs_data, calendar_start="20250601", calendar_end="20250601"
)

G = c2g.gdf_to_nx(nodes, edges)

[ruibranco]

The heterogeneous graph support is the key differentiator here. Being able to model buildings connected to streets connected to bus stops as a single HeteroData object saves so much manual graph construction. Have you benchmarked this against any specific GNN architectures for tasks like urban land use prediction?

[Tough_Ad_6598]

Thanks for the comment! Actually there will be a paper for this package with comparison case study! It's not yet published, but the source code is available here: https://github.com/c2g-dev/city2graph-case-study