Graphways

Graphways is a Rust-powered Python library for fast local reachability, routing, and isochrone analysis on OpenStreetMap road networks. It builds a reusable SpatialGraph once, then runs repeated network-aware queries directly in process without deploying a routing server.

Graphways is designed for workflows that need the street network as a practical analysis primitive: accessibility studies, urban analytics, site selection, agent-based simulations, notebook exploration, and application backends that need low-latency local graph operations.

Installation

Install the Python package from PyPI:

pip install graphways

Or add the Rust crate to Cargo.toml:

[dependencies]
graphways = "0.4.0"

To build the Python extension from source, install Rust and maturin, then run:

maturin develop

Usage

import graphways as gw

origin = (38.9097, -77.0432)
destination = (38.8977, -77.0365)

graph = gw.SpatialGraph.from_place(
    "Washington, DC",
    network="walk",
    max_dist=10_000,
)

isochrones = graph.isochrone(origin, minutes=[10, 20, 30])
route = graph.route(origin, destination, max_snap_m=100)
reachable = graph.reachable(origin, minutes=15, max_snap_m=100)

print(route.duration_s, route.distance_m)
route_geojson = route.to_geojson()
iso_geojson = isochrones[0].to_geojson()

SpatialGraph is the central object. Reachability and network-time prism queries return lightweight graph views over the parent graph, so inspection and GeoJSON export do not copy the full road network.

reachable.nodes()
reachable.edges_geojson()
reachable.route(origin, destination)

prism = graph.prism(
    origin=origin,
    destination=destination,
    max_minutes=45,
    stop_minutes=10,
    buffer_minutes=5,
)

possible_stops = prism.nodes()
slack_polygon = prism.slack_polygon(min_slack_s=5 * 60)

Routes, snap diagnostics, and isochrones return structured Python objects. Call .to_geojson() when you need serialized GeoJSON for mapping or data tools.

Features

• Build reusable walking, biking, driving, and custom-access OSM road graphs.
• Load from Overpass XML, existing OSM XML strings, or local OSM PBF files.
• Query nearest nodes with an R-tree spatial index.
• Compute reachability over the road network from a single origin.
• Generate isochrones with one graph search and triangulated contour extraction.
• Route point-to-point with distance, duration, geometry, and cumulative times.
• Build network-time prisms for "what can I visit between A and B?" analysis.
• Export nodes, edges, routes, POIs, and isochrones as GeoJSON.

Documentation

Start with the quickstart, then see the Python graph API and Rust API notes.

The examples directory and documentation show common workflows:

• building graphs from places, XML, and PBF files
• computing walking and driving isochrones
• routing between coordinates
• querying reachable nodes and graph views
• working with POIs and GeoJSON output

Network Services

SpatialGraph.from_place(...), gw.geocode(...), and POI fetching use public OpenStreetMap services by default. Graphways sends a descriptive User-Agent, rate-limits Nominatim geocoding requests, and retries transient 429 / 5xx responses.

For production workloads, local mirrors, or stricter service policies, configure the service layer with environment variables:

GRAPHWAYS_OVERPASS_URL=https://overpass-api.de/api/interpreter
GRAPHWAYS_NOMINATIM_URL=https://nominatim.openstreetmap.org/search
GRAPHWAYS_USER_AGENT="your-app/1.0 contact@example.com"
GRAPHWAYS_CACHE_DIR=/path/to/graphways-cache

Use SpatialGraph.from_pbf(...) when you need fully offline graph construction.

Performance

Graphways is optimized for repeated local queries over the same area. Graph construction is paid once; subsequent reachability, routing, and isochrone queries reuse the in-memory graph and spatial index.

The benchmark suite compares steady-state graphways queries against NetworkX / OSMnx baselines and includes staged timings for graph construction versus per-query work:

python benchmarks/comparison.py

Current benchmarks are intentionally kept in benchmarks/ rather than treated as a universal claim. Performance depends on graph size, network profile, machine, cache state, and output geometry settings.

License

Graphways is open source and licensed under the MIT license. OpenStreetMap data is licensed separately; when using OSM-derived outputs, follow the OpenStreetMap attribution guidelines.