City2Graph: Geospatial Graphs for Network Analysis and GNNs¶

City2Graph is a Python library that turns geospatial data into analysis-ready graphs. Build networks from buildings, streets, public transport feeds, origin–destination matrices, zones, and points of interest; analyse them with NetworkX or convert them to PyTorch Geometric for Graph Neural Networks (GNNs).

City2Graph provides one interface across GeoPandas, NetworkX, PyTorch Geometric, and rustworkx. It preserves geospatial geometries and attributes while converting between graph representations, so the same graph can support mapping, spatial network analysis, and machine-learning workflows.

Choose a geospatial graph workflow¶

Why City2Graph?¶

• Geospatial inputs stay geospatial. Nodes and edges retain geometries, coordinate reference systems, and attributes in GeoDataFrames.
• Heterogeneous graphs are first-class. Multiple node and relation types can represent buildings, streets, transit stops, zones, and amenities together.
• Conversions work both ways. Move between GeoDataFrames, NetworkX, PyTorch Geometric Data/HeteroData, and rustworkx without rebuilding the graph for every analysis tool.
• Open urban data is supported. Load or process Overture Maps, OpenStreetMap-derived data, GTFS, GBFS, OD matrices, and common GIS layers.

Quickstart¶

pip install city2graph

This installs the graph construction and spatial network analysis features. Install city2graph[cpu] or a CUDA extra when you also need PyTorch Geometric. See the installation guide for a package comparison, supported Python and CUDA versions, and conda-forge instructions.

import city2graph as c2g

# Buildings + street segments -> heterogeneous morphological graph
nodes, edges = c2g.morphological_graph(
    buildings_gdf, segments_gdf, center_point, distance=500
)

import city2graph as c2g

gtfs = c2g.load_gtfs("itm_london_gtfs.zip")

# Stop-to-stop travel-time graph from a GTFS feed
nodes, edges = c2g.travel_summary_graph(
    gtfs, calendar_start="20250601", calendar_end="20250601"
)

import city2graph as c2g

# OD matrix + zone geometries -> weighted spatial graph
nodes, edges = c2g.od_matrix_to_graph(
    od_df, zones_gdf,
    source_col="origin", target_col="destination",
    weight_cols=["flow"], zone_id_col="zone_id",
)

import city2graph as c2g

# Proximity graphs over points of interest
knn_nodes, knn_edges = c2g.knn_graph(poi_gdf, k=5)
wax_nodes, wax_edges = c2g.waxman_graph(poi_gdf, r0=100, beta=0.5)

# Queen contiguity between polygonal zones
w_nodes, w_edges = c2g.contiguity_graph(wards_gdf, contiguity="queen")

import city2graph as c2g

# Compose relations: amenity -> segment -> segment -> amenity
metapaths = [[("amenity", "is_nearby", "segment"),
              ("segment", "connects", "segment"),
              ("segment", "is_nearby", "amenity")]]

nodes, edges = c2g.add_metapaths(
    (nodes, edges), metapaths, edge_attr="distance_m", edge_attr_agg="sum"
)

import city2graph as c2g

# GeoPandas -> NetworkX
G = c2g.gdf_to_nx(nodes, edges)

# GeoPandas -> PyTorch Geometric
data = c2g.gdf_to_pyg(nodes, edges)

# PyTorch Geometric -> GeoPandas
nodes, edges = c2g.pyg_to_gdf(data)

# PyTorch Geometric -> NetworkX
G = c2g.pyg_to_nx(data)

# NetworkX -> rustworkx
G_rx = c2g.nx_to_rx(G_nx)

# rustworkx -> NetworkX
G_nx = c2g.rx_to_nx(G_rx)

Examples¶

Applied projects¶

Tutorials¶

Browse all examples →

Frequently asked questions¶

What data can City2Graph convert into graphs?¶

City2Graph supports buildings, street segments, tessellations, Overture Maps features, GTFS and GBFS feeds, origin–destination matrices, points of interest, polygonal zones, and existing GeoDataFrame or NetworkX graphs. The workflow table links each input to its builder and tutorial.

Is PyTorch required?¶

No. The core installation builds and analyses geospatial graphs with GeoPandas, NetworkX, and rustworkx without installing PyTorch. PyTorch and PyTorch Geometric are optional dependencies for GNN-ready Data and HeteroData tensors.

Can graphs be converted between GeoPandas, NetworkX, and PyTorch Geometric?¶

Yes. City2Graph supports round-trip conversion between GeoDataFrames, NetworkX, and PyTorch Geometric, including heterogeneous graphs. See the graph conversion API for the supported functions.

How does City2Graph relate to OSMnx?¶

OSMnx is a focused toolkit for downloading and analysing OpenStreetMap street networks. City2Graph can use street data from OSMnx and combines it with buildings, Overture Maps, transit, mobility, proximity, and heterogeneous graph workflows. The two libraries are complementary.

How should City2Graph be cited?¶

Use the project DOI when citing City2Graph in research:

@software{sato2025city2graph,
  title = {City2Graph: Transform geospatial relations into graphs for spatial network analysis and Graph Neural Networks},
  author = {Sato, Yuta},
  year = {2025},
  url = {https://github.com/c2g-dev/city2graph},
  doi = {10.5281/zenodo.15858845},
}