osmnx-paper.tex

%!TeX program = pdflatex
% Modeling and Analyzing Urban Networks and Amenities with OSMnx
% Author: Geoff Boeing
% Web: https://geoffboeing.com
% Repo: https://github.com/gboeing/osmnx-paper

\RequirePackage[l2tabu,orthodox]{nag} % warn if using any obsolete or outdated commands
\documentclass[12pt,letterpaper]{article} % document style

% import encoding and font packages for pdflatex, in order
\usepackage[T1]{fontenc} % output T1 font encoding (8-bit) so accented characters are a single glyph
\usepackage[utf8]{inputenc} % allow input of utf-8 encoded characters
\usepackage{ebgaramond} % document's serif font
\usepackage{tgheros} % document's sans serif font

% import language and regionalization packages, in order
\usepackage[strict,autostyle]{csquotes} % smart and nestable quote marks
\usepackage[USenglish]{babel} % automatically regionalize hyphens, quote marks, etc
\usepackage{microtype} % improves text appearance with kerning, etc
\usepackage{setspace} % configure spacing between lines

% import everything else
\usepackage{abstract} % allow full-page title/abstract in twocolumn mode
\usepackage{amsmath} % better math symbology
\usepackage{authblk} % footnote-style author/affiliation info
\usepackage{booktabs} % better looking tables
\usepackage{caption} % custom figure/table caption styles
\usepackage{datetime} % enable formatting of date output
\usepackage[final]{draftwatermark} % watermark paper as a draft
\usepackage{endnotes} % enable endnotes
\usepackage{geometry} % configure page dimensions and margins
\usepackage{graphicx} % better inclusion of graphics
\usepackage{hyperref} % hypertext in document
\usepackage{natbib} % author-year citations w/ bibtex, including textual and parenthetical
\usepackage{orcidlink}
\usepackage{rotating} % rotate wide tables or figures on a page to make them landscape
\usepackage{titlesec} % custom section and subsection heading
\usepackage{url} % make nice line-breakable urls

% print only the month and year when using \today
\newdateformat{monthyeardate}{\monthname[\THEMONTH] \THEYEAR}

