Source-linked AI summary
Modeling and Analyzing Urban Networks and Amenities with OSMnx
Geoff Boeing
TL;DR
Urban network research has been constrained by fragmented data processing and undocumented modeling decisions. This article documents OSMnx’s modern, modular capabilities for downloading, modeling, analyzing, and visualizing OpenStreetMap networks and amenities. It presents the package as a reusable tool that improves transparency and reproducibility, while noting that Python’s relative slowness remains a dependency-ecosystem constraint.
Problem
Historically, constructing suitable OpenStreetMap street-network models required extensive ad hoc code and undocumented decisions, limiting interpretability and replicability.
Method
The article documents OSMnx’s modern modular organization, functionality, usage, graph-modeling theory, software-development lessons, and open-science implications.
Results
OSMnx provides an open-source tool that automatically models urban networks and amenities from OpenStreetMap while exposing theoretically informed, documented workflows.
Takeaways & Limitations
OSMnx supports reproducible urban modeling by making spatial extents and modeling decisions explicit and providing reusable network and amenity analyses.
Takeaways & Limitations
Python’s relative slowness remains a constraint, although newer Python releases and Rust-based libraries may improve future performance.
Abstract
from arXiv · showhide
OSMnx is a Python package for downloading, modeling, analyzing, and visualizing urban networks and any other geospatial features from OpenStreetMap data. A large and growing body of literature uses it to conduct scientific studies across the disciplines of geography, urban planning, transport engineering, computer science, and others. The OSMnx project has recently developed and implemented many new features, modeling capabilities, and analytical methods. The package now encompasses substantially more functionality than was previously documented in the literature. This article introduces OSMnx's modern capabilities, usage, and design -- in addition to the scientific theory and logic underlying them. It shares lessons learned in geospatial software development and reflects on open science's implications for urban modeling and analysis.
1. Introduction
Urban network and geospatial-feature modeling supports research on travel, accessibility, public health, sustainability, and spatial equity, but historical data and tooling limitations constrained empirical urban network science. The article presents OSMnx’s expanded capabilities and modern organization as a documented, reusable tool for urban analytics.
- Urban network and geospatial-feature modeling underpins analyses of travel behavior, accessibility, public health, sustainability, and spatial equity.
- Historically, limited data availability, inconsistent digitization, and insufficient reusable tools constrained reproducibility, generalizability, scalability, and usefulness.
- Open science promotes transparent, interpretable, reproducible, and accessible scientific processes and results, with open-source software playing a central role.
- OSMnx is a free, open-source Python package for downloading, modeling, analyzing, and visualizing urban networks and geospatial features from OpenStreetMap.
- The article documents OSMnx’s expanded functionality, improved performance, stabilized API, modular structure, applications, and scientific underpinnings.
2. Street Network Models and Analysis
Street-network analysis represents infrastructure as spatial graphs combining topology and geometry, then applies geometric, topological, and path-based measures. OpenStreetMap offers broad data coverage, but historically required extensive ad hoc processing whose undocumented decisions reduced interpretability and replicability.
- Model Fundamentals: Spatial graphs represent both network topology and geometry, while street networks are commonly modeled with intersections and dead-ends as nodes and street segments as edges.
- Street Network Analysis: Street-network analysis uses geometric measures such as intersection density, segment length, street density, and circuity to characterize network form.
- Street Network Analysis: Topological measures including average node degree and centrality describe connectedness, alternate routing, and potential chokepoints.
- Street Network Analysis: Shortest-path analyses measure accessibility between origins and amenity destinations, while disaster analyses simulate emergency responses or evacuations and compare outcomes across communities.
- Street Network Tools and Data: OpenStreetMap provides worldwide public geospatial data, but constructing suitable street graphs historically required cumbersome extraction and extensive ad hoc code.
- Street Network Tools and Data: Undocumented decisions about directedness, planarity, self-loops, parallel edges, and cul-de-sacs accumulated to inhibit interpretability and replicability.
3.1. Overview
OSMnx automatically builds spatialized NetworkX graph models from OpenStreetMap data, reducing ad hoc coding and standardizing previously fragmented modeling decisions. Its adoption spans diverse urban research and practice domains.
- OSMnx automatically downloads OpenStreetMap data and constructs spatialized NetworkX graph models for networks anywhere in the world.
- The package replaces numerous ad hoc modeling decisions with a documented, transparent, common tool.
- OSMnx has become a standard tool for retrieving urban data and modeling street networks across fields including transport planning, vehicle-sharing systems, and urban centrality modeling.
3.2. Modular Organization
OSMnx organizes its functionality into modules for geocoding, feature retrieval, network downloading, and graph modeling. Its network workflow supports configurable queries and graph representations, while the public API documents the package’s available functionality.
- Modular Organization: OSMnx is organized as 17 modules using NetworkX and GeoPandas data structures and interacting with public geospatial APIs.
- Geocoding and Features: The geocoder retrieves coordinates, boundaries, and OpenStreetMap elements, while feature tools download amenities and other geospatial features as GeoDataFrames.
- Modeling Networks: The graph module downloads spatial networks using built-in network types or custom OverpassQL filters and models them as graphs.
- Modeling Networks: OSMnx models networks as primal, nonplanar, weighted, directed multigraphs that represent one-way and bidirectional flow and preserve interchange topology.
- Modeling Networks: The package buffers query boundaries by 500 meters before truncation and returns the largest weakly connected component by default, with connectivity configurable.
- Modular Organization: Table 1 lists the OSMnx v2.0 public API modules and the functionality each exposes.
3.2.4. Graph Simplification
OSMnx simplifies raw OpenStreetMap topology so graph nodes represent meaningful intersections or dead-ends and edges represent street segments. These transformations improve model accuracy, preserve useful geometry and attributes, and reduce computational cost.
- Edge simplification: Edge simplification merges adjacent edges while retaining complete edge geometry and aggregating attributes from the original OpenStreetMap ways.It removes nonintersection and non-dead-end nodes so edges better represent street segments.
- Node consolidation: Node consolidation merges nearby nodes that represent one real intersection, including clusters created by complex intersections, traffic circles, or divided roads.Merged node attributes can be aggregated into a single value.
- Benefits: Simplification produces more accurate network measures by avoiding intersection overcounting and preserving street segment lengths.The resulting graph better represents the real-world network.
- Benefits: Fewer nodes and edges allow many graph algorithms to complete much faster, especially for large urban networks where runtime is a major constraint.The reduction can be substantial without loss of accuracy.
- Related graph operations: OSMnx also converts graph representations among MultiDiGraph, MultiGraph, DiGraph, and node or edge GeoDataFrame forms, and supports reprojection and file export.Supported outputs include GraphML, GeoPackage, and OSM XML.
3.2.6. Elevation
OSMnx extends street-network analysis with elevation, routing, network statistics, orientation measures, and visualization. These capabilities connect terrain and spatial structure to graph-based urban analysis.
- Elevation: OSMnx adds elevation attributes from local raster files or the Google Maps Elevation API, enabling edge-grade and street-steepness analysis.Elevation change can also be used in routing impedance functions.
- Routing: Nearest-node and nearest-edge matching converts coordinate lists, such as geocoded addresses, into graph locations for path solving.The distance module uses a spatial index and vectorized operations.
- Routing: Shortest-path routing supports weights including distance, travel time, and elevation change, with multiprocessing parallelization.Missing maximum speeds can be imputed from observed values for other edges of the same type, although the imputation can be imprecise.
- Network measures: OSMnx calculates geometric and topological measures such as intersection density, circuity, average node degree, centrality, street bearings, and orientation entropy.These measures use an undirected representation to avoid double-counting bidirectional edges of two-way streets.
- Visualization: The plot module visualizes routes, building footprints, orientation polar histograms, figure-ground diagrams, and interactive maps of networks and amenities.Figure 2 illustrates orientation entropy through polar histograms and corresponding street maps.
3.3. Installation and Configuration
OSMnx provides installation resources and configuration controls for using the package across reproducible geospatial workflows. Users can install it through standard Python repositories and configure data retrieval behavior.
- Installation: The package is publicly hosted on GitHub and is installable from PyPI or Anaconda.The documentation provides installation instructions.
- Installation: The Getting Started guide and Examples Gallery provide tutorials, feature demonstrations, and sample code for new users.These resources support step-by-step onboarding.
- Configuration: OSMnx settings control logging, server-response caching, server endpoints, and related package behavior.Users can point endpoints to locally hosted instances.
- Configuration: Users can configure OSMnx to retrieve historical OpenStreetMap snapshots as of a specified date.This setting supports time-specific data retrieval.
4. Lessons Learned in Geospatial Software
The paper presents OSMnx’s evolution from a monolithic prototype into a modular, documented, typed, and automated open-source geospatial package. It uses this development history to identify practices supporting maintainability, interoperability, and open science.
- Project evolution: OSMnx began as a monolithic and brittle 2016 beta package before growing through research needs, user feedback, bug reports, feature requests, and community contributions.The project’s development became increasingly community-driven as its user base grew.
- Project evolution: The 2021 version 1.0 release reorganized functionality into thematic modules, making the API more comprehensible, discoverable, and predictable.The redesign included API-breaking changes considered worthwhile for the new modular structure.
- Project evolution: Version 2.0, released at the end of 2024, added features and under-the-hood practices intended to improve user-friendliness and long-term sustainability.The paper uses this milestone to reflect on API design, development pipelines, dependency ecosystems, and open science.
- API design: The v2.0 API exposes 17 public modules and emphasizes parsimony and clarity through few necessary functions and parameters.These streamlining efforts support long-term maintainability and the DRY principle.
- Documentation and typing: Documentation combines a Getting Started guide, examples gallery, detailed docstrings, and automatically updated online API references.Docstrings describe purposes, scientific bases, parameters, and return values.
- Documentation and typing: Full type annotation provides user-facing type hints and enables optional static-type enforcement in the development pipeline.The stated goal is to reduce bugs caused by unexpected data types.
- Development pipeline: OSMnx automates testing, packaging, deployment, dependency compatibility checks, type checking, and documentation building through DevOps workflows.The project uses tools including GitHub, pytest, mypy, Typeguard, numpydoc, Sphinx, DockerHub, and PyPI.
- Dependency ecosystem: The package builds on Python’s geospatial ecosystem, using required dependencies for core functionality and optional dependencies for extended capabilities.This separation supports lightweight minimal installations or more extensive environments.
5. Conclusion
The OSMnx project advances open science by maintaining a theory-informed, reusable tool for modeling and analyzing urban networks and amenities worldwide. The article documents OSMnx’s modern capabilities and theoretical foundations while sharing software-development lessons and emphasizing benefits from a shared tools commons.
- 5. Conclusion: Open, reusable tools developed by scholarly experts are presented as a path toward better and more open science.The authors connect shared tools with benefits across disciplines.
- 5. Conclusion: OSMnx supports reproducible urban network analysis through explicit spatial extents, documented modeling decisions, and theoretically informed graph models.Its models are primal, nonplanar, directed, weighted multigraphs that can include self-loops.
- 5. Conclusion: The project reduces repeated ad hoc modeling work by providing reusable methods for urban networks and amenities from OpenStreetMap data.This lets researchers avoid reinventing basic modeling decisions for each project.
- 5. Conclusion: The article documents OSMnx’s modern organization, capabilities, and theoretical underpinnings while sharing lessons from ten years of geospatial software development.It also offers suggestions for others developing similar projects.
Notes
The notes clarify a graph-theoretic distinction, identify the documented OSMnx release, and point readers to the project’s software and documentation resources.
- Notes: In spatial network analysis, connectivity has a distinct graph-theoretic definition but is less useful because approximate planarity makes it equal to 1 for almost all street networks.The footnote distinguishes graph-theory terminology from its usefulness in spatial network analysis.
- Notes: The article documents OSMnx version 2.0.1, released in January 2025.The version and release date are given in a footnote.
- Notes: The OSMnx source code, documentation, and examples gallery are hosted on GitHub or Read the Docs.The footnote lists the project’s source, documentation, and examples locations.