\newcommand{\myname}{Geoff Boeing}
\newcommand{\myemail}{boeing@usc.edu}
\newcommand{\myaffiliation}{University of Southern California}
\newcommand{\paperdate}{\monthyeardate\today}
\newcommand{\papertitle}{Modeling and Analyzing Urban Networks and Amenities with OSMnx}
\newcommand{\papercitation}{Boeing, G. \the\year. \papertitle. Working paper.\ \href{https://geoffboeing.com/publications/osmnx-paper/}{https://geoffboeing.com/publications/osmnx-paper/}}
\newcommand{\paperkeywords}{network science, openstreetmap, street networks, transportation, urban planning}


% location of figure files, via graphicx package
\graphicspath{{./figures/}}

% configure the page layout, via geometry package
\geometry{
    paper=letterpaper, % paper size
    top=3.8cm, % margin sizes
    bottom=3.8cm,
    left=4cm,
    right=4cm}
\setstretch{1} % line spacing
\clubpenalty=10000 % prevent orphans
\widowpenalty=10000 % prevent widows

% set section/subsection headings as the sans serif font, via titlesec package
\titleformat{\section}{\normalfont\sffamily\large\bfseries\color{black}}{\thesection.}{0.3em}{}
\titleformat{\subsection}{\normalfont\sffamily\small\bfseries\color{black}}{\thesubsection.}{0.3em}{}

% make figure/table captions sans-serif small font
\captionsetup{font={footnotesize,sf},labelfont=bf,labelsep=period}

% configure pdf metadata and link handling, via hyperref package
\hypersetup{
    pdfauthor={\myname},
    pdftitle={\papertitle},
    pdfsubject={\papertitle},
    pdfkeywords={\paperkeywords},
    pdffitwindow=true, % window fit to page when opened
    breaklinks=true, % break links that overflow horizontally
    colorlinks=false, % remove link color
    pdfborder={0 0 0} % remove link border
}
%\doublespacing
\begin{document}

\title{\papertitle~\footnote{Citation info: \papercitation}}
\author[]{\myname~\footnote{Correspondence: \href{mailto:\myemail}{\myemail}}~~\orcidlink{0000-0003-1851-6411}}
\affil[]{\myaffiliation}
\date{\paperdate}

\maketitle

\begin{abstract}

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. Accordingly, this paper introduces the OSMnx package's new capabilities, usage, and design---in addition to the scientific theory and logic underlying them. Finally, it reflects on tool building in geographical information science and the implications for urban modeling and analysis in the mode of open science.

\end{abstract}

\section{Introduction}

Modeling networked urban infrastructure---such as streets, rails, canals, etc.---and geospatial features---such as amenities, points of interest, etc.---underpins research into travel behavior, accessibility, public health, sustainability, and spatial equity. This research spans the disciplines of urban morphology \citep[e.g.,][]{gervasoni_calculating_2017,dacci_signature_2019,coutrot_entropy_2022}, transportation planning \citep[e.g.,][]{merchan_quantifying_2020,liao_disparities_2020,natera_orozco_data-driven_2020}, and network science \citep[e.g.,][]{feng_spatial_2020,yin_multi-task_2020,young_automatic_2020}. However, traditional limitations of data availability, inconsistent digitization standards, and lack of well-documented, reusable tools historically limited the reproducibility, generalizability, scalability, and usefulness of empirical urban network modeling \citep{liu_generalized_2022}. In response to similar challenges across many disciplines, the open science movement calls for reproducibility and transparency---in particular through building, sharing, and utilizing open-source analytical tools \citep{rey_show_2009,singleton_establishing_2016,rey_pysal:_2019,kedron_reproducibility_2021}. Like their peers across disciplines, urban researchers need good tools for good science.

This paper describes OSMnx, a Python package that allows users to easily download, model, analyze, and visualize urban networks and geospatial features from OpenStreetMap data. Users can download and model walking, driving, biking, or custom networks with a single line of code and then analyze and visualize them. Users can easily work with urban amenities and points of interest, building footprints, transit stops, elevation data, street orientations, speed and travel time, and routing.

The OSMnx package was first released as a beta in 2016 and that inchoate version was documented in a preliminary paper \citep{boeing_osmnx:_2017}. At the time, it was the first tool enabling users to automatically download and model the street network geometry and topology of any city in the world as a graph and then analyze and visualize it \citep{boeing_right_2020}. It has since become a widespread tool for a broad range of urban modeling and analysis in the intervening years \citep[e.g.,][]{coutrot_entropy_2022,dacci_signature_2019,feng_spatial_2020,gervasoni_calculating_2017,liao_disparities_2020,natera_orozco_data-driven_2020,yin_multi-task_2020,young_automatic_2020}.

However, since its initial release, the package has evolved substantially by expanding its functionality, improving performance, and stabilizing a user-friendly API.\@ To document these start-of-the-art capabilities and their scientific underpinnings in the literature, this paper presents OSMnx's current modular structure, functionality, and uses for urban modeling and analysis. The following section introduces the theory, data, and tools of street network modeling and analysis, including OSMnx's place in that landscape. Then it presents the OSMnx package's functionality, organization, and usage. Finally this paper concludes with a brief discussion of implications for urban network analysis and tool building in geographical information science.

\section{Street Network Models and Analysis}

Numerous sources cover spatial network theory and analysis \citep[e.g.,][]{tinkler_graph_1979,barnes_graph_1983,gastner_spatial_2006,barthelemy_spatial_2011,ducruet_spatial_2014,fischer_spatial_2014,marshall_street_2018}. This section focuses on street networks and offers an overview of necessary concepts then briefly reviews the current tool landscape.

\subsection{Model Fundamentals}

Real-world networks are commonly modeled as mathematical \textit{graphs} \citep{trudeau_introduction_1994, barthelemy_spatial_2022}. A graph, $G$, is a data structure consisting of two sets: one set, $N$, contains \textit{nodes} that are linked to each other by the second set, $E$, containing node pairs called \textit{edges}. Let $G = (N, E)$ and $\{u, v\} \subseteq N$ and $\{u, v\} \in E$. We can say for graph $G$ that: 1) edge $\{u, v\}$ links nodes $u$ and $v$, 2) edge $\{u, v\}$ is \textit{incident} to $u$ and to $v$, 3) $u$ is \textit{adjacent} to $v$ and vice versa, and 4) $u$ and $v$ are \textit{neighbors} \citep{newman_networks:_2010}. An adjacency matrix can fully represent a graph by defining these adjacent node pairs.

A node's \textit{degree} is how many edges are incident to that node. For example, a node with degree 2 has two incident edges which are consequently adjacent to each other. An edge can be \textit{undirected} (linking two nodes bidirectionally), \textit{directed} (linking one-way from a source node to a target node), or a \textit{self-loop} (linking one node back to itself). A graph with directed edges is a directed graph, or \textit{digraph}. A graph that allows multiple edges to link a single pair of nodes is a \textit{multigraph} and those multiple edges are called \textit{parallel} edges.

A \textit{path} is a sequence of edges linking a sequence of nodes. The graph \textit{distance} between two nodes is the count of edges in the shortest such path between them. A \textit{weighted} graph's distance is the sum of some edge impedance attribute (e.g., length or time) along the shortest path minimizing that sum. A directed graph is strongly \textit{connected} if a path exists between each ordered pair of nodes, and it is weakly connected if such a path exists only if its edges are undirected. A disconnected graph contains multiple connected \textit{components}---each a disjoint set of nodes forming its own connected subgraph.

Spatial networks' nodes and/or edges are embedded in space \citep{barthelemy_spatial_2022}. Spatial graphs thus model both topology and geometry \citep{fischer_spatial_2014}.\ \textit{Topology} refers to the structure and configuration of the nodes and edges, whereas \textit{geometry} encompasses positions, lengths, angles, etc. A \textit{planar} graph's topology can be represented in a two-dimensional plane such that its edges intersect only at nodes \citep{barthelemy_modeling_2008}. Most street networks are nonplanar due to the occasional presence of overpasses and underpasses, but their spatial embedding and \enquote{approximate} planarity constrain their topological characteristics relative to other kinds of complex networks \citep{boeing_planarity_2020}. A \textit{primal} graph models a street network's intersections and dead-ends as nodes and its street segments as edges \citep{porta_network_2006-1}. A \textit{line} graph (sometimes called a \textit{dual} graph) inverts this topology to instead model streets as nodes and their intersections as edges \citep{porta_network_2006}, though it discards much of the network's geometry \citep{ratti_space_2004}.

\subsection{Street Network Analysis}

Many common geometric measures of spatial networks are often applied to street networks. In general, these should use undirected representations of the graph to avoid double-counting bidirectional streets relative to one-ways. Intersection density (i.e., the count of nodes with degree >1, normalized by network area) is perhaps the most common such measure of network \enquote{grain} in transport planning and urban design \citep[e.g.,][]{ewing_travel_2010}. The average street segment length (i.e., mean edge length) offers a linear proxy of block size. Street density is the sum of edge lengths normalized by network area. Circuity can take on different interpretations, including average circuity: the sum of edge lengths divided by the sum of great-circle distances between adjacent node pairs, representing the inverse of network edge straightness \citep{boeing_urban_2019}.

Additionally, many topological measures in network science are often applied to street networks \citep{barthelemy_spatial_2011}. The \textit{average node degree} (i.e., mean number of edges incident to the nodes) indicates graph \textit{connectedness}\endnote{The separate term \textit{connectivity} has a distinct definition in graph theory, but is less useful for spatial network analysis because approximate planarity sharply constrains it: almost all street networks have connectivity equal to 1.} and is perhaps the most common topological measure in transport planning and urban design \citep[e.g.,][]{barrington-leigh_century_2015,barrington-leigh_more_2017,barrington-leigh_global_2020}. Networks with high connectedness can be more robust against perturbation as they offer alternate routing options if parts of the network fail \citep{boeing_resilient_2024}. Various measures of \textit{centrality} are also common \citep{crucitti_centrality_2006}. For example, a node's \textit{betweenness centrality} measures the share of all graph shortest paths that pass through the node \citep{barthelemy_betweenness_2004,barthelemy_self-organization_2013}. The graph's maximum betweenness centrality indicates the share of shortest paths that rely on its most important node: high values suggest possible chokepoints that represent single points of failure, such as a bridge connecting a city's halves across a river \citep{boeing_resilient_2024}.

In street network analysis, researchers use these geometric and topological measures to characterize a network's form. Such analyses often also employ path solving \citep{miller_measuring_1999,wang_road_2020}. For example, accessibility analyses solve shortest paths (e.g., by length or travel time) from origin nodes (e.g., homes) to destination nodes representing the locations of amenities (e.g., workplaces, schools, transit stops, parks, greengrocers, hospitals, etc.) to measure access \citep{foti_behavioral_2014,liu_generalized_2022}. Disaster analyses often simulate emergency responses or evacuations along the network to understand the flows following a disaster \citep{sasabe_road_2020,tamakloe_finding_2021}. These kinds of analyses can reveal differential outcomes for different communities or locations with the city, offering guidance for practitioners' interventions.

\subsection{Street Network Tools and Data}

Various tools exist to model and analyze spatial networks like street networks. For example, ESRI's ArcGIS software includes a Network Analyst extension and QGIS offers plug-ins for network analysis. However, such GIS tools' network capabilities are usually fairly limited. Conversely, dedicated network analysis tools such as Gephi, igraph, graph-tool, and NetworkX offer robust network analysis functionality but limited geospatial capabilities. Other dedicated spatial network tools exist, often for specific analytical purposes, including PySAL spaghetti for network inference \citep{gaboardi_spaghetti_2021,rey_pysal_2022}, Pandana for accessibility analysis \citep{foti_behavioral_2014}, momepy for urban morphology \citep{fleischmann_momepy_2019}, and stplanr for transport planning \citep{lovelace_stplanr_2019}.

Street network data come from various sources, including governmental sources like the US Census Bureau's TIGER/Line shapefiles which represent network geometry but lack sufficient topological information to build a properly nonplanar model. Alternatively, OpenStreetMap offers a worldwide, public web mapping platform and geospatial database that anyone contribute to, with some editorial oversight, and includes streets, highways, transit, buildings, footpaths, cycleways, points of interest, and political boundaries \citep{jokar_arsanjani_openstreetmap_2015}. Although its coverage varies, it includes network geometry and topology and its data quality is generally high---particularly so in urban areas, with notable exceptions in China and sub-Saharan Africa \citep{barron_comprehensive_2014,barrington-leigh_worlds_2017}. OpenStreetMap's data model comprises three \textit{element} types: \textit{nodes} (points), \textit{ways} (either open ways representing lines or closed ways representing polygons), and \textit{relations} (i.e., between nodes and/or ways). These elements can possess one or more \textit{tags}: key-value pairs containing attribute data. OpenStreetMap data are available to download from third-party services, such as Geofabrik, and web APIs including Overpass and Nominatim.

The problem, however, was historically that building a street network model from raw OpenStreetMap data was fairly difficult. The Overpass API can be cumbersome to extract the right data to construct an appropriate graph model. Analysts usually had to write extensive ad hoc code to process the raw data into a useful graph model and then write more code to conduct analyses. Their decisions on how to handle ubiquitous street network characteristics---such as directedness, planarity, self-loops, parallel edges, or culs-de-sac---frequently went undocumented. With every research team writing its own ad hoc code, innumerable small modeling decisions inevitably would go unreported in the resulting peer-reviewed literature---but these small decisions add up to significantly restrict interpretability and replicability.

OSMnx fits into this landscape by allowing users to build a spatial network model anywhere in the world by automatically downloading raw data from OpenStreetMap and building a NetworkX model with spatial information. This allows users to sidestep the ad hoc coding and replace the many small modeling decisions with a well-documented and transparent common tool. Accordingly, OSMnx has become a standard tool in the literature for both retrieving OpenStreetMap data broadly and for modeling street networks specifically \citep{boeing_right_2020}. The following section provides a current\endnote{This working paper documents OSMnx version 2.0.0 prior to its official release.} introduction to the package's organization, capabilities, and usage.

\section{The OSMnx Package}

OSMnx (pronounced as the initialism: \enquote{oh-ess-em-en-ex}) is a free, open-source, and fully type-hinted package written in pure Python. The package is structured as a collection of modules that organize related functionality (Table~\ref{tab:osmnx_modules}). It is built on top of and uses the data structures of NetworkX \citep{hagberg_exploring_2008}, a network analysis Python package, and GeoPandas \citep{van_den_bossche_geopandasgeopandas_2024}, a Python package for working with geospatial dataframes. It interacts with three public web APIs to collect data: the OpenStreetMap Nominatim API, the Overpass API, and the Google Maps Elevation API (or equivalent with the same interface). This section presents OSMnx's organization and capabilities.

\begin{table*}[htbp]
    \centering
    \caption{The OSMnx public API's modules and the functionality they expose.}\label{tab:osmnx_modules}
    \begin{tabular}{lp{10cm}}
        \toprule
        Module &  Functionality \\
        \midrule
        \texttt{bearing}  & Calculate graph edge compass bearings and orientation entropy.\\
        \texttt{convert}  & Convert graph to/from different data types.\\
        \texttt{distance}  & Calculate spatial distances and find nearest graph node/edge(s) to point(s).\\
        \texttt{elevation}  &  Attach node elevations from raster files or a Google Maps compatible elevation API, and calculate edge grades.\\
        \texttt{features}  &  Download OSM geospatial features' geometries and attributes, such as points of interest, building footprints, transit stops, etc.\\
        \texttt{geocoder}  & Geocode place names or addresses or retrieve OSM elements by place name or ID, via the Nominatim API.\\
        \texttt{graph}  & Download and create graphs from OSM data, using filters to query the Overpass API for built-in network types or a custom filter.\\
        \texttt{io}  & Save/load graphs to/from GraphML, GeoPackage, or OSM XML files.\\
        \texttt{plot} & Visualize street networks, routes, orientations, and geospatial features.  \\
        \texttt{projection}  &  Project spatial graph to a different coordinate reference system.\\
        \texttt{routing}  &  Calculate graph edge speeds, travel times, and weighted shortest paths between nodes.\\
        \texttt{settings}  & Configure global package settings.\\
        \texttt{simplification}  & Simplify and consolidate spatial graph nodes and edges.\\
        \texttt{stats}  &  Calculate geometric and topological network measures.\\
        \texttt{truncate}  & Truncate spatial graph by distance, bounding box, or polygon.\\
        \texttt{utils}  & General utility functions.\\
        \texttt{utils\_geo}  & Miscellaneous geospatial utility functions.\\
        \bottomrule
    \end{tabular}
\end{table*}

\subsection{Geocoding and Querying}

OSMnx geocodes place names and addresses with the Nominatim API\@. Users can use the \texttt{geocoder} module to geocode place names or addresses to latitude-longitude point coordinates. Or, they can retrieve place boundaries or any other OpenStreetMap elements by name or ID.\@ Using the \texttt{features} and \texttt{graph} modules, as described below, users can download OpenStreetMap data from the Overpass API by latitude-longitude point coordinates, address, bounding box, bounding polygon/multipolygon, or place name (e.g., neighborhood, city, county, etc.).

\subsection{Urban Amenities}

Using OSMnx's \texttt{features} module, users can search for and download any geospatial features (e.g., building footprints, grocery stores, schools, public parks, transit stops, etc.) from the OpenStreetMap Overpass API as a GeoPandas \texttt{GeoDataFrame} object. This uses OpenStreetMap tags to search for matching elements.

\subsection{Modeling Networks}

OSMnx models spatial networks as primal, nonplanar, weighted, directed multigraphs with possible self-loops---specifically, these are NetworkX \texttt{MultiDiGraph} data structures \citep{hagberg_exploring_2008}. Using OSMnx's \texttt{graph} module, users can download any spatial network data (such as streets, paths, rail, canals, power lines, etc.) from the Overpass API and model them as a \texttt{MultiDiGraph}.

OSMnx models a one-way street as a single directed edge from node $u$ to node $v$, but a bidirectional street is modeled with two reciprocal directed edges (with identical geometries)---one from $u$ to $v$ and another from $v$ to $u$---to represent both possible directions of flow. Because these graphs are nonplanar, they correctly model the topology of interchanges, overpasses, and underpasses. That is, edge crossings in a two-dimensional plane are not nodes in an OSMnx model unless they represent true junctions in the three-dimensional real world.

The \texttt{graph} module uses filters to query the Overpass API:\@ users can either specify a built-in network type or provide their own custom filter written in OverpassQL.\@ Under the hood, OSMnx does several things to generate the best possible model. It initially buffers the query area by 500 meters to create the initial graph before truncating it to the user's desired query area. This ensures accurate streets-per-node counts by attenuating graph perimeter effects. As the graph may contain many small disconnected components around the perimeter, by default it returns the largest weakly connected component. OSMnx also automatically simplifies the graph topology as discussed below.

\subsection{Graph Simplification}

The \texttt{simplification} module automatically processes the network's topology from the original raw OpenStreetMap data to ensure that individual nodes represent individual intersections or dead-ends and edges represent the street segments that link them. This graph simplification is of two primary types---edge simplification and node consolidation---described in detail in \citet{boeing_graph_2024} and summarized here.

\begin{figure*}[tbp]
    \centering
    \includegraphics[width=1\textwidth]{fig_graph_simplification.png}
    \caption{Graph of a town's street network before (left) and after (right) edge simplification.}\label{fig:graph_simplification}
\end{figure*}

\textit{Edge simplification}, put simply, merges adjacent edges for a better model. It cleans up the graph's topology so that nodes represent intersections or dead-ends and edges represent street segments as illustrated in Figure~\ref{fig:graph_simplification}. This is important because in OpenStreetMap's raw data, ways comprise sets of straight-line segments between nodes: that is, nodes are vertices for streets' curving line geometries, not just intersections and dead-ends. By default, OSMnx simplifies this topology by deleting non-intersection/dead-end nodes, merging the edges between them into a new \enquote{simplified} edge, and retaining the complete true edge geometry as an edge attribute. When multiple OpenStreetMap ways are thus merged into a new graph edge, the ways' attribute values can be aggregated into a single value.

\textit{Node consolidation}, put simply, merges nearby nodes for a better model. This is important because many real-world street networks feature complex intersections and traffic circles, resulting in a cluster of graph nodes where there is really just one true intersection as we would consider it in transport planning or urban design. Similarly, divided roads are often represented by separate centerline edges. The intersection of 2 divided roads thus creates 4 nodes where each edge intersects a perpendicular edge---but these 4 nodes represent a single intersection in the real world. OSMnx can consolidate such complex intersections into a single node and optionally rebuild the graph's edge topology accordingly. When multiple OpenStreetMap nodes are thus merged into a new graph node, the nodes' attribute values can be aggregated into a single value.

Edge simplification and node consolidation offer several benefits. They produce a more accurate model that better represents the real world. This in turn yields more accurate network measures, for example by not overcounting complex intersections when calculating intersection density or by not underrepresenting street segment lengths. Finally, many graph algorithms' time complexity scales with node or edge count. By generating a graph with (often drastically) fewer nodes and edges---yet no loss of accuracy---many algorithms will complete much faster. This matters most when analyzing large urban networks, where runtime becomes an issue.

\subsection{Converting, Projecting, and Saving}

OSMnx's \texttt{convert} module can convert a NetworkX \texttt{MultiDiGraph} model to a NetworkX \texttt{MultiGraph} if the user prefers an undirected representation of the network for specific analytical purposes, as discussed in the background section. It can also convert to a NetworkX \texttt{DiGraph} if the user prefers a directed graph without any parallel edges. OSMnx can also convert a \texttt{MultiDiGraph} to and from node and edge GeoPandas \texttt{GeoDataFrame} objects. The resulting nodes \texttt{GeoDataFrame} is indexed by OpenStreetMap node ID, and the resulting edges \texttt{GeoDataFrame} is multi-indexed by endpoint node $u$, endpoint node $v$, and a \textit{key} (to differentiate parallel edges), just as a \texttt{MultiDiGraph} edge is identified by its $u$, $v$, \textit{key} ordered triplet. This also allows users to load arbitrary node and edge ShapeFiles or GeoPackage layers as \texttt{GeoDataFrame}s then convert them to a \texttt{MultiDiGraph} for network analysis.

As these models are all spatial graphs, they have coordinate reference system (CRS) metadata. OSMnx's default CRS is EPSG:4326, but users can project a graph to any other CRS using the \texttt{projection} module. If a user is unsure which CRS to project to, OSMnx can automatically determine an appropriate Universal Transverse Mercator CRS for the operation, based on the graph nodes' centroid.

Finally, using the \texttt{io} module, users can save a graph to disk as a GraphML file (to load into other network analysis software, including OSMnx), a GeoPackage (to load into other GIS software), or an OSM XML file (the standard OpenStreetMap data interchange format).

\subsection{Elevation}

Topography is essential to understanding street network form, but street network analyses too often ignore elevation as it can be difficult to acquire and attach to a graph model \citep{boeing_street_2022}. OSMnx's \texttt{elevation} module lets users automatically add elevation attributes to a spatial graph's nodes from either a local raster file or the Google Maps Elevation API.\@ Once all nodes have elevation attributes, users can automatically calculate edge grades (i.e., rise-over-run inclines), analyze the steepness of certain streets, or use elevation change in an impedance function for routing, as discussed below.

\subsection{Map Matching and Routing}

OSMnx offers basic map matching and routing functionality. The \texttt{distance} module can match a list of coordinates to each's nearest node or edge using a fast spatial index and vectorized operation. This can be useful for converting an origin-destination matrix of coordinates (such as geocoded addresses) into corresponding nearest nodes for route solving.

The \texttt{routing} module can solve shortest paths for network routing---parallelized with multiprocessing---using different weights (e.g., distance, travel time, elevation change, etc.). OpenStreetMap has a \enquote{maxspeed} tag representing streets' maximum speed limits, but it tends to be sparse for most cities. To address this problem, the \texttt{routing} module can impute missing edge maximum speeds based on observed values across other edges of the same type in the graph. Such imputation can be imprecise, but the user can override it by passing per-type local speed limits. Once all edges have maximum speed attributes, the module can also automatically calculate free-flow traversal times for each edge.

\subsection{Network Measures}

The \texttt{stats} module can calculate a variety of geometric and topological measures of the network \citep{boeing_street_2022}. These measures define streets as the edges in an undirected representation of the graph to prevent double-counting the bidirectional edges of a two-way street. Users can automatically calculate common measures from transport planning, urban design, and network science, including intersection density, circuity, average node degree, centrality, and many others. Users can also use NetworkX directly to calculate dozens of additional topological network measures. Additionally, OSMnx's \texttt{bearing} module can calculate the streets' compass bearings and the network's orientation entropy \citep{boeing_urban_2019}.

\subsection{Visualization}

Users can visualize network characteristics, routes, network figure-ground diagrams \citep{boeing_spatial_2021}, building footprints, and network orientation polar histograms \citep{boeing_urban_2019} using OSMnx's \texttt{plot} module. Users can also easily explore networks, routes, or urban amenities as interactive web maps.

\subsection{Installation and Configuration}

The OSMnx project's source code\endnote{The OSMnx source code is hosted at \href{https://github.com/gboeing/osmnx}{https://github.com/gboeing/osmnx}} is publicly hosted on GitHub. Users can install the package from the PyPI package repository using pip or from the Anaconda package repository using conda, as detailed in the package documentation\endnote{The OSMnx documentation is available at \href{https://osmnx.readthedocs.io/en/latest/}{https://osmnx.readthedocs.io/en/latest/}} and its installation instructions. To get started, users can read the documentation's Getting Started guide then work through the OSMnx Examples Gallery\endnote{The OSMnx Examples Gallery is hosted at \href{https://github.com/gboeing/osmnx-examples}{https://github.com/gboeing/osmnx-examples}} for step-by-step tutorials, feature demonstrations, and sample code.

Once installed and imported, users can configure OSMnx through its \texttt{settings} module. Here they can adjust logging behavior, server response caching, server endpoints (including pointing to locally hosted instances), and much more. Users can also configure OSMnx to retrieve historical snapshots of OpenStreetMap data as of a certain date.

\section{Discussion}

The open science movement calls for accessible, reusable, and well-documented research tools to support better science. The OSMnx project seeks to contribute to these goals in urban science by offering such a tool for modeling and analyzing urban networks and amenities anywhere in the world from OpenStreetMap data. It embodies the relevant domain theory from urban planning, network science, and geographical information science in an easy-to-use tool. In turn, researchers no longer have to reinvent the wheel and make dozens of ad hoc modeling decisions for each analytics project.

Along these lines, the OSMnx project aims to improve reproducibility by allowing users to automatically model networks with clearly defined spatial extents, thoroughly documented modeling decisions, and theoretically-sophisticated results. For example, its graph models are primal, nonplanar, directed, weighted, multigraphs with possible self-loops to capture the diversity of network types and characteristics around the world. Its graph creation methods attenuate perimeter effects, and its graph simplification methods generate models that flexibly match real-world expectations and use.

This paper documented the package's current organization, capabilities, and scientific underpinnings. Better tools, led by academic domain experts, represent one of the key paths forward toward better and more open science.

\section*{Acknowledgments}

The author wishes to thank the developers and maintainers of the many other packages on which OSMnx depends, as well as the contributors who have lent their time and expertise in proposing features, solving bugs, and contributing code to the OSMnx code base over the years.

% print the footnotes as endnotes, if any exist
\IfFileExists{\jobname.ent}{\theendnotes}{}

% print the bibliography
\setlength{\bibsep}{0.00cm plus 0.05cm} % no space between items
\bibliographystyle{apalike}
\bibliography{references}

\end{document}