Upload 79 files

Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.10
+
+RUN useradd -m -u 1000 user && python -m pip install --upgrade pip
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . /app
+ENV MCP_TRANSPORT=http
+ENV MCP_PORT=7860
+
+EXPOSE 7860
+
+CMD ["python", "osmnx/mcp_output/start_mcp.py"]

README.md

@@ -1,10 +1,32 @@
 ---
-title: Osmnx
-emoji: 💻
-colorFrom: indigo
+title: Osmnx MCP
+emoji: 🤖
+colorFrom: blue
 colorTo: purple
 sdk: docker
+sdk_version: "4.26.0"
+app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Osmnx MCP Service
+
+Auto-generated MCP service for osmnx.
+
+## Usage
+
+```
+https://None-osmnx-mcp.hf.space/mcp
+```
+
+## Connect with Cursor
+
+```json
+{
+  "mcpServers": {
+    "osmnx": {
+      "url": "https://None-osmnx-mcp.hf.space/mcp"
+    }
+  }
+}
+```

app.py

@@ -0,0 +1,45 @@
+from fastapi import FastAPI
+import os
+import sys
+
+mcp_plugin_path = os.path.join(os.path.dirname(__file__), "osmnx", "mcp_output", "mcp_plugin")
+sys.path.insert(0, mcp_plugin_path)
+
+app = FastAPI(
+    title="Osmnx MCP Service",
+    description="Auto-generated MCP service for osmnx",
+    version="1.0.0"
+)
+
+@app.get("/")
+def root():
+    return {
+        "service": "Osmnx MCP Service",
+        "version": "1.0.0",
+        "status": "running",
+        "transport": os.environ.get("MCP_TRANSPORT", "http")
+    }
+
+@app.get("/health")
+def health_check():
+    return {"status": "healthy", "service": "osmnx MCP"}
+
+@app.get("/tools")
+def list_tools():
+    try:
+        from mcp_service import create_app
+        mcp_app = create_app()
+        tools = []
+        for tool_name, tool_func in mcp_app.tools.items():
+            tools.append({
+                "name": tool_name,
+                "description": tool_func.__doc__ or "No description available"
+            })
+        return {"tools": tools}
+    except Exception as e:
+        return {"error": f"Failed to load tools: {str(e)}"}
+
+if __name__ == "__main__":
+    import uvicorn
+    port = int(os.environ.get("PORT", 7860))
+    uvicorn.run(app, host="0.0.0.0", port=port)

osmnx/mcp_output/README_MCP.md

@@ -0,0 +1,70 @@
+# OSMnx MCP (Model Context Protocol) Service
+
+## Project Introduction
+
+OSMnx is a Python package designed for downloading, modeling, analyzing, and visualizing street networks and other geospatial features from OpenStreetMap (OSM). It provides a simple interface to retrieve complex urban data and convert it into network graphs and other usable formats for spatial analysis. Key functionalities include graph creation, network analysis, routing, and visualization.
+
+## Installation Method
+
+To install OSMnx, ensure you have Python installed, then use pip to install the package along with its dependencies:
+
+- Required dependencies: `networkx`, `matplotlib`, `geopandas`, `shapely`, `requests`
+- Optional dependency: `folium`
+
+Install OSMnx via pip:
+
+```
+pip install osmnx
+```
+
+## Quick Start
+
+Here's a quick example to get you started with OSMnx:
+
+1. **Create a graph from a place name:**
+
+   ```python
+   import osmnx as ox
+   G = ox.graph_from_place('Piedmont, California, USA', network_type='drive')
+   ```
+
+2. **Plot the graph:**
+
+   ```python
+   ox.plot_graph(G)
+   ```
+
+3. **Calculate distances:**
+
+   ```python
+   distance = ox.distance.great_circle_vec(lat1, lon1, lat2, lon2)
+   ```
+
+## Available Tools and Endpoints List
+
+- **Graph Creation:**
+  - `graph_from_place()`: Create a graph from a place name.
+  - `graph_from_address()`: Create a graph from an address.
+  - `graph_from_point()`: Create a graph from a geographic point.
+
+- **Visualization:**
+  - `plot_graph()`: Visualize the graph.
+  - `plot_footprints()`: Plot building footprints.
+
+- **Distance Calculations:**
+  - `great_circle_vec()`: Calculate great-circle distance between points.
+  - `euclidean_dist_vec()`: Calculate Euclidean distance between points.
+
+## Common Issues and Notes
+
+- **Dependencies:** Ensure all required dependencies are installed. Use the optional `folium` for interactive map visualizations.
+- **Environment:** OSMnx is compatible with Python 3.6 and above. Ensure your environment is set up accordingly.
+- **Performance:** Large datasets may require significant memory and processing power. Consider using a machine with adequate resources for large-scale analyses.
+
+## Reference Links or Documentation
+
+- [OSMnx GitHub Repository](https://github.com/gboeing/osmnx)
+- [OSMnx Documentation](https://osmnx.readthedocs.io/en/stable/)
+- [OSMnx User Guide](https://osmnx.readthedocs.io/en/stable/user_guide.html)
+
+For further details on the OSMnx MCP (Model Context Protocol) service, refer to the documentation and explore the various functionalities it offers for geospatial analysis and visualization.

osmnx/mcp_output/analysis.json

@@ -0,0 +1,251 @@
+{
+  "summary": {
+    "repository_url": "https://github.com/gboeing/osmnx",
+    "summary": "Imported via zip fallback, file count: 49",
+    "file_tree": {
+      ".github/ISSUE_TEMPLATE/bug_report.yml": {
+        "size": 4139
+      },
+      ".github/ISSUE_TEMPLATE/config.yml": {
+        "size": 28
+      },
+      ".github/ISSUE_TEMPLATE/feature_proposal.yml": {
+        "size": 2518
+      },
+      ".github/dependabot.yml": {
+        "size": 173
+      },
+      ".github/pull_request_template.md": {
+        "size": 946
+      },
+      ".github/workflows/build-publish-docker.yml": {
+        "size": 1519
+      },
+      ".github/workflows/build-publish-pypi.yml": {
+        "size": 1213
+      },
+      ".github/workflows/ci.yml": {
+        "size": 2027
+      },
+      ".github/workflows/test-docs-linkcheck.yml": {
+        "size": 1014
+      },
+      ".github/workflows/test-latest-deps.yml": {
+        "size": 1214
+      },
+      ".github/workflows/test-minimum-deps.yml": {
+        "size": 1319
+      },
+      ".pre-commit-config.yaml": {
+        "size": 1390
+      },
+      "CHANGELOG.md": {
+        "size": 31709
+      },
+      "CONTRIBUTING.md": {
+        "size": 3569
+      },
+      "LICENSE.txt": {
+        "size": 1109
+      },
+      "README.md": {
+        "size": 2558
+      },
+      "docs/.readthedocs.yaml": {
+        "size": 223
+      },
+      "docs/requirements-docs.txt": {
+        "size": 45
+      },
+      "docs/source/conf.py": {
+        "size": 1842
+      },
+      "osmnx/__init__.py": {
+        "size": 1189
+      },
+      "osmnx/_api_v1.py": {
+        "size": 2724
+      },
+      "osmnx/_errors.py": {
+        "size": 610
+      },
+      "osmnx/_http.py": {
+        "size": 11518
+      },
+      "osmnx/_nominatim.py": {
+        "size": 4900
+      },
+      "osmnx/_osm_xml.py": {
+        "size": 16252
+      },
+      "osmnx/_overpass.py": {
+        "size": 18059
+      },
+      "osmnx/_validate.py": {
+        "size": 13542
+      },
+      "osmnx/bearing.py": {
+        "size": 10769
+      },
+      "osmnx/convert.py": {
+        "size": 18490
+      },
+      "osmnx/distance.py": {
+        "size": 16700
+      },
+      "osmnx/elevation.py": {
+        "size": 11330
+      },
+      "osmnx/features.py": {
+        "size": 28647
+      },
+      "osmnx/geocoder.py": {
+        "size": 8631
+      },
+      "osmnx/graph.py": {
+        "size": 33070
+      },
+      "osmnx/io.py": {
+        "size": 15477
+      },
+      "osmnx/plot.py": {
+        "size": 33836
+      },
+      "osmnx/projection.py": {
+        "size": 6381
+      },
+      "osmnx/routing.py": {
+        "size": 21734
+      },
+      "osmnx/settings.py": {
+        "size": 8327
+      },
+      "osmnx/simplification.py": {
+        "size": 33518
+      },
+      "osmnx/stats.py": {
+        "size": 13492
+      },
+      "osmnx/truncate.py": {
+        "size": 6097
+      },
+      "osmnx/utils.py": {
+        "size": 6198
+      },
+      "osmnx/utils_geo.py": {
+        "size": 13934
+      },
+      "pyproject.toml": {
+        "size": 3463
+      },
+      "tests/.yamllint.yml": {
+        "size": 182
+      },
+      "tests/README.md": {
+        "size": 1703
+      },
+      "tests/test_osmnx.py": {
+        "size": 36044
+      },
+      "tests/verify_min_deps.py": {
+        "size": 1575
+      }
+    },
+    "processed_by": "zip_fallback",
+    "success": true
+  },
+  "structure": {
+    "packages": [
+      "source.osmnx"
+    ]
+  },
+  "dependencies": {
+    "has_environment_yml": false,
+    "has_requirements_txt": false,
+    "pyproject": true,
+    "setup_cfg": false,
+    "setup_py": false
+  },
+  "entry_points": {
+    "imports": [],
+    "cli": [],
+    "modules": []
+  },
+  "llm_analysis": {
+    "core_modules": [
+      {
+        "package": "source.osmnx",
+        "module": "osmnx.graph",
+        "functions": [
+          "graph_from_place",
+          "graph_from_address",
+          "graph_from_point"
+        ],
+        "classes": [
+          "Graph"
+        ],
+        "description": "Functions and classes for creating and manipulating graphs from OpenStreetMap data."
+      },
+      {
+        "package": "source.osmnx",
+        "module": "osmnx.plot",
+        "functions": [
+          "plot_graph",
+          "plot_footprints"
+        ],
+        "classes": [],
+        "description": "Functions for visualizing graphs and geographic data."
+      },
+      {
+        "package": "source.osmnx",
+        "module": "osmnx.distance",
+        "functions": [
+          "great_circle_vec",
+          "euclidean_dist_vec"
+        ],
+        "classes": [],
+        "description": "Functions for calculating distances between geographic points."
+      }
+    ],
+    "cli_commands": [],
+    "import_strategy": {
+      "primary": "import",
+      "fallback": "blackbox",
+      "confidence": 0.9
+    },
+    "dependencies": {
+      "required": [
+        "networkx",
+        "matplotlib",
+        "geopandas",
+        "shapely",
+        "requests"
+      ],
+      "optional": [
+        "folium"
+      ]
+    },
+    "risk_assessment": {
+      "import_feasibility": 0.9,
+      "intrusiveness_risk": "low",
+      "complexity": "medium"
+    }
+  },
+  "deepwiki_analysis": {
+    "repo_url": "https://github.com/gboeing/osmnx",
+    "repo_name": "osmnx",
+    "content": "gboeing/osmnx\nInstallation and Setup\nGetting Started\nArchitecture and Data Flow\nData Acquisition\nConfiguration and Settings\nCore Functionality\nGraph Creation and Manipulation\nNetwork Analysis\nRouting and Path Finding\nVisualization\nAdvanced Features\nElevation Data\nProjection and Coordinate Systems\nData Import and Export\nDevelopment and Contributing\nTesting and Quality Assurance\nCI/CD Pipeline\nDocker Environment\nVersion History and Roadmap\nCHANGELOG.md\nLICENSE.txt\ndocs/source/conf.py\ndocs/source/index.rst\ndocs/source/internals-reference.rst\ndocs/source/user-reference.rst\nosmnx/__init__.py\nosmnx/_version.py\nOSMnx is a Python package for downloading, modeling, analyzing, and visualizing street networks and other geospatial features from OpenStreetMap (OSM). It provides a simple interface to retrieve complex urban data and convert it into network graphs and other usable formats for spatial analysis. This document introduces the OSMnx system architecture and its core functionality. For installation instructions, seeInstallation and Setup, and for a quick start guide, seeGetting Started.\nPurpose and Scope\nOSMnx enables users to:\nDownload and model walking, driving, or biking networks with a single line of code\nWork with urban amenities/points of interest, building footprints, and transit infrastructure\nAnalyze network metrics and spatial characteristics\nIncorporate elevation data for 3D network analysis and grade calculations\nCalculate and visualize street orientation patterns and entropy\nPerform routing and trip planning with customizable impedance values\nProject and visualize networks and analysis results\nSources:README.md10-12docs/source/index.rst4-5\nSystem Architecture\nCore Components of OSMnx\nOSMnx SystemUser ApplicationOSMnx APIData Acquisition LayerProcessing LayerAnalysis LayerVisualization LayerI/O LayerOverpass API Client(_overpass)Nominatim API Client(_nominatim)HTTP & Caching(_http)graph.py(Network Creation)projection.py(Coordinate Systems)simplification.py(Network Cleanup)convert.py(Data Conversion)distance.py(Distance Calculations)routing.py(Path Finding)stats.py(Network Metrics)bearing.py(Street Orientations)elevation.py(Elevation Data)plot.py(Map Visualization)io.py(Save/Load Graphs)_osm_xml.py(XML Handling)settings.py(Configuration)utils.py(Utilities)OpenStreetMapData\nOSMnx System\nUser Application\nData Acquisition Layer\nProcessing Layer\nAnalysis Layer\nVisualization Layer\nOverpass API Client(_overpass)\nNominatim API Client(_nominatim)\nHTTP & Caching(_http)\ngraph.py(Network Creation)\nprojection.py(Coordinate Systems)\nsimplification.py(Network Cleanup)\nconvert.py(Data Conversion)\ndistance.py(Distance Calculations)\nrouting.py(Path Finding)\nstats.py(Network Metrics)\nbearing.py(Street Orientations)\nelevation.py(Elevation Data)\nplot.py(Map Visualization)\nio.py(Save/Load Graphs)\n_osm_xml.py(XML Handling)\nsettings.py(Configuration)\nutils.py(Utilities)\nOpenStreetMapData\nSources:osmnx/__init__.py10-53docs/source/user-reference.rst\nOutputAnalysisGraph ProcessingData AcquisitionInput MethodsUser InputDefine Query Typegraph_from_place()graph_from_address()graph_from_point()graph_from_bbox()graph_from_polygon()graph_from_xml()geocoder.py_nominatim.py_overpass.py_http.pyOpenStreetMapData_osm_xml.pyNetworkX MultiDiGraphproject_graph()simplify_graph()consolidate_intersections()Add Attributes(speed, travel time,elevation, bearings)Path Finding(shortest_path,k_shortest_paths)Network Analysis(basic_stats)plot_graph()plot_graph_route()save_graphml()save_graph_geopackage()save_graph_xml()\nGraph Processing\nData Acquisition\nInput Methods\nDefine Query Type\ngraph_from_place()\ngraph_from_address()\ngraph_from_point()\ngraph_from_bbox()\ngraph_from_polygon()\ngraph_from_xml()\ngeocoder.py\n_nominatim.py\n_overpass.py\nOpenStreetMapData\n_osm_xml.py\nNetworkX MultiDiGraph\nproject_graph()\nsimplify_graph()\nconsolidate_intersections()\nAdd Attributes(speed, travel time,elevation, bearings)\nPath Finding(shortest_path,k_shortest_paths)\nNetwork Analysis(basic_stats)\nplot_graph()plot_graph_route()\nsave_graphml()save_graph_geopackage()save_graph_xml()\nSources:osmnx/__init__.py10-53CHANGELOG.md\nCore Functionality\nGraph Creation\nOSMnx provides multiple functions for downloading and creating street network graphs:\ngraph_from_place()\ngraph_from_address()\ngraph_from_point()\ngraph_from_bbox()\ngraph_from_polygon()\ngraph_from_xml()\nSources:osmnx/__init__.py27-32\nNetwork Types\nOSMnx can retrieve different types of street networks depending on thenetwork_typeparameter:\nnetwork_type\nNetwork Typeswalk(Pedestrian)bike(Cycling)drive(Driving)drive_service(Driving + Service Roads)all(All Public Ways)all_public(All Public Ways)\nNetwork Types\nwalk(Pedestrian)\nbike(Cycling)\ndrive(Driving)\ndrive_service(Driving + Service Roads)\nall(All Public Ways)\nall_public(All Public Ways)\nSources:CHANGELOG.md79-81\nData Processing and Analysis\nAfter creating a graph, OSMnx provides tools for processing, enriching, and analyzing the network:\nproject_graph()\nsimplify_graph()\nconsolidate_intersections()\nadd_edge_lengths()\nadd_edge_speeds()\nadd_edge_travel_times()\nadd_edge_bearings()\nadd_edge_grades()\nadd_node_elevations_google()\nadd_node_elevations_raster()\nshortest_path()\nk_shortest_paths()\nbasic_stats()\nSources:osmnx/__init__.py10-53CHANGELOG.md\nVisualization\nOSMnx provides multiple plotting functions to visualize networks and analysis results:\nplot_graph()\nplot_graph_route()\nplot_graph_routes()\nplot_footprints()\nplot_figure_ground()\nplot_orientation()\nSources:osmnx/__init__.py37-42\nOSMnx can save and load graphs in various formats:\nsave_graphml()\nload_graphml()\nsave_graph_geopackage()\nsave_graph_xml()\nSources:osmnx/__init__.py33-36\nVersion and Development\nOSMnx is currently at version 2.0.2, released under the MIT license. The package is actively maintained with regular updates and improvements. For version history and roadmap information, seeVersion History and Roadmap.\nSources:osmnx/_version.py3LICENSE.txtCHANGELOG.md\nRefresh this wiki\nOn this page\nPurpose and Scope\nSystem Architecture\nCore Components of OSMnx\nCore Functionality\nGraph Creation\nNetwork Types\nData Processing and Analysis\nVisualization\nVersion and Development",
+    "model": "gpt-4o-2024-08-06",
+    "source": "selenium",
+    "success": true
+  },
+  "deepwiki_options": {
+    "enabled": true,
+    "model": "gpt-4o-2024-08-06"
+  },
+  "risk": {
+    "import_feasibility": 0.9,
+    "intrusiveness_risk": "low",
+    "complexity": "medium"
+  }
+}

osmnx/mcp_output/diff_report.md

@@ -0,0 +1,63 @@
+# OSMnx Project Difference Report
+
+**Date:** February 6, 2026  
+**Time:** 14:18:16  
+**Repository:** osmnx  
+**Project Type:** Python Library  
+**Intrusiveness:** None  
+**Workflow Status:** Success  
+**Test Status:** Failed  
+
+## Project Overview
+
+OSMnx is a Python library designed to facilitate the acquisition, construction, analysis, and visualization of street networks from OpenStreetMap. It provides tools for geospatial analysis and urban planning, making it a valuable resource for researchers and developers working with spatial data.
+
+## Difference Analysis
+
+### New Files
+
+In this update, 8 new files have been added to the repository. These files likely introduce new features or enhancements to the existing functionality of the OSMnx library. However, no existing files were modified, indicating that the core functionality remains unchanged.
+
+### Modified Files
+
+There were no modifications to existing files. This suggests that the new features or enhancements were implemented in a way that does not alter the current codebase, maintaining backward compatibility.
+
+## Technical Analysis
+
+### Workflow Status
+
+The workflow status is marked as successful, indicating that the automated processes for building, testing, and deploying the project were executed without errors. This suggests that the integration of new files was handled smoothly.
+
+### Test Status
+
+The test status is marked as failed, which is a critical issue. This failure indicates that the new additions may have introduced bugs or that the existing test suite does not adequately cover the new functionality. It is essential to address these test failures to ensure the reliability and stability of the library.
+
+## Recommendations and Improvements
+
+1. **Investigate Test Failures:** Conduct a thorough investigation into the test failures to identify the root causes. This may involve reviewing the new files for potential bugs or updating the test suite to cover new functionalities.
+
+2. **Enhance Test Coverage:** Ensure that the test suite is comprehensive and includes tests for all new features. This will help in maintaining the integrity of the library and prevent future test failures.
+
+3. **Documentation Update:** Update the project documentation to reflect the new features and enhancements. This will assist users in understanding and utilizing the new capabilities of the library.
+
+4. **Code Review:** Conduct a code review of the new files to ensure they adhere to the project's coding standards and best practices. This can help in identifying potential issues early.
+
+## Deployment Information
+
+The deployment process appears to have been successful, as indicated by the workflow status. However, given the test failures, it is advisable to hold off on deploying the new version to production until the issues are resolved.
+
+## Future Planning
+
+1. **Bug Fixes:** Prioritize fixing the test failures and any identified bugs in the new files.
+
+2. **Feature Expansion:** Consider expanding the new features based on user feedback and requirements.
+
+3. **Community Engagement:** Engage with the community to gather feedback on the new features and identify areas for improvement.
+
+4. **Regular Updates:** Plan for regular updates to the library to incorporate new features, bug fixes, and improvements.
+
+## Conclusion
+
+The recent update to the OSMnx project introduces new features through the addition of 8 new files. While the integration process was successful, the test failures highlight the need for immediate attention to ensure the library's reliability. By addressing these issues and enhancing test coverage, the project can continue to provide valuable tools for geospatial analysis and urban planning.
+
+---

osmnx/mcp_output/mcp_plugin/adapter.py

@@ -0,0 +1,242 @@
+import os
+import sys
+
+# Path settings
+source_path = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))), "source")
+sys.path.insert(0, source_path)
+
+# Import statements
+try:
+    from osmnx import (
+        graph_from_place, graph_from_address, graph_from_point, graph_from_bbox,
+        graph_from_polygon, graph_from_xml, project_graph, simplify_graph,
+        consolidate_intersections, add_edge_lengths, add_edge_speeds,
+        add_edge_travel_times, add_edge_bearings, add_edge_grades,
+        add_node_elevations_google, add_node_elevations_raster, shortest_path,
+        k_shortest_paths, basic_stats, plot_graph, plot_graph_route,
+        plot_graph_routes, plot_footprints, plot_figure_ground, plot_orientation,
+        save_graphml, load_graphml, save_graph_geopackage, save_graph_xml
+    )
+    import_success = True
+except ImportError as e:
+    import_success = False
+    import_error = str(e)
+
+class Adapter:
+    """
+    Adapter class for interfacing with the OSMnx library.
+    Provides methods for graph creation, manipulation, analysis, and visualization.
+    """
+    
+    def __init__(self):
+        self.mode = "import" if import_success else "fallback"
+    
+    # -------------------- Graph Creation Methods --------------------
+    
+    def create_graph_from_place(self, place_name, network_type='all'):
+        """
+        Create a graph from a place name.
+        
+        :param place_name: Name of the place to create the graph from.
+        :param network_type: Type of network to create.
+        :return: Dictionary with status and graph object or error message.
+        """
+        try:
+            graph = graph_from_place(place_name, network_type=network_type)
+            return {"status": "success", "graph": graph}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+    
+    def create_graph_from_address(self, address, network_type='all'):
+        """
+        Create a graph from an address.
+        
+        :param address: Address to create the graph from.
+        :param network_type: Type of network to create.
+        :return: Dictionary with status and graph object or error message.
+        """
+        try:
+            graph = graph_from_address(address, network_type=network_type)
+            return {"status": "success", "graph": graph}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+    
+    def create_graph_from_point(self, point, dist=1000, network_type='all'):
+        """
+        Create a graph from a geographical point.
+        
+        :param point: Tuple of (latitude, longitude).
+        :param dist: Distance around the point to create the graph.
+        :param network_type: Type of network to create.
+        :return: Dictionary with status and graph object or error message.
+        """
+        try:
+            graph = graph_from_point(point, dist=dist, network_type=network_type)
+            return {"status": "success", "graph": graph}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+    
+    def create_graph_from_bbox(self, north, south, east, west, network_type='all'):
+        """
+        Create a graph from a bounding box.
+        
+        :param north: Northern latitude.
+        :param south: Southern latitude.
+        :param east: Eastern longitude.
+        :param west: Western longitude.
+        :param network_type: Type of network to create.
+        :return: Dictionary with status and graph object or error message.
+        """
+        try:
+            graph = graph_from_bbox(north, south, east, west, network_type=network_type)
+            return {"status": "success", "graph": graph}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+    
+    def create_graph_from_polygon(self, polygon, network_type='all'):
+        """
+        Create a graph from a polygon.
+        
+        :param polygon: Polygon geometry.
+        :param network_type: Type of network to create.
+        :return: Dictionary with status and graph object or error message.
+        """
+        try:
+            graph = graph_from_polygon(polygon, network_type=network_type)
+            return {"status": "success", "graph": graph}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+    
+    def create_graph_from_xml(self, filepath, network_type='all'):
+        """
+        Create a graph from an XML file.
+        
+        :param filepath: Path to the XML file.
+        :param network_type: Type of network to create.
+        :return: Dictionary with status and graph object or error message.
+        """
+        try:
+            graph = graph_from_xml(filepath, network_type=network_type)
+            return {"status": "success", "graph": graph}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+    
+    # -------------------- Graph Manipulation Methods --------------------
+    
+    def project_graph(self, graph):
+        """
+        Project a graph to UTM.
+        
+        :param graph: Graph to project.
+        :return: Dictionary with status and projected graph or error message.
+        """
+        try:
+            projected_graph = project_graph(graph)
+            return {"status": "success", "projected_graph": projected_graph}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+    
+    def simplify_graph(self, graph):
+        """
+        Simplify a graph.
+        
+        :param graph: Graph to simplify.
+        :return: Dictionary with status and simplified graph or error message.
+        """
+        try:
+            simplified_graph = simplify_graph(graph)
+            return {"status": "success", "simplified_graph": simplified_graph}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+    
+    def consolidate_intersections(self, graph, tolerance=10, rebuild_graph=True):
+        """
+        Consolidate intersections in a graph.
+        
+        :param graph: Graph to process.
+        :param tolerance: Tolerance for consolidating intersections.
+        :param rebuild_graph: Whether to rebuild the graph after consolidation.
+        :return: Dictionary with status and processed graph or error message.
+        """
+        try:
+            consolidated_graph = consolidate_intersections(graph, tolerance=tolerance, rebuild_graph=rebuild_graph)
+            return {"status": "success", "consolidated_graph": consolidated_graph}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+    
+    # -------------------- Graph Analysis Methods --------------------
+    
+    def calculate_basic_stats(self, graph):
+        """
+        Calculate basic statistics of a graph.
+        
+        :param graph: Graph to analyze.
+        :return: Dictionary with status and statistics or error message.
+        """
+        try:
+            stats = basic_stats(graph)
+            return {"status": "success", "stats": stats}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+    
+    # -------------------- Graph Visualization Methods --------------------
+    
+    def plot_graph(self, graph, **kwargs):
+        """
+        Plot a graph.
+        
+        :param graph: Graph to plot.
+        :param kwargs: Additional plotting parameters.
+        :return: Dictionary with status and plot or error message.
+        """
+        try:
+            plot = plot_graph(graph, **kwargs)
+            return {"status": "success", "plot": plot}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+    
+    # -------------------- Graph I/O Methods --------------------
+    
+    def save_graphml(self, graph, filepath):
+        """
+        Save a graph to GraphML format.
+        
+        :param graph: Graph to save.
+        :param filepath: Path to save the GraphML file.
+        :return: Dictionary with status or error message.
+        """
+        try:
+            save_graphml(graph, filepath)
+            return {"status": "success"}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+    
+    def load_graphml(self, filepath):
+        """
+        Load a graph from GraphML format.
+        
+        :param filepath: Path to the GraphML file.
+        :return: Dictionary with status and loaded graph or error message.
+        """
+        try:
+            graph = load_graphml(filepath)
+            return {"status": "success", "graph": graph}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+    
+    # -------------------- Fallback Handling --------------------
+    
+    def handle_import_failure(self):
+        """
+        Handle import failure gracefully.
+        
+        :return: Dictionary with status and error message.
+        """
+        if not import_success:
+            return {"status": "error", "message": f"Failed to import OSMnx: {import_error}. Please ensure the package is installed correctly."}
+        return {"status": "success"}
+
+# Example usage:
+# adapter = Adapter()
+# result = adapter.create_graph_from_place("Piedmont, California, USA")
+# print(result)

osmnx/mcp_output/mcp_plugin/main.py

@@ -0,0 +1,13 @@
+"""
+MCP Service Auto-Wrapper - Auto-generated
+"""
+from mcp_service import create_app
+
+def main():
+    """Main entry point"""
+    app = create_app()
+    return app
+
+if __name__ == "__main__":
+    app = main()
+    app.run()

osmnx/mcp_output/mcp_plugin/mcp_service.py

@@ -0,0 +1,79 @@
+import os
+import sys
+
+# Add the local source directory to sys.path
+source_path = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))), "source")
+if source_path not in sys.path:
+    sys.path.insert(0, source_path)
+
+from fastmcp import FastMCP
+from osmnx import graph, routing, plot, stats
+
+mcp = FastMCP("osmnx_service")
+
+@mcp.tool(name="create_graph_from_place", description="Create a graph from a place name")
+def create_graph_from_place(place_name: str, network_type: str) -> dict:
+    """
+    Create a graph from a place name.
+
+    :param place_name: The name of the place to create the graph from.
+    :param network_type: The type of network to create (e.g., 'walk', 'bike', 'drive').
+    :return: A dictionary with success, result, or error fields.
+    """
+    try:
+        G = graph.graph_from_place(place_name, network_type=network_type)
+        return {"success": True, "result": G, "error": None}
+    except Exception as e:
+        return {"success": False, "result": None, "error": str(e)}
+
+@mcp.tool(name="shortest_path", description="Find the shortest path between two nodes")
+def shortest_path(G, origin: int, destination: int) -> dict:
+    """
+    Find the shortest path between two nodes in a graph.
+
+    :param G: The graph to search.
+    :param origin: The origin node ID.
+    :param destination: The destination node ID.
+    :return: A dictionary with success, result, or error fields.
+    """
+    try:
+        path = routing.shortest_path(G, origin, destination)
+        return {"success": True, "result": path, "error": None}
+    except Exception as e:
+        return {"success": False, "result": None, "error": str(e)}
+
+@mcp.tool(name="plot_graph", description="Plot a graph")
+def plot_graph(G) -> dict:
+    """
+    Plot a graph.
+
+    :param G: The graph to plot.
+    :return: A dictionary with success, result, or error fields.
+    """
+    try:
+        fig, ax = plot.plot_graph(G)
+        return {"success": True, "result": (fig, ax), "error": None}
+    except Exception as e:
+        return {"success": False, "result": None, "error": str(e)}
+
+@mcp.tool(name="calculate_basic_stats", description="Calculate basic statistics of a graph")
+def calculate_basic_stats(G) -> dict:
+    """
+    Calculate basic statistics of a graph.
+
+    :param G: The graph to analyze.
+    :return: A dictionary with success, result, or error fields.
+    """
+    try:
+        stats_result = stats.basic_stats(G)
+        return {"success": True, "result": stats_result, "error": None}
+    except Exception as e:
+        return {"success": False, "result": None, "error": str(e)}
+
+def create_app() -> FastMCP:
+    """
+    Create and return the FastMCP application instance.
+
+    :return: The FastMCP instance.
+    """
+    return mcp

osmnx/mcp_output/requirements.txt

@@ -0,0 +1,11 @@
+fastmcp
+fastapi
+uvicorn[standard]
+pydantic>=2.0.0
+geopandas>=1.0.1
+networkx>=2.5
+numpy>=1.24
+pandas>=1.5
+requests>=2.27
+shapely>=2.0
+matplotlib

osmnx/mcp_output/start_mcp.py

@@ -0,0 +1,30 @@
+
+"""
+MCP Service Startup Entry
+"""
+import sys
+import os
+
+project_root = os.path.dirname(os.path.abspath(__file__))
+mcp_plugin_dir = os.path.join(project_root, "mcp_plugin")
+if mcp_plugin_dir not in sys.path:
+    sys.path.insert(0, mcp_plugin_dir)
+
+from mcp_service import create_app
+
+def main():
+    """Start FastMCP service"""
+    app = create_app()
+    # Use environment variable to configure port, default 8000
+    port = int(os.environ.get("MCP_PORT", "8000"))
+    
+    # Choose transport mode based on environment variable
+    transport = os.environ.get("MCP_TRANSPORT", "stdio")
+    if transport == "http":
+        app.run(transport="http", host="0.0.0.0", port=port)
+    else:
+        # Default to STDIO mode
+        app.run()
+
+if __name__ == "__main__":
+    main()

osmnx/mcp_output/workflow_summary.json

@@ -0,0 +1,194 @@
+{
+  "repository": {
+    "name": "osmnx",
+    "url": "https://github.com/gboeing/osmnx",
+    "local_path": "/export/zxcpu1/shiweijie/code/ghh/Code2MCP/workspace/osmnx",
+    "description": "Python library",
+    "features": "Basic functionality",
+    "tech_stack": "Python",
+    "stars": 0,
+    "forks": 0,
+    "language": "Python",
+    "last_updated": "",
+    "complexity": "medium",
+    "intrusiveness_risk": "low"
+  },
+  "execution": {
+    "start_time": 1770358542.3952017,
+    "end_time": 1770358630.1692348,
+    "duration": 87.7740330696106,
+    "status": "success",
+    "workflow_status": "success",
+    "nodes_executed": [
+      "download",
+      "analysis",
+      "env",
+      "generate",
+      "run",
+      "review",
+      "finalize"
+    ],
+    "total_files_processed": 1,
+    "environment_type": "unknown",
+    "llm_calls": 0,
+    "deepwiki_calls": 0
+  },
+  "tests": {
+    "original_project": {
+      "passed": false,
+      "details": {},
+      "test_coverage": "100%",
+      "execution_time": 0,
+      "test_files": []
+    },
+    "mcp_plugin": {
+      "passed": true,
+      "details": {},
+      "service_health": "healthy",
+      "startup_time": 0,
+      "transport_mode": "stdio",
+      "fastmcp_version": "unknown",
+      "mcp_version": "unknown"
+    }
+  },
+  "analysis": {
+    "structure": {
+      "packages": [
+        "source.osmnx"
+      ]
+    },
+    "dependencies": {
+      "has_environment_yml": false,
+      "has_requirements_txt": false,
+      "pyproject": true,
+      "setup_cfg": false,
+      "setup_py": false
+    },
+    "entry_points": {
+      "imports": [],
+      "cli": [],
+      "modules": []
+    },
+    "risk_assessment": {
+      "import_feasibility": 0.9,
+      "intrusiveness_risk": "low",
+      "complexity": "medium"
+    },
+    "deepwiki_analysis": {
+      "repo_url": "https://github.com/gboeing/osmnx",
+      "repo_name": "osmnx",
+      "content": "gboeing/osmnx\nInstallation and Setup\nGetting Started\nArchitecture and Data Flow\nData Acquisition\nConfiguration and Settings\nCore Functionality\nGraph Creation and Manipulation\nNetwork Analysis\nRouting and Path Finding\nVisualization\nAdvanced Features\nElevation Data\nProjection and Coordinate Systems\nData Import and Export\nDevelopment and Contributing\nTesting and Quality Assurance\nCI/CD Pipeline\nDocker Environment\nVersion History and Roadmap\nCHANGELOG.md\nLICENSE.txt\ndocs/source/conf.py\ndocs/source/index.rst\ndocs/source/internals-reference.rst\ndocs/source/user-reference.rst\nosmnx/__init__.py\nosmnx/_version.py\nOSMnx is a Python package for downloading, modeling, analyzing, and visualizing street networks and other geospatial features from OpenStreetMap (OSM). It provides a simple interface to retrieve complex urban data and convert it into network graphs and other usable formats for spatial analysis. This document introduces the OSMnx system architecture and its core functionality. For installation instructions, seeInstallation and Setup, and for a quick start guide, seeGetting Started.\nPurpose and Scope\nOSMnx enables users to:\nDownload and model walking, driving, or biking networks with a single line of code\nWork with urban amenities/points of interest, building footprints, and transit infrastructure\nAnalyze network metrics and spatial characteristics\nIncorporate elevation data for 3D network analysis and grade calculations\nCalculate and visualize street orientation patterns and entropy\nPerform routing and trip planning with customizable impedance values\nProject and visualize networks and analysis results\nSources:README.md10-12docs/source/index.rst4-5\nSystem Architecture\nCore Components of OSMnx\nOSMnx SystemUser ApplicationOSMnx APIData Acquisition LayerProcessing LayerAnalysis LayerVisualization LayerI/O LayerOverpass API Client(_overpass)Nominatim API Client(_nominatim)HTTP & Caching(_http)graph.py(Network Creation)projection.py(Coordinate Systems)simplification.py(Network Cleanup)convert.py(Data Conversion)distance.py(Distance Calculations)routing.py(Path Finding)stats.py(Network Metrics)bearing.py(Street Orientations)elevation.py(Elevation Data)plot.py(Map Visualization)io.py(Save/Load Graphs)_osm_xml.py(XML Handling)settings.py(Configuration)utils.py(Utilities)OpenStreetMapData\nOSMnx System\nUser Application\nData Acquisition Layer\nProcessing Layer\nAnalysis Layer\nVisualization Layer\nOverpass API Client(_overpass)\nNominatim API Client(_nominatim)\nHTTP & Caching(_http)\ngraph.py(Network Creation)\nprojection.py(Coordinate Systems)\nsimplification.py(Network Cleanup)\nconvert.py(Data Conversion)\ndistance.py(Distance Calculations)\nrouting.py(Path Finding)\nstats.py(Network Metrics)\nbearing.py(Street Orientations)\nelevation.py(Elevation Data)\nplot.py(Map Visualization)\nio.py(Save/Load Graphs)\n_osm_xml.py(XML Handling)\nsettings.py(Configuration)\nutils.py(Utilities)\nOpenStreetMapData\nSources:osmnx/__init__.py10-53docs/source/user-reference.rst\nOutputAnalysisGraph ProcessingData AcquisitionInput MethodsUser InputDefine Query Typegraph_from_place()graph_from_address()graph_from_point()graph_from_bbox()graph_from_polygon()graph_from_xml()geocoder.py_nominatim.py_overpass.py_http.pyOpenStreetMapData_osm_xml.pyNetworkX MultiDiGraphproject_graph()simplify_graph()consolidate_intersections()Add Attributes(speed, travel time,elevation, bearings)Path Finding(shortest_path,k_shortest_paths)Network Analysis(basic_stats)plot_graph()plot_graph_route()save_graphml()save_graph_geopackage()save_graph_xml()\nGraph Processing\nData Acquisition\nInput Methods\nDefine Query Type\ngraph_from_place()\ngraph_from_address()\ngraph_from_point()\ngraph_from_bbox()\ngraph_from_polygon()\ngraph_from_xml()\ngeocoder.py\n_nominatim.py\n_overpass.py\nOpenStreetMapData\n_osm_xml.py\nNetworkX MultiDiGraph\nproject_graph()\nsimplify_graph()\nconsolidate_intersections()\nAdd Attributes(speed, travel time,elevation, bearings)\nPath Finding(shortest_path,k_shortest_paths)\nNetwork Analysis(basic_stats)\nplot_graph()plot_graph_route()\nsave_graphml()save_graph_geopackage()save_graph_xml()\nSources:osmnx/__init__.py10-53CHANGELOG.md\nCore Functionality\nGraph Creation\nOSMnx provides multiple functions for downloading and creating street network graphs:\ngraph_from_place()\ngraph_from_address()\ngraph_from_point()\ngraph_from_bbox()\ngraph_from_polygon()\ngraph_from_xml()\nSources:osmnx/__init__.py27-32\nNetwork Types\nOSMnx can retrieve different types of street networks depending on thenetwork_typeparameter:\nnetwork_type\nNetwork Typeswalk(Pedestrian)bike(Cycling)drive(Driving)drive_service(Driving + Service Roads)all(All Public Ways)all_public(All Public Ways)\nNetwork Types\nwalk(Pedestrian)\nbike(Cycling)\ndrive(Driving)\ndrive_service(Driving + Service Roads)\nall(All Public Ways)\nall_public(All Public Ways)\nSources:CHANGELOG.md79-81\nData Processing and Analysis\nAfter creating a graph, OSMnx provides tools for processing, enriching, and analyzing the network:\nproject_graph()\nsimplify_graph()\nconsolidate_intersections()\nadd_edge_lengths()\nadd_edge_speeds()\nadd_edge_travel_times()\nadd_edge_bearings()\nadd_edge_grades()\nadd_node_elevations_google()\nadd_node_elevations_raster()\nshortest_path()\nk_shortest_paths()\nbasic_stats()\nSources:osmnx/__init__.py10-53CHANGELOG.md\nVisualization\nOSMnx provides multiple plotting functions to visualize networks and analysis results:\nplot_graph()\nplot_graph_route()\nplot_graph_routes()\nplot_footprints()\nplot_figure_ground()\nplot_orientation()\nSources:osmnx/__init__.py37-42\nOSMnx can save and load graphs in various formats:\nsave_graphml()\nload_graphml()\nsave_graph_geopackage()\nsave_graph_xml()\nSources:osmnx/__init__.py33-36\nVersion and Development\nOSMnx is currently at version 2.0.2, released under the MIT license. The package is actively maintained with regular updates and improvements. For version history and roadmap information, seeVersion History and Roadmap.\nSources:osmnx/_version.py3LICENSE.txtCHANGELOG.md\nRefresh this wiki\nOn this page\nPurpose and Scope\nSystem Architecture\nCore Components of OSMnx\nCore Functionality\nGraph Creation\nNetwork Types\nData Processing and Analysis\nVisualization\nVersion and Development",
+      "model": "gpt-4o-2024-08-06",
+      "source": "selenium",
+      "success": true
+    },
+    "code_complexity": {
+      "cyclomatic_complexity": "medium",
+      "cognitive_complexity": "medium",
+      "maintainability_index": 75
+    },
+    "security_analysis": {
+      "vulnerabilities_found": 0,
+      "security_score": 85,
+      "recommendations": []
+    }
+  },
+  "plugin_generation": {
+    "files_created": [
+      "mcp_output/start_mcp.py",
+      "mcp_output/mcp_plugin/__init__.py",
+      "mcp_output/mcp_plugin/mcp_service.py",
+      "mcp_output/mcp_plugin/adapter.py",
+      "mcp_output/mcp_plugin/main.py",
+      "mcp_output/requirements.txt",
+      "mcp_output/README_MCP.md"
+    ],
+    "main_entry": "start_mcp.py",
+    "requirements": [
+      "fastmcp>=0.1.0",
+      "pydantic>=2.0.0"
+    ],
+    "readme_path": "/export/zxcpu1/shiweijie/code/ghh/Code2MCP/workspace/osmnx/mcp_output/README_MCP.md",
+    "adapter_mode": "import",
+    "total_lines_of_code": 0,
+    "generated_files_size": 0,
+    "tool_endpoints": 0,
+    "supported_features": [
+      "Basic functionality"
+    ],
+    "generated_tools": [
+      "Basic tools",
+      "Health check tools",
+      "Version info tools"
+    ]
+  },
+  "code_review": {},
+  "errors": [],
+  "warnings": [],
+  "recommendations": [
+    "Improve test coverage by adding more unit tests",
+    "Ensure all dependencies are clearly defined in a requirements.txt or environment.yml file",
+    "Optimize large files like osmnx/plot.py and osmnx/simplification.py for better performance",
+    "Enhance documentation for core modules and functions",
+    "Implement continuous integration to automate testing and deployment",
+    "Review and refactor code for better readability and maintainability",
+    "Consider adding more CLI commands for ease of use",
+    "Update the README to include more detailed setup and usage instructions",
+    "Regularly update the CHANGELOG to reflect recent changes and improvements",
+    "Conduct a code review to identify potential areas for optimization and bug fixes."
+  ],
+  "performance_metrics": {
+    "memory_usage_mb": 0,
+    "cpu_usage_percent": 0,
+    "response_time_ms": 0,
+    "throughput_requests_per_second": 0
+  },
+  "deployment_info": {
+    "supported_platforms": [
+      "Linux",
+      "Windows",
+      "macOS"
+    ],
+    "python_versions": [
+      "3.8",
+      "3.9",
+      "3.10",
+      "3.11",
+      "3.12"
+    ],
+    "deployment_methods": [
+      "Docker",
+      "pip",
+      "conda"
+    ],
+    "monitoring_support": true,
+    "logging_configuration": "structured"
+  },
+  "execution_analysis": {
+    "success_factors": [
+      "Successful execution of all workflow nodes",
+      "Healthy service status of the MCP plugin"
+    ],
+    "failure_reasons": [],
+    "overall_assessment": "excellent",
+    "node_performance": {
+      "download_time": "Efficient, completed without issues",
+      "analysis_time": "Completed successfully, medium complexity",
+      "generation_time": "Efficient, generated necessary files",
+      "test_time": "Original project tests failed, MCP plugin tests passed"
+    },
+    "resource_usage": {
+      "memory_efficiency": "Not explicitly measured, assumed efficient due to lack of issues",
+      "cpu_efficiency": "Not explicitly measured, assumed efficient due to lack of issues",
+      "disk_usage": "Minimal, as only one file was processed"
+    }
+  },
+  "technical_quality": {
+    "code_quality_score": 75,
+    "architecture_score": 80,
+    "performance_score": 70,
+    "maintainability_score": 75,
+    "security_score": 85,
+    "scalability_score": 70
+  }
+}

osmnx/source/.pre-commit-config.yaml

@@ -0,0 +1,53 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        args: [--maxkb=50]
+      - id: check-ast
+      - id: check-case-conflict
+      - id: check-executables-have-shebangs
+      - id: check-json
+      - id: check-merge-conflict
+        args: [--assume-in-merge]
+      - id: check-shebang-scripts-are-executable
+      - id: check-toml
+      - id: check-xml
+      - id: check-yaml
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: fix-byte-order-marker
+      - id: mixed-line-ending
+      - id: no-commit-to-branch
+      - id: pretty-format-json
+        args: [--autofix]
+      - id: trailing-whitespace
+
+  - repo: https://github.com/adrienverge/yamllint
+    rev: v1.38.0
+    hooks:
+      - id: yamllint
+        args: [--strict, --config-file=./tests/.yamllint.yml]
+
+  - repo: https://github.com/numpy/numpydoc
+    rev: v1.10.0
+    hooks:
+      - id: numpydoc-validation
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.13
+    hooks:
+      - id: ruff-check
+        args: [--fix, --show-fixes]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.1
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - matplotlib
+          - pandas-stubs
+          - pytest
+          - scipy-stubs
+          - types-requests

osmnx/source/CHANGELOG.md

@@ -0,0 +1,690 @@
+# Changelog
+
+## 2.1.0 (TBD)
+
+- add Python 3.14 support (#1336)
+- drop Python 3.9 and 3.10 support (#1322 #1336)
+- add validation functions to verify that a graph or GeoDataFrame satisfies OSMnx expectations (#1317)
+
+## 2.0.7 (2025-11-25)
+
+- fix TypeError in _getaddrinfo wrapper when host passed both positionally and as keyword (#1340)
+- allow interpolate_points function to run on MultiLineString input (#1341)
+
+## 2.0.6 (2025-08-11)
+
+- handle relations with missing member geometries when loading features from XML (#1334)
+- exclude ways tagged "rest_area" or "services" when downloading network data (#1328)
+
+## 2.0.5 (2025-07-05)
+
+- fix bug that prevents querying or projecting in polar regions (#1324 #1326)
+- improve module exposure for better code introspection (#1308)
+- add "all" optional dependency extra (#1313)
+- bump minimum required patch versions of optional extras to earliest versions with macosx/arm64 wheels (#1313)
+
+## 2.0.4 (2025-06-11)
+
+- fix bug in features module when elements have pre-existing geometry tags (#1298)
+- fix bug in save_graphml function where Gephi compatibility mode erases node attributes (#1300)
+- bump minimum required minor versions of optional extras to earliest versions with linux/amd64 wheels (#1296)
+
+## 2.0.3 (2025-05-06)
+
+- ensure geocoder results are sorted by importance (#1290)
+- update official reference paper and citations (#1293)
+
+## 2.0.2 (2025-03-25)
+
+- fix bug in parsing time when calculating pause duration between requests (#1277)
+- fix bug in round-robin DNS resolution by safely handling missing host argument (#1282)
+- fix bug where consolidate_intersections function would mutate the passed-in graph (#1273)
+- add graph-level "consolidated" attribute if consolidate_intersections has been run (#1273)
+- provide user-friendly error message if consolidate_intersections is run more than once (#1273)
+- refactor internals of caching and pausing between requests (#1279)
+- streamline internal handling of radians throughout package (#1281)
+- improve docstrings (#1272 #1274)
+
+## 2.0.1 (2025-01-01)
+
+- fix error message when elevation module's optional dependencies are missing (#1250)
+- update "walk" network_type to filter out ways whose sidewalks are mapped separately (#1254)
+
+## 2.0.0 (2024-11-24)
+
+Read the v2 [migration guide](https://github.com/gboeing/osmnx/issues/1123)
+
+- add type annotations to all public and private functions throughout package (#1107)
+- remove all functionality previously deprecated in v1 (#1113 #1122 #1135 #1148)
+- add Python 3.13 support (#1223)
+- drop Python 3.8 support (#1106)
+- bump minimum required numpy version to 1.22 for typing support (#1133 #1198)
+- bump minimum required versions of geopandas to 1.0 and pandas to 1.4 for union_all support (#1179 #1198)
+- replace gdal optional dependency with rio-vrt optional dependency (#1203)
+- improve docstrings throughout package (#1116)
+- improve logging and warnings throughout package (#1125)
+- improve error messages throughout package (#1131)
+- improve internal file handling context management (#1226 #1227)
+- refactor features module for speed improvement and memory efficiency (#1157 #1205)
+- refactor save_graph_xml function and \_osm_xml module for speed improvement and bug fixes (#1135)
+- make save_graph_xml function accept only an unsimplified MultiDiGraph as its input data (#1135)
+- replace save_graph_xml function's edge_tag_aggs tuple parameter with way_tag_aggs dict parameter (#1135)
+- add utils_geo.buffer_geometry helper function (#1214)
+- add OSM junction and railway tags to the default settings.useful_tags_node (#1144)
+- add node_attrs_include argument to simplification.simplify_graph function to flexibly relax strictness (#1145)
+- add edge_attr_aggs argument to simplify_graph function to specify aggregation behavior (#1155)
+- add node_attr_aggs argument to the consolidate_intersections function to specify aggregation behavior (#1155)
+- allow per-node tolerance values for intersection consolidation (#1160)
+- make consolidate_intersections function retain unique attribute values when consolidating nodes (#1144)
+- make which_result function parameters consistently able to accept a list throughout package (#1113)
+- handle implicit maxspeed values in add_edge_speeds function (#1153)
+- change add_node_elevations_google default batch_size to 512 to match Google's limit (#1115)
+- better virtual raster handling in elevation module (#1236)
+- use system's default start method when multiprocessing (#1237)
+- allow analysis of MultiDiGraph directional edge bearings and orientation (#1139)
+- allow graph union queries through the custom_filter argument (#1204)
+- fix graph projection creating useless lat and lon node attributes (#1144)
+- fix bug in \_downloader.\_save_to_cache function usage (#1107)
+- fix bug in handling requests ConnectionError when querying Overpass status endpoint (#1113)
+- fix minor bugs throughout to address inconsistencies revealed by type enforcement (#1107 #1114)
+- make optional function parameters keyword-only throughout package (#1134)
+- make dist function parameters required rather than optional throughout package (#1134)
+- make utils_geo.bbox_from_point function return a tuple of floats for consistency with rest of package (#1113)
+- make bounding box coordinate order consistently left, bottom, right, top (#1196)
+- rename truncate.truncate_graph_dist max_dist argument to dist for consistency with rest of package (#1134)
+- remove retain_all argument from all truncate module functions (#1148)
+- remove settings module's deprecated and now replaced settings (#1129 #1136)
+- rename osm_xml module to \_osm_xml to make it private, as all its functions are private (#1113)
+- rename private \_downloader module to \_http (#1114)
+- remove unnecessary private \_api module (#1114)
+
+## 1.9.4 (2024-07-24)
+
+- pin maximum dependency versions for remaining v1 releases
+- add warning to note that the order of bounding box coordinates will change in v2
+
+## 1.9.3 (2024-05-01)
+
+- update the official package reference paper (#1169)
+- rename network_types "all" -> "all_public" and "all_private" -> "all" for clarity (#1164)
+- deprecate the obsolete "all_private" network_type name (#1164)
+
+## 1.9.2 (2024-04-02)
+
+- deprecate and replace settings module's default_accept_language, default_referer, and default_user_agent settings (#1138)
+- deprecate and replace settings module's memory, nominatim_endpoint, overpass_endpoint, and timeout settings (#1138)
+- deprecate save_graph_xml function's renamed or obsolete parameters (#1138)
+- deprecate graph_from_xml tags and polygon function parameters (#1146)
+- deprecate simplify_graph function's endpoint_attrs argument and replace it with edge_attrs_differ (#1146)
+- deprecate utils_graph.get_digraph function and replace it with covert.to_digraph function (#1146)
+- deprecate utils_graph.get_undirected function and replace it with covert.to_undirected function (#1146)
+- deprecate utils_graph.graph_to_gdfs function and replace it with covert.graph_to_gdfs function (#1146)
+- deprecate utils_graph.graph_from_gdfs function and replace it with covert.graph_from_gdfs function (#1146)
+- deprecate utils_graph.remove_isolated_nodes function (#1156)
+- deprecate utils_graph.get_largest_component function and replace it with truncate.largest_component function (#1146)
+- deprecate utils_graph.route_to_gdf function and replace it with routing.route_to_gdf function (#1146)
+- deprecate speed module and move all of its functionality to the routing module (#1146)
+
+## 1.9.1 (2024-02-01)
+
+- fix deprecation warning in simplification.simplify_graph function (#1126)
+
+## 1.9.0 (2024-01-31)
+
+- add endpoint_attrs argument to simplification.simplify_graph function to flexibly relax strictness (#1117)
+- fix a bug in the features module's polygon handling (#1104)
+- update obsolete numpy random number generation (#1108)
+- make deprecation warnings FutureWarnings (#1124)
+- update warning messages to note that deprecated code will be removed in v2.0.0 (#1111)
+- deprecate strict argument in simplification.simplify_graph function in favor of new endpoint_attrs argument (#1117)
+- deprecate north, south, east, west arguments throughout package in favor of bbox tuple argument (#1112)
+- deprecate return_coords argument in graph.graph_from_address function (#1105)
+- deprecate return_hex argument in plot.get_colors function (#1109)
+- deprecate address, point, network_type, edge_color, and smooth_joints arguments in plot.plot_figure_ground function (#1121)
+
+## 1.8.1 (2023-12-31)
+
+- fix a bug arising from the save_graph_xml function (#1093)
+- warn user if their query area is significantly larger than max query area size (#1101)
+- refactor utils_geo module and deprecate quadrat_width and min_num function arguments (#1100)
+- under-the-hood code clean-up (#1092 #1099 #1103)
+
+## 1.8.0 (2023-11-30)
+
+- formally support Python 3.12 (#1082)
+- fix Windows-specific character encoding issue when reading XML files (#1084)
+- resolve pandas and gdal future warnings (#1089)
+- use spawn instead of fork for multiprocessing to resolve Python 3.12 deprecation warning (#1089)
+- rename add_node_elevations_google function's max_locations_per_batch parameter, with deprecation warning (#1088)
+- move add_node_elevations_google function's url_template parameter to settings module, with deprecation warning (#1088)
+
+## 1.7.1 (2023-10-29)
+
+- fix references to latitude and longitude parameters as lat and lon consistently across package (#1068 #1069)
+- fix handling of dict and set attribute types when reloading GraphML files (#1075 #1077)
+
+## 1.7.0 (2023-10-11)
+
+- improve automatic UTM handling in the projection module (#1059)
+- add a to_latlong parameter to the projection.project_graph function for API consistency (#1057)
+- workaround for pytest issue with printing to terminal window on Windows (#1064)
+- refactor the distance module and add a new routing module (#1063)
+- move shortest_path and k_shortest_paths functions to new routing module, with deprecation warning (#1063)
+- rename great_circle_vec and euclidean_dist_vec functions to great_circle and euclidean, with deprecation warning (#1063)
+- under-the-hood code clean-up (#1047)
+
+## 1.6.0 (2023-07-28)
+
+- fix DNS resolution in Dask clusters (#1039)
+- improve memory efficiency during features GeoDataFrame creation (#1043)
+- handle the settings.cache_only_mode option in the features module (#1043)
+- deprecate the buffer_dist and clean_periphery function parameters throughout package (#1044)
+- add more descriptive exceptions: ResponseStatusCodeError and GraphSimplificationError (#1041)
+- replace CacheOnlyModeInterrupt exception with CacheOnlyInterruptError exception (#1041)
+- replace EmptyOverpassResponse exception with InsufficientResponseError exception (#1041)
+- refactor elevation module (#1042 #1043)
+- refactor the \_downloader module and add new \_overpass and \_nominatim modules (#1043)
+- under-the-hood code clean-up (#1036 #1037 #1038)
+
+## 1.5.1 (2023-07-08)
+
+- improve memory efficiency during graph creation (#1021 #1029)
+- improve log messaging (#1032)
+- add version number to XML generator attribute in save_graph_xml (#1031)
+- warn user if loading a .osm XML file generated by OSMnx itself (#1031)
+- add style keyword argument to citation function (#1034)
+
+## 1.5.0 (2023-06-28)
+
+- fix bug in save_graph_xml due to roundabout ways (#986 #999)
+- fix GeoPandas future warning (#1012)
+- make API key properly optional in elevation.add_node_elevations_google function (#999)
+- rename geometries module as features module and deprecate geometries module (#1007 #1011)
+- remove private \_polygon_features module and move its data to features module (#994)
+- make the internal downloader module private (#1010)
+- deprecate interpolate parameter in distance.nearest_edges function (#1010)
+- move save_graph_xml function to io module with deprecation warning in osm_xml module (#1017)
+- migrate from setup.py, setup.cfg, and requirements.txt to pyproject.toml (#1002)
+- pin optional dependencies to minimum required versions (#995)
+- expand and reorganize the documentation (#993)
+
+## 1.4.0 (2023-06-11)
+
+- verify edge weight attribute values before solving shortest paths (#967)
+- provide consistent error when no data elements are returned from Overpass (#960)
+- add route_to_gdf function to utils_graph module to return a GeoDataFrame of the edges in a path (#957)
+- deprecate the get_route_edge_attributes function in favor of the new route_to_gdf function (#957)
+- deprecate folium module in favor of using geopandas.GeoDataFrame.explore directly (#957)
+- deprecate precision parameter in bearing, distance, elevation, and speed modules' functions (#981)
+- deprecate utils_geo.round_geometry_coords function (#981)
+- move plot_orientation function from bearing module to plot module (#956)
+- make matplotlib an optional dependency required only for the plot module (#976)
+- drop pyproj package dependency (#980)
+
+## 1.3.1.post0 (2023-05-26)
+
+- restore Python 3.8 compatibility (#965)
+
+## 1.3.1 (2023-05-24)
+
+- improve DNS resolution when using proxies or on networks blocking DNS-over-HTTPS (#924 #953)
+- improve processing of per-lane values when adding edge speeds (#944 #955)
+- improve file writing in save_graph_xml function (#917 #961)
+- ensure node coordinates are non-null and convertible to float in the add_edge_lengths function (#950)
+- ignore ways tagged highway=no or highway=razed in built-in filters (#938)
+- do not assume an edge with key=0 exists between each node pair when simplifying graph (#921)
+- drop dateutil package dependency (#919)
+
+## 1.3.0 (2023-01-01)
+
+- fully support Shapely 2.0 and drop support for Shapely 1.x (#900)
+- drop RTree package dependency (#900)
+- much faster nearest edges search using STRTree index (#900)
+- allow using alternative Google Maps compatible elevation APIs, such as Open Topo Data (#901 #903)
+- optionally track merged_edges as a new edge attribute in simplify_graph function (#892 #909)
+
+## 1.2.3 (2022-12-14)
+
+- fix bug that added unsimplified edge geometry attributes when projecting
+- hard code Google DNS IP address
+- resolve matplotlib deprecation warning
+- deprecate save_graph_shapefile function
+
+## 1.2.2 (2022-08-05)
+
+- fix compatibility with rasterio 1.3
+- fix API version when saving OSM XML
+- resolve shapely deprecation warning
+
+## 1.2.1 (2022-06-16)
+
+- fix rate limit checking and pausing on newest versions of Overpass API
+- allow add_edge_lengths function to be run on a subset of edges
+- resolve pandas deprecation warning
+
+## 1.2.0 (2022-05-23)
+
+- add ability to load GraphML string data to the load_graphml function
+- add "reversed" edge attribute to support node-order-dependent edge attributes
+- add new edge_color and edge_linewidth arguments to plot_footprints function
+- fix nearest_edges function selecting arbitrary edge when bounding boxes overlap
+- fix get_digraph function's parallel edge handling
+- fix pandas and geopandas version compatibility
+- fix log output appearing in Jupyter notebooks on Unix-like systems
+- remove old functions and arguments previously deprecated in v1.1
+- deprecate utils.config function in favor of using settings module directly
+
+## 1.1.2 (2021-11-17)
+
+- fix geocoding when no geojson is returned
+- fix graph simplification to properly handle travel_time edge attributes
+- fix streets per node not being calculated when clean_periphery=False
+- allow user-defined aggregation function when imputing missing edge speeds
+- allow user to configure requests package keyword arguments when connecting to APIs
+- faster graph projection by calculating UTM zone number with a computationally cheaper method
+- improve efficiency of quadrat-based geometry cutting
+- fall back on google dns resolution when necessary if using a proxy
+- move count_streets_per_node function to stats module
+- resolve shapely and geopandas deprecation warnings
+
+## 1.1.1 (2021-05-19)
+
+- fix overpass status endpoint checks with explicit IP address resolution
+- fix slot management on local overpass instances by optionally disabling rate limiting
+- parallelize shortest_path calculation for multiple origins/destinations
+
+## 1.1.0 (2021-05-01)
+
+- add graph-constrained spatial sampling function
+- add add_node_elevations_raster function to add node elevations from local raster file(s)
+- add add_node_elevations_google function and deprecate old add_node_elevations function
+- add faster streamlined nearest_nodes and nearest_edges functions to distance module
+- deprecate old get_nearest_node, get_nearest_nodes, get_nearest_edge, and get_nearest_edges
+- add utils_geo.interpolate_points function and deprecate redistribute_vertices in favor of it
+- add vectorized calculate_bearing function and deprecate get_bearing in favor of it
+- expose individual street network stats functions in stats module
+- deprecate the extended_stats function in stats module
+- add network orientation and entropy stats functions to bearing module
+- add plot_orientation function to bearing module to polar histograms of graph edge bearings
+- add route_linewidths parameter to plot_graph_routes function
+- handle relations of type "boundary" in geometries module
+- multi-index GeoDataFrames returned from geometries module by element type and osmid
+- ensure all nodes have integer IDs after graph intersection consolidation
+- vectorize add_edge_lengths, add_edge_grades, and add_edge_bearings functions
+- improve save_graph_xml speed
+- improve geocoder module error messages
+- improve handling of node geometry when converting graph to/from GeoDataFrames
+- fix network_type filters allowing ways tagged "bus_guideway"
+- fix handling of boolean type conversion in load_graphml
+- fix truncate_graph_dist retaining unreachable nodes
+- fix bug in consolidate_intersections when pygeos is installed
+- move add_edge_lengths function from utils_graph to distance module
+- remove descartes dependency in line with geopandas
+
+## 1.0.1 (2021-01-13)
+
+- fix network_type filters allowing ways tagged "planned"
+- fix "drive" network_type allowing some alleys
+- fix intersection consolidation for compatibility with v1.0 node ids/indexing
+- fix python 3.6 compatibility
+- deprecate folium polyline styling arguments
+
+## 1.0.0 (2021-01-01)
+
+- set use_cache=True by default
+- add ability to query a place by OSM ID in geocoder.geocode_to_gdf function
+- add optional setting for download/cache-only mode
+- replace md5 with sha1 for cache filename hashing
+- replace streets_per_node graph attribute with equivalent street_count node attribute
+- remove redundant osmid node attribute
+- make graph_to_gdfs multi-index the edges GeoDataFrame by u, v, key
+- refactor consolidate_intersections function for better speed and efficiency
+- refactor count_streets_per_node function for better speed and efficiency
+- refactor folium module for better speed and efficiency
+- refactor get_undirected functionality for better speed and efficiency
+- extract all private/internal .osm XML functionality into new osm_xml module
+- deprecate io.save_graph_xml with warning (function moved to osm_xml module)
+- remove internal \_is_simplified function
+- remove deprecated pois module
+- remove deprecated footprints module
+- remove deprecated utils_graph.induce_subgraph function
+- remove deprecated node_type parameter from io.load_graphml function
+
+## 0.16.2 (2020-11-17)
+
+- improve graph_from_gdfs speed and efficiency
+- improve plot_route_folium speed and efficiency
+- fix remove_isolated_nodes function mutating the passed-in graph
+- fix gephi compatibility in save_graphml
+- add customizable node/edge attribute data type arguments to load_graphml
+- deprecate old node_type argument in load_graphml
+- expose bidirectional_network_types via config function
+
+## 0.16.1 (2020-10-05)
+
+- fix handling graphs with no intersections in consolidate_intersections
+- fix consolidate_intersections returning GeoSeries without CRS attribute
+- fix response caching to save only when status code is 200
+- fix elevation module's grade absolute value calculation when grade is null
+- move shortest path functions from utils_graph module to distance module
+
+## 0.16.0 (2020-09-07)
+
+- new geometries module for creating GeoDataFrames from tag/value queries
+- deprecate old pois and footprints modules (replaced by geometries module)
+- auto-select first Polygon/MultiPolygon when geocoding with which_result=None
+- new k*shortest_paths function to solve \_k* shortest paths from origin to destination
+- new shortest_path convenience function
+- new get_digraph function to correctly convert MultiDiGraph to DiGraph
+- miscellaneous performance improvements and optimizations
+- deprecate induce_subgraph function
+- remove deprecated boundaries module (replaced by geocoder module in v0.15.0)
+- remove deprecated utils_geo.geocode function (replaced by geocoder.geocode function in v0.15.0)
+
+## 0.15.1 (2020-07-03)
+
+- fix geopandas future warnings
+
+## 0.15.0 (2020-06-30)
+
+- improve plotting defaults and streamline plot module speed and efficiency
+- improve color handling in plot module
+- improve route plotting
+- plot_graph_routes function now accepts multiple route colors
+- allow multiple elevation API providers
+- consolidate_intersections replaces update_edge_lengths param with reconnect_edges param
+- fix geopackage file saving after consolidating intersections
+- add new geocoder module and move utils_geo.geocode function into it
+- replace gdf_from_place/s functions with geocoder.geocode_to_gdf
+- deprecate boundaries module
+- remove deprecated timeout, memory, custom_settings, and max_query_area_size function params
+- remove deprecated plotting params and plot_shape function
+
+## 0.14.1 (2020-06-09)
+
+- fix simplification of graphs with long rural roads
+- reduce memory footprint of graph simplification
+- remove disconnected self-contained rings from graph by default when simplifying
+- improve speed and efficiency of project_graph, graph_to_gdfs, and graph_from_gdfs
+- improve attribute value conversion in load_graphml
+- expose precision parameter for adding bearings, elevations, speeds, and travel times
+- fix config function clobber behavior
+- fix graph periphery cleaning when clean_periphery=True but simplify=False
+- rename settings useful_tags_path to the more appropriate useful_tags_way
+- deprecate the timeout, memory, custom_settings, and max_query_area_size function params
+- the params above are now accessible via config function and settings module
+- deprecate old plot params and plot_shape function
+- remove previously deprecated infrastructure parameter in favor of custom_filter
+
+## 0.14.0 (2020-06-03)
+
+- better geometry subdividing for huge OSM queries
+- better handling of maxspeed list values for simplified graphs
+- downloader only retrieves url response from cache if no server remark
+- deprecate graph creation infrastructure parameter in favor of flexible custom_filter
+- remove deprecated functions: graph_from_file, clean_intersections, gdfs_to_graph
+
+## 0.13.0 (2020-05-25)
+
+- major refactor of entire package
+- clean up API and namespace
+- new consolidate_intersections function with topological option
+- new speed module to calculate graph edge speeds and travel times
+- generalize POIs module to query with a flexible tags dict
+- allow folium functions to accept FeatureGroup and kwargs
+- all graph saving functions now take a filepath argument instead of folder/filename
+- save shapefiles in single folder containing both nodes and edges
+- optionally return distance and/or geometry in nearest edge search
+- expose timeout and memory parameters in pois and footprints modules
+- define default crs via epsg code instead of proj4 string
+- update and simplify logging with timestamps
+- graph metadata: add creation date and version, remove name
+- replace inconsistent distance parameters with consistent dist parameters
+- deprecate old clean_intersections function in favor of new consolidate_intersections
+- deprecate old gdfs_to_graph function in favor of graph_from_gdfs
+- deprecate old graph_from_file function in favor of graph_from_xml
+- rename save_as_osm function -> save_graph_xml for consistency
+- rename save_load module -> io
+- remove old save_gdf_shapefile function
+- drop support for python 3.5 and lower
+
+## 0.12.1 (2020-05-01)
+
+- fix handling relations with missing type tag
+- fix save_graph_geopackage handling numeric attributes
+- fix load_graphml handling elevation and grade attributes
+- improve edge finding algorithms to return edge key
+- more informative graph_from_file data load error message
+- refactor url-in-cache checking
+- add timestamp helper function
+- documentation improvements
+
+## 0.12 (2020-04-10)
+
+- add ability to save graph as geopackage file
+- add truncate_by_edge implementation in truncate_graph_polygon
+- allow flexible overpass settings (e.g., to query by date)
+- better handling of invalid footprint geometries
+- geocode function now uses nominatim_request function
+- improve .osm xml output
+- improve one-way street handling
+- fix graph projection overwriting original lat/lng
+- fix redistribute_vertices function for MultiLineStrings
+
+## 0.11.4 (2020-01-31)
+
+- fix .osm xml output
+- fix for pandas 1.0
+
+## 0.11.3 (2020-01-09)
+
+- fix errant print statement
+
+## 0.11.2 (2020-01-07)
+
+- fix .osm xml output
+- fix geopandas future compatibility
+
+## 0.11.1 (2020-01-01)
+
+- fix get_nearest_edges search when not using a spatial index
+
+## 0.11 (2019-12-04)
+
+- drop formal python 2 support
+- refactor all modules for cleaner package organization
+- make stats betweenness centrality compatible with networkx>=2.4
+- allow configurable overpass and nominatim endpoints
+- allow gdf_from_places to take a which_result list argument
+- handle zero-division in street grade calculation
+- better footprint relation handling
+- improve network type queries for better filtering
+- fix pois_from_polygon returning points outside polygon
+
+## 0.10 (2019-05-08)
+
+- remove deprecated buildings module
+- filter steps ways out of bike queries
+- convert CRS-handling to proj4 strings
+- save graph to xml-formatted .osm file
+- minor refactoring
+
+## 0.9 (2019-01-28)
+
+- deprecate buildings module and replace with generalized footprints module
+- improve handling of multipolygon footprints
+- new function to find nearest edge(s), given coordinates
+- add "search," "reverse," and "lookup" nominatim queries
+- use unprojected graphs for figure-ground plotting functions
+- allow non-integer osmid values for custom data
+- improve get_route_edge_attributes function
+- improve color mapping by node/edge attribute value
+- make bidirectional network types explicit
+- networkx compatibility fixes to resolve warnings
+
+## 0.8.2 (2018-09-19)
+
+- add python 3.7 compatibility
+- add convenience function to plot several routes over the same map
+- optimize graph truncation to bounding box
+- give self-loops a null bearing when calculating edge bearings
+- make accept-language http header explicit and configurable
+- add citation function
+- refactor POI module
+
+## 0.8.1 (2018-05-17)
+
+- add Gephi compatibility argument for saving GraphML
+- handle square bracket encapsulated strings when loading GraphML
+
+## 0.8 (2018-05-05)
+
+- add ability to retrieve points of interest
+- improve performance for retrieving huge geographies' street networks
+- fix building footprint retrieval query syntax
+- minor bug fixes
+
+## 0.7.4 (2018-04-05)
+
+- add fast nearest-nodes search
+- allow custom network query filters
+- allow create_graph to return graph with no edges
+- improve figure_ground joint smoothing
+- fix handling of parallel edges when making multidigraph undirected
+- generalize same-geometry checker
+- improve detection of prior topology simplification
+- custom error types for finer-grained handling
+
+## 0.7.3 (2018-03-12)
+
+- turn off x- and y-axes to improve plotting appearance
+- make floating-point precision and rounding more sensible
+- improve OS path handling cross-platform
+- replace great-circle distance calculator with haversine
+- add access filter as configurable setting
+- improve performance of inducing subgraphs
+- fix utils.get_largest_component for networkx 2.2 compatibility
+- fix config settings namespacing
+
+## 0.7.2 (2018-02-15)
+
+- compatibility with networkx 2.1
+
+## 0.7.1 (2018-02-04)
+
+- fix documentation build
+- ignore ways marked access=no
+
+## 0.7 (2018-02-01)
+
+- ability to load a graph from a .osm file
+- change datum from NAD83 to WGS84
+- make roundabouts one-way
+- conformal plotting for unprojected graphs
+- fix folium web maps rendering
+
+## 0.6 (2017-10-02)
+
+- migrate to the networkx 2.0 API
+
+## 0.5.4 (2017-09-16)
+
+- add optional cleaned intersections count to basic stats
+- allow circuity to be calculated for projected or unprojected networks
+- various code clean-up and refactoring
+
+## 0.5.3 (2017-07-22)
+
+- add requirements files to distribution
+
+## 0.5.2 (2017-07-22)
+
+- add ability to download other infrastructures besides just roads/paths (e.g., rail lines, power lines, etc.)
+- calculate graph edges' bearings
+- add ability to get nearest node by great circle or euclidean distance
+- move examples/demo notebooks to new repo: osmnx-examples
+- fix docstrings
+- fix building footprint downloads that require multiple calls for large areas
+- fix missing MultiPolygon import in buildings module
+
+## 0.5.1 (2017-05-12)
+
+- functionality to clean-up and consolidate complex intersections
+- let save_gdf_shapefile save building footprint GeoDataFrames
+- set node color correctly in figure-ground diagrams
+
+## 0.5 (2017-04-25)
+
+- add elevation module to get node elevations and street grades
+- new color sequence creation and conversion functions in plot module
+- new function to get a path's edge attribute values
+- gracefully handle subpolygons that are invalid or have zero area
+- make truncate_graph_polygon work on projected graphs
+- plot_shape accepts a color or a list of colors
+- make all requests to Overpass API set custom user-agent and referer
+- rewrite algorithms to convert multidigraphs to multigraphs
+
+## 0.4.1 (2017-04-01)
+
+- fix load_graphml so we can save a graph again after loading it
+- fix load_graphml so edge oneway attribute is not always set to True
+- buildings module gets buildings stored in OSM as relations as well as ways
+- fix figure-ground diagram saving to make perfect square and smooth joints
+- add optional graph argument to plot_figure_ground
+- suppress jupyter notebook deprecation warnings
+
+## 0.4 (2017-03-01)
+
+- plot entire networks with folium
+- plot routes on top of networks with folium
+- vectorize all great circle calculations
+- new geocode function in utils
+- remove geopy dependency
+- refactor modules
+- simplify before truncating by distance when getting graph by point and network distance
+- project geometries, GeoDataFrames, and graphs to a passed-in CRS
+
+## 0.3.1 (2017-02-15)
+
+- clean up docstrings throughout
+- remove network code vestiges from buildings.py
+
+## 0.3 (2017-01-29)
+
+- add route plotting with folium
+- add downloading and visualization of building footprints
+- updates for compatibility with matplotlib 2.0
+
+## 0.2.2 (2017-01-20)
+
+- fixes for compatibility with networkx 2.0's new API
+- make png default image save format
+- figure-ground plots collect street network from a wider area
+
+## 0.2.1 (2017-01-11)
+
+- add license file to dist package
+
+## 0.2 (2017-01-10)
+
+- refactor modules
+- add graph to GDF and GDF to graph functions
+- add encoding argument to save_graph_shapefile
+- add unit tests and continuous integration
+
+## 0.1 (2016-12-19)
+
+- add street width attribute for ways from OSM
+
+## 0.1b2 (2016-11-29)
+
+- make simplification error messages explicit
+
+## 0.1b1 (2016-11-28)
+
+- process land use and area tags from OSM
+- make intersection error messages clear
+
+## 0.1a1 (2016-11-07)
+
+- first pre-release

osmnx/source/CITATION.cff

@@ -0,0 +1,32 @@
+cff-version: 1.2.0
+title: OSMnx
+message: If you use OSMnx, please cite the preferred-citation below.
+type: software
+authors:
+  - family-names: Boeing
+    given-names: Geoff
+    orcid: https://orcid.org/0000-0003-1851-6411
+identifiers:
+  - type: doi
+    value: 10.1111/gean.70009
+    description: Official reference paper
+repository-code: https://github.com/gboeing/osmnx
+url: https://osmnx.readthedocs.org
+abstract: >-
+  OSMnx is a Python package to easily download, model, analyze, and visualize
+  street networks and other geospatial features from OpenStreetMap.
+license: MIT
+preferred-citation:
+  type: article
+  authors:
+    - family-names: Boeing
+      given-names: Geoff
+      orcid: https://orcid.org/0000-0003-1851-6411
+  year: 2025
+  title: Modeling and Analyzing Urban Networks and Amenities with OSMnx
+  journal: Geographical Analysis
+  volume: 57
+  issue: 4
+  start: 567
+  end: 577
+  doi: 10.1111/gean.70009

osmnx/source/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing guidelines
+
+Thanks for using OSMnx and for considering contributing to it by opening an issue or pull request. Every piece of software is a work in progress. This project is the result of many hours of work contributed freely its contributors and the many people that build the projects on which it depends. Thank you for contributing!
+
+## If you have a "how-to" or usage question
+
+Please ask your question on [StackOverflow](https://stackoverflow.com/search?q=osmnx), as we reserve the issue tracker for bug reports and new feature development. Any such questions asked in the issue tracker will be automatically closed.
+
+## If you have an installation problem
+
+Ensure you have followed the installation instructions in the [documentation](https://osmnx.readthedocs.io/). If you installed OSMnx via conda-forge, please open an issue at its [feedstock](https://github.com/conda-forge/osmnx-feedstock/issues).
+
+## If you have a feature proposal
+
+The OSMnx project follows three principles when considering new functionality: 1) it is useful for a broad set of users, 2) it generalizes well, and 3) it is not trivially easy for users to implement themselves.
+
+- Post your proposal on the [issue tracker](https://github.com/gboeing/osmnx/issues), and _provide all the information requested in the template_, so we can review it together (some proposals may not be a good fit for the project).
+- Fork the repo, make your change, update the [changelog](./CHANGELOG.md), run the [tests](./tests), and submit a pull request.
+- Adhere to the project's code and docstring standards by running its [pre-commit](.pre-commit-config.yaml) hooks.
+- Respond to code review.
+
+## If you found a bug
+
+- Read the error message, then review the [documentation](https://osmnx.readthedocs.io/) and OSMnx [Examples Gallery](https://github.com/gboeing/osmnx-examples), which cover key concepts, installation, and package usage.
+- Search through the open and closed [issues](https://github.com/gboeing/osmnx/issues) to see if the problem has already been reported.
+- If the problem is with a dependency of OSMnx, open an issue in that dependency's repo.
+- If the problem is with OSMnx itself and you can fix it simply, please open a pull request.
+- If the problem persists, please open an issue in the [issue tracker](https://github.com/gboeing/osmnx/issues), and _provide all the information requested in the template_, including a minimal standalone example so others can independently and completely reproduce the bug.
+
+## Creating a minimal standalone reproducible example
+
+We need a minimal standalone example code snippet to be able to reproduce and in turn troubleshoot your problem (also provide the resulting complete error traceback if your code generates an error). This code snippet must be:
+
+_Minimal_: the absolute fewest lines of code necessary to reproduce your problem without any extraneous code or data unrelated to your specific problem. This usually requires reworking your code and data down to just a few lines necessary to generate the error.
+
+_Standalone_: all imports, data, and variables must be completely defined within the snippet itself so others can independently run it from top to bottom by copying/pasting it into a Python interpreter. Do not link to or load external files and do not provide screenshots of code or error messages: provide all code, data, and tracebacks inline as text.
+
+If you're unsure how to create a good reproducible example, read
+        [this guide](https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports).

osmnx/source/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016-2025 Geoff Boeing https://geoffboeing.com/
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

osmnx/source/README.md

@@ -0,0 +1,33 @@
+# OSMnx
+
+[![PyPI Version](https://badge.fury.io/py/osmnx.svg)](https://pypi.org/project/osmnx/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/osmnx?period=total&units=international_system&left_color=grey&right_color=brightgreen&left_text=downloads)](https://pepy.tech/project/osmnx)
+[![Documentation Status](https://readthedocs.org/projects/osmnx/badge/?version=latest)](https://osmnx.readthedocs.io/)
+[![Build Status](https://github.com/gboeing/osmnx/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gboeing/osmnx/actions/workflows/ci.yml)
+[![Coverage Status](https://codecov.io/gh/gboeing/osmnx/branch/main/graph/badge.svg)](https://codecov.io/gh/gboeing/osmnx)
+
+**OSMnx** is a Python package to easily download, model, analyze, and visualize street networks and other geospatial features from OpenStreetMap. You can download and model walking, driving, or biking networks with a single line of code then analyze and visualize them. You can just as easily work with urban amenities/points of interest, building footprints, transit stops, elevation data, street orientations, speed/travel time, and routing.
+
+## Citation
+
+If you use OSMnx in your work, please cite the paper:
+
+Boeing, G. (2025). [Modeling and Analyzing Urban Networks and Amenities with OSMnx](https://doi.org/10.1111/gean.70009). *Geographical Analysis* 57 (4), 567-577. doi:10.1111/gean.70009
+
+## Getting Started
+
+First read the [Getting Started](https://osmnx.readthedocs.io/en/stable/getting-started.html) guide for an introduction to the package and FAQ.
+
+Then work through the [Examples Gallery](https://github.com/gboeing/osmnx-examples) for step-by-step tutorials and sample code.
+
+## Installation
+
+Follow the [Installation](https://osmnx.readthedocs.io/en/stable/installation.html) guide to install OSMnx.
+
+## Support
+
+If you have any trouble, consult the [User Reference](https://osmnx.readthedocs.io/en/stable/user-reference.html). The OSMnx repository is hosted on [GitHub](https://github.com/gboeing/osmnx). If you have a "how-to" or usage question, please ask it on [StackOverflow](https://stackoverflow.com/search?q=osmnx), as we reserve the repository's issue tracker for bug tracking and feature development.
+
+## License
+
+OSMnx is open source and licensed under the MIT license. OpenStreetMap's open data [license](https://www.openstreetmap.org/copyright/) requires that derivative works provide proper attribution. Refer to the [Getting Started](https://osmnx.readthedocs.io/en/stable/getting-started.html) guide for usage limitations.

osmnx/source/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""
+osmnx Project Package Initialization File
+"""

osmnx/source/docs/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-lts-latest
+  tools:
+    python: '3'
+
+formats: all
+
+python:
+  install:
+    - requirements: ./docs/requirements-docs.txt
+
+sphinx:
+  configuration: ./docs/source/conf.py
+  fail_on_warning: true

osmnx/source/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

osmnx/source/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

osmnx/source/docs/requirements-docs.txt

@@ -0,0 +1,4 @@
+furo
+sphinx>=7
+sphinx-autodoc-typehints
+-e .

osmnx/source/docs/source/conf.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python
+"""
+Configuration file for the Sphinx documentation builder.
+
+For the full list of built-in configuration values, see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
+
+import sys
+from pathlib import Path
+from tomllib import load as toml_load
+
+# project info
+author = "Geoff Boeing"
+copyright = "2016-2025, Geoff Boeing"  # noqa: A001
+project = "OSMnx"
+
+# go up two levels from current working dir (/docs/source) to package root
+pkg_root_path = str(Path.cwd().parent.parent)
+sys.path.insert(0, pkg_root_path)
+
+# dynamically load version
+with Path("../../pyproject.toml").open("rb") as f:
+    pyproject = toml_load(f)
+version = release = pyproject["project"]["version"]
+
+# mock import all required + optional dependency packages because readthedocs
+# does not have them installed
+autodoc_mock_imports = [
+    "geopandas",
+    "matplotlib",
+    "networkx",
+    "numpy",
+    "pandas",
+    "rasterio",
+    "requests",
+    "rio-vrt",
+    "scipy",
+    "shapely",
+    "sklearn",
+]
+
+# linkcheck for some DOI redirects gets HTTP 403 in CI environment
+linkcheck_ignore = [r"https://doi\.org/.*"]
+
+# type annotations configuration
+autodoc_typehints = "description"
+napoleon_use_param = True
+napoleon_use_rtype = False
+typehints_document_rtype = True
+typehints_use_rtype = False
+typehints_fully_qualified = False
+
+# general configuration and options for HTML output
+# see https://www.sphinx-doc.org/en/master/usage/configuration.html
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_autodoc_typehints"]
+html_static_path: list[str] = []
+html_theme = "furo"
+language = "en"
+needs_sphinx = "7"  # match version from pyproject.toml optional-dependencies
+root_doc = "index"
+source_suffix = ".rst"
+templates_path: list[str] = []

osmnx/source/docs/source/further-reading.rst

@@ -0,0 +1,40 @@
+Further Reading
+===============
+
+Boeing, G. (2025). `Modeling and Analyzing Urban Networks and Amenities with OSMnx`_. *Geographical Analysis* 57 (4), 567-577. doi:10.1111/gean.70009
+
+This is the official reference paper and citation for the OSMnx package.
+
+.. _Modeling and Analyzing Urban Networks and Amenities with OSMnx: https://doi.org/10.1111/gean.70009
+
+----
+
+Boeing, G. (2025). `Topological Graph Simplification Solutions to the Street Intersection Miscount Problem`_. *Transactions in GIS* 29 (3), e70037. doi:10.1111/tgis.70037
+
+This paper describes and validates the algorithms implemented in OSMnx's :code:`simplification` module and explains why graph simplification is necessary to accurately measure intersection density, street segment length, node degree, etc.
+
+.. _Topological Graph Simplification Solutions to the Street Intersection Miscount Problem: https://doi.org/10.1111/tgis.70037
+
+----
+
+Boeing, G. (2021). `Street Network Models and Indicators for Every Urban Area in the World`_. *Geographical Analysis* 54 (3), 519-535. doi:10.1111/gean.12281
+
+This study uses OSMnx to model and analyze the street networks of every urban area in the world: over 160 million OpenStreetMap street network nodes and over 320 million edges across 8,914 urban areas in 178 countries.
+
+.. _Street Network Models and Indicators for Every Urban Area in the World: https://geoffboeing.com/publications/street-network-models-indicators-world/
+
+----
+
+Boeing, G. (2020). `The Right Tools for the Job: The Case for Spatial Science Tool-Building`_. *Transactions in GIS* 24 (5), 1299-1314. doi:10.1111/tgis.12678
+
+This paper was presented as the 8th annual Transactions in GIS plenary address at the American Association of Geographers annual meeting in Washington, DC. It describes the early development of OSMnx and reviews its use in scientific research over the previous few years.
+
+.. _The Right Tools for the Job\: The Case for Spatial Science Tool-Building: https://geoffboeing.com/publications/right-tools-for-job/
+
+----
+
+Boeing, G. (2020). `Planarity and Street Network Representation in Urban Form Analysis`_. *Environment and Planning B: Urban Analytics and City Science* 47 (5), 855-869. doi:10.1177/2399808318802941
+
+This paper demonstrates the need for nonplanar graphs when modeling urban street networks, which was one of the original motivations for developing OSMnx.
+
+.. _Planarity and Street Network Representation in Urban Form Analysis: https://geoffboeing.com/publications/planarity-street-network-representation/

osmnx/source/docs/source/getting-started.rst

@@ -0,0 +1,184 @@
+Getting Started
+===============
+
+Get Started in 4 Steps
+----------------------
+
+1. Install OSMnx by following the :doc:`installation` guide.
+
+2. Read the :ref:`introducing-osmnx` section on this page.
+
+3. Work through the OSMnx `Examples Gallery`_ for step-by-step tutorials and sample code.
+
+4. Consult the :doc:`user-reference` for complete details on using the package.
+
+Finally, if you're not already familiar with `NetworkX`_ and `GeoPandas`_, make sure you read their user guides as OSMnx uses their data structures.
+
+.. _introducing-osmnx:
+
+Introducing OSMnx
+-----------------
+
+This quick introduction explains key concepts and the basic functionality of OSMnx.
+
+Overview
+^^^^^^^^
+
+OSMnx is pronounced as the initialism: "oh-ess-em-en-ex". It is built on top of NetworkX and GeoPandas, and interacts with `OpenStreetMap`_ APIs to:
+
+* Download and model street networks or other infrastructure anywhere in the world with a single line of code
+* Download geospatial features (e.g., political boundaries, building footprints, grocery stores, transit stops) as a GeoDataFrame
+* Query by city name, polygon, bounding box, or point/address + distance
+* Model driving, walking, biking, and other travel modes
+* Attach node elevations from a local raster file or web service and calculate edge grades
+* Impute missing speeds and calculate graph edge travel times
+* Simplify and correct the network's topology to clean-up nodes and consolidate complex intersections
+* Fast map-matching of points, routes, or trajectories to nearest graph edges or nodes
+* Save/load network to/from disk as GraphML, GeoPackage, or OSM XML file
+* Conduct topological and spatial analyses to automatically calculate dozens of indicators
+* Calculate and visualize street bearings and orientations
+* Calculate and visualize shortest-path routes that minimize distance, travel time, elevation, etc
+* Explore street networks and geospatial features as a static map or interactive web map
+* Visualize travel distance and travel time with isoline and isochrone maps
+* Plot figure-ground diagrams of street networks and building footprints
+
+The OSMnx `Examples Gallery`_ contains tutorials and demonstrations of all these features, and package usage is detailed in the :doc:`user-reference`.
+
+Configuration
+^^^^^^^^^^^^^
+
+You can configure OSMnx using the ``settings`` module. Here you can adjust logging behavior, caching, server endpoints, and more. You can also configure OSMnx to retrieve historical snapshots of OpenStreetMap data as of a certain date.
+
+Read more about the :ref:`settings <osmnx-settings-module>` module in the User Reference.
+
+Geocoding and Querying
+^^^^^^^^^^^^^^^^^^^^^^
+
+OSMnx geocodes place names and addresses with the OpenStreetMap `Nominatim`_ API. You can use the ``geocoder`` module to geocode place names or addresses to lat-lon coordinates. Or, you can retrieve place boundaries or any other OpenStreetMap elements by name or ID. Read more about the :ref:`geocoder <osmnx-geocoder-module>` module in the User Reference.
+
+Using the ``features`` and ``graph`` modules, as described below, you can download data by lat-lon point, address, bounding box, bounding polygon, or place name (e.g., neighborhood, city, county, etc).
+
+Urban Amenities
+^^^^^^^^^^^^^^^
+
+Using OSMnx's ``features`` module, you can search for and download any geospatial `features`_ (such as building footprints, grocery stores, schools, public parks, transit stops, etc) from the OpenStreetMap `Overpass`_ API as a GeoPandas GeoDataFrame. This uses OpenStreetMap `tags`_ to search for matching `elements`_.
+
+Read more about the :ref:`features <osmnx-features-module>` module in the User Reference.
+
+Modeling a Network
+^^^^^^^^^^^^^^^^^^
+
+Using OSMnx's ``graph`` module, you can retrieve any spatial network data (such as streets, paths, rail, canals, etc) from the Overpass API and model them as NetworkX `MultiDiGraphs`_.
+
+In short, MultiDiGraphs are nonplanar directed graphs with possible self-loops and parallel edges. Thus, a one-way street will be represented with a single directed edge from node *u* to node *v*, but a bidirectional street will be represented with two reciprocal directed edges (with identical geometries): one from node *u* to node *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, bridges, and tunnels. That is, edge crossings in a two-dimensional plane are not intersections in an OSMnx model unless they represent true junctions in the three-dimensional real world.
+
+The ``graph`` module uses filters to query the Overpass API: you can either specify a built-in network type or provide your own custom filter with `Overpass QL`_. Under the hood, OSMnx does several things to generate the best possible model. It initially creates a 500m-buffered graph before truncating it to your desired query area, to ensure accurate streets-per-node stats and to attenuate graph perimeter effects. By default, it returns the largest weakly connected component. It also simplifies the graph topology as discussed below.
+
+Read more about the :ref:`graph <osmnx-graph-module>` module in the User Reference and refer to the official reference paper at the :doc:`further-reading` page for complete modeling details.
+
+Topology Clean-Up
+^^^^^^^^^^^^^^^^^
+
+The ``simplification`` module automatically processes the network's topology from the original raw OpenStreetMap data, such that nodes represent intersections/dead-ends and edges represent the street segments that link them. This takes two primary forms: graph simplification and intersection consolidation.
+
+**Graph simplification** cleans up the graph's topology so that nodes represent intersections or dead-ends and edges represent street segments. This is important because in OpenStreetMap 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 discarding non-intersection/dead-end nodes while retaining the complete true edge geometry as an edge attribute. When multiple OpenStreetMap ways are merged into a single graph edge, the ways' attribute values can be aggregated into a single value.
+
+**Intersection consolidation** 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 think of it in transportation or urban design. Similarly, divided roads are often represented by separate centerline edges: the intersection of two divided roads thus creates 4 nodes, representing 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 merged into a single graph node, the nodes' attribute values can be aggregated into a single value.
+
+Read more about the :ref:`simplification <osmnx-simplification-module>` module in the User Reference.
+
+Model Attributes
+^^^^^^^^^^^^^^^^
+
+An OSMnx model has some standard required attributes, plus some optional attributes. The latter are sometimes present based on the source OSM data's tagging, the ``settings`` module configuration, and any processing you may have done to add additional attributes (as noted in various functions' documentation).
+
+As a NetworkX `MultiDiGraph`_ object, it has top-level ``graph``, ``nodes``, and ``edges`` attributes. The ``graph`` attribute dictionary must contain a "crs" key defining its coordinate reference system. The ``nodes`` are identified by OSM ID and each must contain a ``data`` attribute dictionary that must have "x" and "y" keys defining its coordinates and a "street_count" key defining how many physical streets are incident to it. The ``edges`` are identified by a 3-tuple of "u" (source node ID), "v" (target node ID), and "key" (to differentiate parallel edges), and each must contain a ``data`` attribute dictionary that must have an "osmid" key defining its OSM ID and a "length" key defining its length in meters.
+
+The OSMnx ``graph`` module automatically creates MultiDiGraphs with these required attributes, plus additional optional attributes based on the ``settings`` module configuration. If you instead manually create your own graph model, make sure it has these required attributes at a minimum.
+
+Convert, Project, Save
+^^^^^^^^^^^^^^^^^^^^^^
+
+OSMnx's ``convert`` module can convert a MultiDiGraph to a `DiGraph`_ if you prefer a directed representation of the network without any parallel edges, or to a `MultiGraph`_ if you need an undirected representation for use with functions or algorithms that only accept a MultiGraph object. If you just want a fully bidirectional graph (such as for a walking network), just configure the ``settings`` module's ``bidirectional_network_types`` before creating your graph.
+
+The ``convert`` module can also convert a MultiDiGraph to/from GeoPandas node and edge `GeoDataFrames`_. The nodes GeoDataFrame is indexed by OSM ID and the edges GeoDataFrame is multi-indexed by ``u, v, key`` just like a NetworkX edge. This allows you to load arbitrary node/edge ShapeFiles or GeoPackage layers as GeoDataFrames then model them as a MultiDiGraph for graph analysis. The ``convert`` module exposes validation functions to verify that your MultiDiGraph or GeoDataFrames satisfy OSMnx requirements. Read more about the :ref:`convert <osmnx-convert-module>` module in the User Reference.
+
+You can easily project your graph to different coordinate reference systems using the ``projection`` module. If you're unsure which `CRS`_ you want to project to, OSMnx can automatically determine an appropriate UTM CRS for you. Read more about the :ref:`projection <osmnx-projection-module>` module in the User Reference.
+
+Using the ``io`` module, you can save your graph to disk as a GraphML file (to load into other network analysis software), a GeoPackage (to load into other GIS software), or an OSM XML file. Use the GraphML format whenever saving a graph for later work with OSMnx. Read more about the :ref:`io <osmnx-io-module>` module in the User Reference.
+
+Network Measures
+^^^^^^^^^^^^^^^^
+
+You can use the ``stats`` module to calculate a variety of geometric and topological measures as well as street network bearing and orientation statistics. These measures define streets as the edges in an undirected representation of the graph to prevent double-counting bidirectional edges of a two-way street. You can easily generate common stats in transportation studies, urban design, and network science, including intersection density, circuity, average node degree (connectedness), betweenness centrality, and much more. Read more about the :ref:`stats <osmnx-stats-module>` module in the User Reference.
+
+You can also use NetworkX directly to calculate additional topological network measures.
+
+Working with Elevation
+^^^^^^^^^^^^^^^^^^^^^^
+
+The ``elevation`` module lets you automatically attach elevations to the graph's nodes from a local raster file or the Google Maps `Elevation API`_ (or equivalent web API with a compatible interface). You can also calculate edge grades (i.e., rise-over-run) and analyze the steepness of certain streets or routes.
+
+Read more about the :ref:`elevation <osmnx-elevation-module>` module in the User Reference.
+
+Routing
+^^^^^^^
+
+The ``distance`` module can find the nearest node(s) or edge(s) to coordinates using a fast spatial index. The ``routing`` module can solve shortest paths for network routing, parallelized with multiprocessing, using different weights (e.g., distance, travel time, elevation change, etc). It can also impute missing speeds to the graph edges. This imputation can obviously be imprecise, so the user can override it by passing in arguments that define local speed limits. It can also calculate free-flow travel times for each edge.
+
+Read more about the :ref:`distance <osmnx-distance-module>` and :ref:`routing <osmnx-routing-module>` modules in the User Reference.
+
+Visualization
+^^^^^^^^^^^^^
+
+You can plot graphs, routes, network figure-ground diagrams, building footprints, and street network orientation rose diagrams (aka, polar histograms) with the ``plot`` module. You can also explore street networks, routes, or geospatial features as interactive `Folium`_ web maps.
+
+Read more about the :ref:`plot <osmnx-plot-module>` module in the User Reference.
+
+Usage Limits
+^^^^^^^^^^^^
+
+Refer to the `Nominatim Usage Policy`_ and `Overpass Commons`_ documentation for API usage limits and restrictions to which you must adhere. If you configure OSMnx to use an alternative API instance, ensure you understand and follow their policies. If you feel you need to exceed these limits, consider installing your own hosted instance and setting OSMnx to use it.
+
+More Info
+---------
+
+All of this functionality is demonstrated step-by-step in the OSMnx `Examples Gallery`_, and usage is detailed in the :doc:`user-reference`. Feature development details are in the `Changelog`_. Consult the :doc:`further-reading` resources for additional technical details and research.
+
+Frequently Asked Questions
+--------------------------
+
+*How do I install OSMnx?* Follow the :doc:`installation` guide.
+
+*How do I use OSMnx?* Check out the step-by-step tutorials in the OSMnx `Examples Gallery`_.
+
+*How does this or that function work?* Consult the :doc:`user-reference`.
+
+*What can I do with OSMnx?* Check out recent `projects`_ that use OSMnx.
+
+*I have a usage question.* Please ask it on `StackOverflow`_.
+
+
+.. _Changelog: https://github.com/gboeing/osmnx/blob/main/CHANGELOG.md
+.. _CRS: https://en.wikipedia.org/wiki/Coordinate_reference_system
+.. _DiGraph: https://networkx.org/documentation/stable/reference/classes/digraph.html
+.. _elements: https://wiki.openstreetmap.org/wiki/Elements
+.. _Elevation API: https://developers.google.com/maps/documentation/elevation
+.. _Examples Gallery: https://github.com/gboeing/osmnx-examples
+.. _features: https://wiki.openstreetmap.org/wiki/Map_features
+.. _Folium: https://python-visualization.github.io/folium/
+.. _GeoDataFrames: https://geopandas.org/en/stable/docs/reference/geodataframe.html
+.. _GeoPandas: https://geopandas.org
+.. _MultiDiGraph: https://networkx.org/documentation/stable/reference/classes/multidigraph.html
+.. _MultiDiGraphs: https://networkx.org/documentation/stable/reference/classes/multidigraph.html
+.. _MultiGraph: https://networkx.org/documentation/stable/reference/classes/multigraph.html
+.. _NetworkX: https://networkx.org
+.. _Nominatim: https://nominatim.org
+.. _Nominatim Usage Policy: https://operations.osmfoundation.org/policies/nominatim/
+.. _OpenStreetMap: https://www.openstreetmap.org
+.. _Overpass: https://wiki.openstreetmap.org/wiki/Overpass_API
+.. _Overpass Commons: https://dev.overpass-api.de/overpass-doc/en/preface/commons.html
+.. _Overpass QL: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL
+.. _projects: https://geoffboeing.com/2018/03/osmnx-features-roundup
+.. _StackOverflow: https://stackoverflow.com/search?q=osmnx
+.. _tags: https://wiki.openstreetmap.org/wiki/Tags

osmnx/source/docs/source/index.rst

@@ -0,0 +1,84 @@
+OSMnx |version|
+===============
+
+**OSMnx** is a Python package to easily download, model, analyze, and visualize street networks and other geospatial features from OpenStreetMap. You can download and model walking, driving, or biking networks with a single line of code then analyze and visualize them. You can just as easily work with urban amenities/points of interest, building footprints, transit stops, elevation data, street orientations, speed/travel time, and routing.
+
+.. _migration guide: https://github.com/gboeing/osmnx/issues/1123
+
+Citation
+--------
+
+If you use OSMnx in your work, please cite the paper:
+
+Boeing, G. (2025). `Modeling and Analyzing Urban Networks and Amenities with OSMnx`_. *Geographical Analysis* 57 (4), 567-577. doi:10.1111/gean.70009
+
+.. _Modeling and Analyzing Urban Networks and Amenities with OSMnx: https://doi.org/10.1111/gean.70009
+
+
+Getting Started
+---------------
+
+First read the :doc:`getting-started` guide for an introduction to the package and FAQ.
+
+Then work through the `Examples Gallery`_ for step-by-step tutorials and sample code.
+
+.. _Examples Gallery: https://github.com/gboeing/osmnx-examples
+
+
+Installation
+------------
+
+Follow the :doc:`installation` guide to install OSMnx.
+
+
+Support
+-------
+If you have any trouble, consult the :doc:`user-reference`. The OSMnx repository is hosted on `GitHub`_. If you have a "how-to" or usage question, please ask it on `StackOverflow`_, as we reserve the repository's issue tracker for bug tracking and feature development.
+
+.. _GitHub: https://github.com/gboeing/osmnx
+.. _StackOverflow: https://stackoverflow.com/search?q=osmnx
+
+
+License
+-------
+
+OSMnx is open source and licensed under the MIT license. OpenStreetMap's open data `license`_ requires that derivative works provide proper attribution. Refer to the :doc:`getting-started` guide for usage limitations.
+
+.. _license: https://www.openstreetmap.org/copyright
+
+
+User Guides
+-----------
+
+.. toctree::
+   :maxdepth: 1
+
+   installation
+
+.. toctree::
+   :maxdepth: 1
+
+   getting-started
+
+.. toctree::
+   :maxdepth: 1
+
+   user-reference
+
+.. toctree::
+   :maxdepth: 1
+
+   internals-reference
+
+.. toctree::
+   :maxdepth: 1
+
+   further-reading
+
+
+Indices
+-------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

osmnx/source/docs/source/installation.rst

@@ -0,0 +1,37 @@
+Installation
+============
+
+Conda
+-----
+
+The foolproof way to install OSMnx is with `conda`_ or `mamba`_:
+
+.. code-block:: shell
+
+    conda create --strict-channel-priority -c conda-forge -n ox osmnx
+
+This creates a new conda environment and installs OSMnx into it, via the conda-forge channel. If you want other packages, such as :code:`jupyterlab`, installed in this environment as well, just add their names after :code:`osmnx` above. To upgrade OSMnx to a newer release, remove the conda environment you created and then create a new one again, as above. See the `conda-forge`_ documentation for details.
+
+Docker
+------
+
+You can run OSMnx + JupyterLab directly from the official OSMnx `Docker`_ image.
+
+Pip
+---
+
+You can also install OSMnx with `uv`_ or `pip`_ (into a virtual environment):
+
+.. code-block:: shell
+
+    pip install osmnx
+
+OSMnx is written in pure Python and distributed on `PyPI`_. Its installation alone is thus trivially simple if you have its dependencies installed and tested on your system. However, OSMnx depends on other packages that in turn depend on compiled C/C++ libraries, which may present some challenges depending on your specific system's configuration. If precompiled binaries are not available for your system, you may need to compile and configure those dependencies by following their installation instructions. So, if you're not sure what you're doing, just follow the conda instructions above to avoid installation problems.
+
+.. _conda: https://conda.io/
+.. _conda-forge: https://conda-forge.org/
+.. _Docker: https://hub.docker.com/r/gboeing/osmnx
+.. _mamba: https://mamba.readthedocs.io/
+.. _pip: https://pip.pypa.io/
+.. _PyPI: https://pypi.org/project/osmnx/
+.. _uv: https://docs.astral.sh/uv/

osmnx/source/docs/source/internals-reference.rst

@@ -0,0 +1,196 @@
+Internals Reference
+===================
+
+This is the complete OSMnx internals reference for developers, including private internal modules and functions. If you are instead looking for a user guide to OSMnx's public API, see the :doc:`user-reference`.
+
+osmnx._api_v1 module
+--------------------
+
+.. automodule:: osmnx._api_v1
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.bearing module
+--------------------
+
+.. automodule:: osmnx.bearing
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.convert module
+---------------------
+
+.. automodule:: osmnx.convert
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.distance module
+---------------------
+
+.. automodule:: osmnx.distance
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.elevation module
+----------------------
+
+.. automodule:: osmnx.elevation
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx._errors module
+--------------------
+
+.. automodule:: osmnx._errors
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.features module
+---------------------
+
+.. automodule:: osmnx.features
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.geocoder module
+---------------------
+
+.. automodule:: osmnx.geocoder
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.graph module
+------------------
+
+.. automodule:: osmnx.graph
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx._http module
+------------------
+
+.. automodule:: osmnx._http
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.io module
+---------------
+
+.. automodule:: osmnx.io
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx._nominatim module
+-----------------------
+
+.. automodule:: osmnx._nominatim
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx._osm_xml module
+---------------------
+
+.. automodule:: osmnx._osm_xml
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx._overpass module
+----------------------
+
+.. automodule:: osmnx._overpass
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.plot module
+-----------------
+
+.. automodule:: osmnx.plot
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.projection module
+-----------------------
+
+.. automodule:: osmnx.projection
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.routing module
+-----------------------
+
+.. automodule:: osmnx.routing
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.settings module
+---------------------
+
+.. automodule:: osmnx.settings
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.simplification module
+---------------------------
+
+.. automodule:: osmnx.simplification
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.stats module
+------------------
+
+.. automodule:: osmnx.stats
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.truncate module
+---------------------
+
+.. automodule:: osmnx.truncate
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.utils module
+------------------
+
+.. automodule:: osmnx.utils
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx.utils_geo module
+----------------------
+
+.. automodule:: osmnx.utils_geo
+    :members:
+    :private-members:
+    :noindex:
+
+osmnx._validate module
+----------------------
+
+.. automodule:: osmnx._validate
+    :members:
+    :private-members:
+    :noindex:

osmnx/source/docs/source/user-reference.rst

@@ -0,0 +1,142 @@
+User Reference
+==============
+
+This is the User Reference for the OSMnx package. If you are looking for an introduction to OSMnx, read the :doc:`getting-started` guide. This guide describes the usage of OSMnx's public API.
+
+.. _migration guide: https://github.com/gboeing/osmnx/issues/1123
+
+.. _osmnx-bearing-module:
+
+osmnx.bearing module
+--------------------
+
+.. automodule:: osmnx.bearing
+    :members:
+
+.. _osmnx-convert-module:
+
+osmnx.convert module
+--------------------
+
+.. automodule:: osmnx.convert
+    :members:
+
+.. _osmnx-distance-module:
+
+osmnx.distance module
+---------------------
+
+.. automodule:: osmnx.distance
+    :members:
+
+.. _osmnx-elevation-module:
+
+osmnx.elevation module
+----------------------
+
+.. automodule:: osmnx.elevation
+    :members:
+
+.. _osmnx-features-module:
+
+osmnx.features module
+---------------------
+
+.. automodule:: osmnx.features
+    :members:
+
+.. _osmnx-geocoder-module:
+
+osmnx.geocoder module
+---------------------
+
+.. automodule:: osmnx.geocoder
+    :members:
+
+.. _osmnx-graph-module:
+
+osmnx.graph module
+------------------
+
+.. automodule:: osmnx.graph
+    :members:
+
+.. _osmnx-io-module:
+
+osmnx.io module
+---------------
+
+.. automodule:: osmnx.io
+    :members:
+
+.. _osmnx-plot-module:
+
+osmnx.plot module
+-----------------
+
+.. automodule:: osmnx.plot
+    :members:
+
+.. _osmnx-projection-module:
+
+osmnx.projection module
+-----------------------
+
+.. automodule:: osmnx.projection
+    :members:
+
+.. _osmnx-routing-module:
+
+osmnx.routing module
+-----------------------
+
+.. automodule:: osmnx.routing
+    :members:
+
+.. _osmnx-settings-module:
+
+osmnx.settings module
+---------------------
+
+.. automodule:: osmnx.settings
+    :members:
+
+.. _osmnx-simplification-module:
+
+osmnx.simplification module
+---------------------------
+
+.. automodule:: osmnx.simplification
+    :members:
+
+.. _osmnx-stats-module:
+
+osmnx.stats module
+------------------
+
+.. automodule:: osmnx.stats
+    :members:
+
+.. _osmnx-truncate-module:
+
+osmnx.truncate module
+---------------------
+
+.. automodule:: osmnx.truncate
+    :members:
+
+.. _osmnx-utils-module:
+
+osmnx.utils module
+------------------
+
+.. automodule:: osmnx.utils
+    :members:
+
+.. _osmnx-utils_geo-module:
+
+osmnx.utils_geo module
+----------------------
+
+.. automodule:: osmnx.utils_geo
+    :members:

osmnx/source/environments/create_conda_env.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+set -euo pipefail
+echo "Run conda deactivate before running this script."
+ENV=ox
+ENV_PATH=$(conda info --base)/envs/$ENV
+PACKAGE=osmnx
+uv --version
+eval "$(conda shell.bash hook)"
+conda deactivate
+conda env remove --yes -n $ENV || true
+conda create --yes -c conda-forge --strict-channel-priority -n $ENV python
+eval "$(conda shell.bash hook)"
+conda activate $ENV
+uv export --no-build --all-extras --all-groups > ./environments/requirements-temp.txt
+uv pip install --no-build --strict -r ./environments/requirements-temp.txt
+rm -f ./environments/requirements-temp.txt
+python -m pip --python "$ENV_PATH" uninstall $PACKAGE --yes
+python -m pip --python "$ENV_PATH" install -e .
+python -m ipykernel install --prefix "$ENV_PATH" --name $ENV --display-name "Python ($ENV)"
+conda list -n $ENV
+python -m pip --python "$ENV_PATH" check
+jupyter kernelspec list
+ipython -c "import $PACKAGE; print('$PACKAGE version', $PACKAGE.__version__)"

osmnx/source/environments/docker/Dockerfile

@@ -0,0 +1,24 @@
+FROM jupyter/base-notebook
+LABEL maintainer="Geoff Boeing <boeing@usc.edu>"
+LABEL url="https://osmnx.readthedocs.io"
+LABEL description="OSMnx is a Python package to easily download, model, analyze, and visualize street networks and other geospatial features from OpenStreetMap."
+
+# expose $TARGETPLATFORM to the install.sh script
+ARG TARGETPLATFORM
+
+# copy uv binaries and package files needed for installation
+COPY --from=ghcr.io/astral-sh/uv:0.9 /uv /uvx /bin/
+COPY --chown=jovyan --chmod=0755 ./environments/docker/install.sh ./osmnx/
+COPY --chown=jovyan --chmod=0755 ./osmnx/ ./osmnx/osmnx/
+COPY --chown=jovyan --chmod=0755 ./LICENSE.txt ./osmnx/
+COPY --chown=jovyan --chmod=0755 ./pyproject.toml ./osmnx/
+COPY --chown=jovyan --chmod=0755 ./README.md ./osmnx/
+
+# install and configure everything in one RUN to keep image tidy
+RUN cd ./osmnx && bash install.sh
+
+# set jupyter working directory to map to mounted volume
+WORKDIR /home/jovyan/work
+
+# set default command to launch when container is run
+CMD ["jupyter", "lab", "--ip='0.0.0.0'", "--port=8888", "--no-browser", "--NotebookApp.token=''", "--NotebookApp.password=''"]

osmnx/source/environments/docker/build_image.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+echo "Run this script from the repository root."
+docker login
+docker buildx build --progress=plain --no-cache --pull --push --platform=linux/amd64,linux/arm64 -f ./environments/docker/Dockerfile -t gboeing/osmnx:test .
+IMPORTED_VERSION=$(docker run --rm gboeing/osmnx:test /bin/bash -c "ipython -c \"import osmnx; print(osmnx.__version__)\"")
+echo "Imported $IMPORTED_VERSION"

osmnx/source/environments/docker/install.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+set -euo pipefail
+
+# rasterio doesn't provide linux/arm64 wheels, so if the target platform is
+# linux/arm64, don't install this optional dependency (attempting to build
+# it rather than install the wheel will also fail).
+# see https://github.com/rasterio/rasterio-wheels/issues/69
+if [[ "$TARGETPLATFORM" == "linux/arm64" ]]
+then
+  NOEXTRA="--no-extra=raster --no-extra=all"
+else
+  NOEXTRA=""
+fi
+
+# install all requirements into the existing system environment
+uv export --no-cache --no-build --all-extras $NOEXTRA --group examples > requirements-temp.txt
+uv pip install --no-cache --no-build --system --compile-bytecode --strict -r requirements-temp.txt
+rm -f requirements-temp.txt
+uv cache clean
+python --version
+ipython -c "import osmnx; print('OSMnx version', osmnx.__version__)"

osmnx/source/osmnx/__init__.py

@@ -0,0 +1,37 @@
+# ruff: noqa: D205  # numpydoc ignore=SS06
+"""
+OSMnx is a Python package to easily download, model, analyze, and visualize
+street networks and other geospatial features from OpenStreetMap.
+
+Full documentation at: https://osmnx.readthedocs.io
+
+If you use OSMnx in your work, please cite: https://doi.org/10.1111/gean.70009
+"""
+
+from importlib.metadata import version as metadata_version
+
+# expose the package version
+__version__ = metadata_version("osmnx")
+
+# expose the package's public modules
+from . import _errors as _errors
+from . import bearing as bearing
+from . import convert as convert
+from . import distance as distance
+from . import elevation as elevation
+from . import features as features
+from . import geocoder as geocoder
+from . import graph as graph
+from . import io as io
+from . import plot as plot
+from . import projection as projection
+from . import routing as routing
+from . import settings as settings
+from . import simplification as simplification
+from . import stats as stats
+from . import truncate as truncate
+from . import utils as utils
+from . import utils_geo as utils_geo
+
+# expose the old v1 API for backwards compatibility
+from ._api_v1 import *  # noqa: F403

osmnx/source/osmnx/_api_v1.py

@@ -0,0 +1,53 @@
+# ruff: noqa: PLC0414
+"""
+Expose the old v1 API for backwards compatibility.
+
+This allows common functionality to be accessed directly via the
+ox.function_name() shortcut by exposing these functions directly in the
+package's namespace.
+"""
+
+from .bearing import add_edge_bearings as add_edge_bearings
+from .bearing import orientation_entropy as orientation_entropy
+from .convert import graph_from_gdfs as graph_from_gdfs
+from .convert import graph_to_gdfs as graph_to_gdfs
+from .distance import nearest_edges as nearest_edges
+from .distance import nearest_nodes as nearest_nodes
+from .elevation import add_edge_grades as add_edge_grades
+from .elevation import add_node_elevations_google as add_node_elevations_google
+from .elevation import add_node_elevations_raster as add_node_elevations_raster
+from .features import features_from_address as features_from_address
+from .features import features_from_bbox as features_from_bbox
+from .features import features_from_place as features_from_place
+from .features import features_from_point as features_from_point
+from .features import features_from_polygon as features_from_polygon
+from .features import features_from_xml as features_from_xml
+from .geocoder import geocode as geocode
+from .geocoder import geocode_to_gdf as geocode_to_gdf
+from .graph import graph_from_address as graph_from_address
+from .graph import graph_from_bbox as graph_from_bbox
+from .graph import graph_from_place as graph_from_place
+from .graph import graph_from_point as graph_from_point
+from .graph import graph_from_polygon as graph_from_polygon
+from .graph import graph_from_xml as graph_from_xml
+from .io import load_graphml as load_graphml
+from .io import save_graph_geopackage as save_graph_geopackage
+from .io import save_graph_xml as save_graph_xml
+from .io import save_graphml as save_graphml
+from .plot import plot_figure_ground as plot_figure_ground
+from .plot import plot_footprints as plot_footprints
+from .plot import plot_graph as plot_graph
+from .plot import plot_graph_route as plot_graph_route
+from .plot import plot_graph_routes as plot_graph_routes
+from .plot import plot_orientation as plot_orientation
+from .projection import project_graph as project_graph
+from .routing import add_edge_speeds as add_edge_speeds
+from .routing import add_edge_travel_times as add_edge_travel_times
+from .routing import k_shortest_paths as k_shortest_paths
+from .routing import shortest_path as shortest_path
+from .simplification import consolidate_intersections as consolidate_intersections
+from .simplification import simplify_graph as simplify_graph
+from .stats import basic_stats as basic_stats
+from .utils import citation as citation
+from .utils import log as log
+from .utils import ts as ts

osmnx/source/osmnx/_errors.py

@@ -0,0 +1,21 @@
+"""Define custom errors and exceptions."""
+
+
+class CacheOnlyInterruptError(InterruptedError):
+    """Exception for `settings.cache_only_mode=True` interruption."""
+
+
+class GraphSimplificationError(ValueError):
+    """Exception for a problem with graph simplification."""
+
+
+class ValidationError(ValueError):
+    """Exception for failed graph or node/edge GeoDataFrame validation."""
+
+
+class InsufficientResponseError(ValueError):
+    """Exception for empty or too few results in server response."""
+
+
+class ResponseStatusCodeError(ValueError):
+    """Exception for an unhandled server response status code."""

osmnx/source/osmnx/_http.py

@@ -0,0 +1,332 @@
+"""Handle HTTP requests to web APIs."""
+
+from __future__ import annotations
+
+import json
+import logging as lg
+import socket
+from hashlib import sha1
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+import requests
+from requests.exceptions import JSONDecodeError
+
+from . import settings
+from . import utils
+from ._errors import InsufficientResponseError
+from ._errors import ResponseStatusCodeError
+
+# capture getaddrinfo function to use original later after mutating it
+_original_getaddrinfo = socket.getaddrinfo
+
+
+def _save_to_cache(
+    url: str,
+    response_json: dict[str, Any] | list[dict[str, Any]],
+    ok: bool,  # noqa: FBT001
+) -> None:
+    """
+    Save a HTTP response JSON object to a file in the cache folder.
+
+    If request was sent to server via POST instead of GET, then `url` should
+    be a GET-style representation of the request. Response is only saved to a
+    cache file if `settings.use_cache` is True, `ok` is True, `response_json`
+    is not None, and `response_json` does not contain a server "remark."
+
+    Users should always pass OrderedDicts instead of dicts of parameters into
+    request functions, so the parameters remain in the same order each time,
+    producing the same URL string, and thus the same hash. Otherwise you will
+    get a cache miss when the URL's parameters appeared in a different order.
+
+    Parameters
+    ----------
+    url
+        The URL of the request.
+    response_json
+        The JSON HTTP response.
+    ok
+        A `requests.response.ok` value.
+    """
+    if settings.use_cache:
+        if not ok:  # pragma: no cover
+            msg = "Did not save to cache because HTTP status code is not OK"
+            utils.log(msg, level=lg.WARNING)
+        elif isinstance(response_json, dict) and ("remark" in response_json):  # pragma: no cover
+            msg = f"Did not save to cache because response contains remark: {response_json['remark']!r}"
+            utils.log(msg, lg.WARNING)
+        else:
+            # create cache folder on disk if it doesn't already exist
+            cache_filepath = _resolve_cache_filepath(url)
+            cache_filepath.parent.mkdir(parents=True, exist_ok=True)
+            cache_filepath.write_text(json.dumps(response_json), encoding="utf-8")
+            msg = f"Saved response to cache file {str(cache_filepath)!r}"
+            utils.log(msg, level=lg.INFO)
+
+
+def _resolve_cache_filepath(key: str, extension: str = "json") -> Path:
+    """
+    Determine a cache key's corresponding cache file path.
+
+    This uses the configured `settings.cache_folder` and calculates the 160
+    bit SHA-1 hash digest (40 hexadecimal characters) of `key` to determine a
+    succinct but unique cache filename.
+
+    Parameters
+    ----------
+    key
+        The key for which to generate a cache file path, for example, a URL.
+    extension
+        The desired cache file's extension.
+
+    Returns
+    -------
+    cache_filepath
+        Cache file path corresponding to `key`.
+    """
+    digest = sha1(key.encode("utf-8")).hexdigest()  # noqa: S324
+    return Path(settings.cache_folder) / f"{digest}.{extension}"
+
+
+def _check_cache(key: str) -> Path | None:
+    """
+    Check if a key exists in the cache, and return its cache file path if so.
+
+    Parameters
+    ----------
+    key
+        The key to look for in the cache.
+
+    Returns
+    -------
+    cache_filepath
+        Filepath to cached data for `key` if it exists, otherwise None.
+    """
+    cache_filepath = _resolve_cache_filepath(key)
+    return cache_filepath if cache_filepath.is_file() else None
+
+
+def _retrieve_from_cache(url: str) -> dict[str, Any] | list[dict[str, Any]] | None:
+    """
+    Retrieve a HTTP response JSON object from the cache if it exists.
+
+    A cache hit returns the data. A cache miss returns None.
+
+    Parameters
+    ----------
+    url
+        The URL of the request.
+
+    Returns
+    -------
+    response_json
+        The cached response for `url` if it exists, otherwise None.
+    """
+    # if the tool is configured to use the cache
+    if settings.use_cache:
+        # return cached response for this url if exists, otherwise return None
+        cache_filepath = _check_cache(url)
+        if cache_filepath is not None:
+            response_json: dict[str, Any] | list[dict[str, Any]]
+            response_json = json.loads(cache_filepath.read_text(encoding="utf-8"))
+            msg = f"Retrieved response from cache file {str(cache_filepath)!r}"
+            utils.log(msg, lg.INFO)
+            return response_json
+
+    return None
+
+
+def _get_http_headers(
+    *,
+    user_agent: str | None = None,
+    referer: str | None = None,
+    accept_language: str | None = None,
+) -> dict[str, str]:
+    """
+    Update the default requests HTTP headers with OSMnx information.
+
+    Parameters
+    ----------
+    user_agent
+        The user agent. If None, use `settings.http_user_agent` value.
+    referer
+        The referer. If None, use `settings.http_referer` value.
+    accept_language
+        The accept language. If None, use `settings.http_accept_language`
+        value.
+
+    Returns
+    -------
+    headers
+        The updated HTTP headers.
+    """
+    if user_agent is None:
+        user_agent = settings.http_user_agent
+    if referer is None:
+        referer = settings.http_referer
+    if accept_language is None:
+        accept_language = settings.http_accept_language
+
+    info = {"User-Agent": user_agent, "referer": referer, "Accept-Language": accept_language}
+    headers = dict(requests.utils.default_headers())
+    headers.update(info)
+    return headers
+
+
+def _resolve_host_via_doh(hostname: str) -> str:
+    """
+    Resolve hostname to IP address via Google's public DNS-over-HTTPS API.
+
+    Necessary fallback as socket.gethostbyname will not always work when using
+    a proxy. See https://developers.google.com/speed/public-dns/docs/doh/json
+    If the user has set `settings.doh_url_template=None` or if resolution
+    fails (e.g., due to local network blocking DNS-over-HTTPS) the hostname
+    itself will be returned instead. Note that this means that server slot
+    management may be violated: see `_config_dns` documentation for details.
+
+    Parameters
+    ----------
+    hostname
+        The hostname to consistently resolve the IP address of.
+
+    Returns
+    -------
+    ip_address
+        Resolved IP address of host, or hostname itself if resolution failed.
+    """
+    if settings.doh_url_template is None:
+        # if user has set the url template to None, return hostname itself
+        msg = "User set `doh_url_template=None`, requesting host by name"
+        utils.log(msg, level=lg.WARNING)
+        return hostname
+
+    err_msg = f"Failed to resolve {hostname!r} IP via DoH, requesting host by name"
+    try:
+        url = settings.doh_url_template.format(hostname=hostname)
+        response = requests.get(url, timeout=settings.requests_timeout)
+        data = response.json()
+
+    # if we cannot reach DoH server or resolve host, return hostname itself
+    except requests.exceptions.RequestException:  # pragma: no cover
+        utils.log(err_msg, level=lg.ERROR)
+        return hostname
+
+    # if there were no request exceptions, return
+    else:
+        if response.ok and data["Status"] == 0:
+            # status 0 means NOERROR, so return the IP address
+            ip_address: str = data["Answer"][0]["data"]
+            return ip_address
+
+        # otherwise, if we cannot reach DoH server or cannot resolve host
+        # just return the hostname itself
+        utils.log(err_msg, level=lg.ERROR)
+        return hostname
+
+
+def _config_dns(url: str) -> None:
+    """
+    Force socket.getaddrinfo to use IP address instead of hostname.
+
+    Resolves URL's hostname to an IP address so that we use the same server
+    for both 1) checking the necessary pause duration and 2) sending the query
+    itself even if there is round-robin redirecting among multiple server
+    machines on the server-side. Mutates the getaddrinfo function so it uses
+    the same IP address everytime it finds the hostname in the URL.
+
+    For example, the server overpass-api.de just redirects to one of the other
+    servers (currently gall.openstreetmap.de and lambert.openstreetmap.de). So
+    if we check the status endpoint of overpass-api.de, we may see results for
+    server gall, but when we submit the query itself it gets redirected to
+    server lambert. This could result in violating server lambert's slot
+    management timing.
+
+    Parameters
+    ----------
+    url
+        The URL to consistently resolve the IP address of.
+    """
+    hostname = _hostname_from_url(url)
+    try:
+        ip = socket.gethostbyname(hostname)
+    except socket.gaierror:  # pragma: no cover
+        # may occur when using a proxy, so instead resolve IP address via DoH
+        msg = f"Encountered gaierror while trying to resolve {hostname!r}, trying again via DoH..."
+        utils.log(msg, level=lg.ERROR)
+        ip = _resolve_host_via_doh(hostname)
+
+    # mutate socket.getaddrinfo to map hostname -> IP address
+    def _getaddrinfo(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
+        if hostname == next(iter(args), kwargs.get("host")):
+            # remove "host" from kwargs to avoid TypeError with positional argument
+            kwargs.pop("host", None)
+            msg = f"Resolved {hostname!r} to {ip!r}"
+            utils.log(msg, level=lg.INFO)
+            return _original_getaddrinfo(ip, *args[1:], **kwargs)
+
+        # otherwise
+        return _original_getaddrinfo(*args, **kwargs)
+
+    socket.getaddrinfo = _getaddrinfo
+
+
+def _hostname_from_url(url: str) -> str:
+    """
+    Extract the hostname (domain) from a URL.
+
+    Parameters
+    ----------
+    url
+        The url from which to extract the hostname.
+
+    Returns
+    -------
+    hostname
+        The extracted hostname (domain).
+    """
+    return urlparse(url).netloc.split(":")[0]
+
+
+def _parse_response(response: requests.Response) -> dict[str, Any] | list[dict[str, Any]]:
+    """
+    Parse JSON from a requests response and log the details.
+
+    Parameters
+    ----------
+    response
+        The response object.
+
+    Returns
+    -------
+    response_json
+        Value will be a dict if the response is from the Google or Overpass
+        APIs, and a list if the response is from the Nominatim API.
+    """
+    # log the response size and hostname
+    hostname = _hostname_from_url(response.url)
+    size_kb = len(response.content) / 1000
+    msg = f"Downloaded {size_kb:,.1f}kB from {hostname!r} with status {response.status_code}"
+    utils.log(msg, level=lg.INFO)
+
+    # parse the response to JSON and log/raise exceptions
+    try:
+        response_json: dict[str, Any] | list[dict[str, Any]] = response.json()
+    except JSONDecodeError as e:  # pragma: no cover
+        msg = f"{hostname!r} responded: {response.status_code} {response.reason} {response.text}"
+        utils.log(msg, level=lg.ERROR)
+        if response.ok:
+            raise InsufficientResponseError(msg) from e
+        raise ResponseStatusCodeError(msg) from e
+
+    # log any remarks if they exist
+    if isinstance(response_json, dict) and "remark" in response_json:  # pragma: no cover
+        msg = f"{hostname!r} remarked: {response_json['remark']!r}"
+        utils.log(msg, level=lg.WARNING)
+
+    # log if the response status_code is not OK
+    if not response.ok:
+        msg = f"{hostname!r} returned HTTP status code {response.status_code}"
+        utils.log(msg, level=lg.WARNING)
+
+    return response_json

osmnx/source/osmnx/_nominatim.py

@@ -0,0 +1,151 @@
+"""Tools to work with the Nominatim API."""
+
+from __future__ import annotations
+
+import logging as lg
+import time
+from collections import OrderedDict
+from typing import Any
+
+import requests
+
+from . import _http
+from . import settings
+from . import utils
+from ._errors import InsufficientResponseError
+
+
+def _download_nominatim_element(
+    query: str | dict[str, str],
+    *,
+    by_osmid: bool = False,
+    limit: int = 1,
+    polygon_geojson: bool = True,
+) -> list[dict[str, Any]]:
+    """
+    Retrieve an OSM element from the Nominatim API.
+
+    Parameters
+    ----------
+    query
+        Query string or structured query dict.
+    by_osmid
+        If True, treat `query` as an OSM ID lookup rather than text search.
+    limit
+        Max number of results to return.
+    polygon_geojson
+        Whether to retrieve the place's geometry from the API.
+
+    Returns
+    -------
+    response_json
+        The Nominatim API's response.
+    """
+    # define the parameters
+    params: OrderedDict[str, int | str] = OrderedDict()
+    params["format"] = "json"
+    params["polygon_geojson"] = int(polygon_geojson)  # bool -> int
+
+    if by_osmid:
+        # if querying by OSM ID, use the lookup endpoint
+        if not isinstance(query, str):
+            msg = "`query` must be a string if `by_osmid` is True."
+            raise TypeError(msg)
+        request_type = "lookup"
+        params["osm_ids"] = query
+
+    else:
+        # if not querying by OSM ID, use the search endpoint
+        request_type = "search"
+
+        # prevent OSM from deduping so we get precise number of results
+        params["dedupe"] = 0
+        params["limit"] = limit
+
+        if isinstance(query, str):
+            params["q"] = query
+        elif isinstance(query, dict):
+            # add query keys in alphabetical order so URL is the same string
+            # each time, for caching purposes
+            for key in sorted(query):
+                params[key] = query[key]
+        else:  # pragma: no cover
+            msg = "Each query must be a dict or a string."  # type: ignore[unreachable]
+            raise TypeError(msg)
+
+    # request the URL, return the JSON
+    return _nominatim_request(params=params, request_type=request_type)
+
+
+def _nominatim_request(
+    params: OrderedDict[str, int | str],
+    *,
+    request_type: str = "search",
+) -> list[dict[str, Any]]:
+    """
+    Send a HTTP GET request to the Nominatim API and return response.
+
+    Parameters
+    ----------
+    params
+        Key-value pairs of parameters.
+    request_type
+        Which Nominatim API endpoint to query, one of {"search", "reverse",
+        "lookup"}.
+
+    Returns
+    -------
+    response_json
+        The Nominatim API's response.
+    """
+    if request_type not in {"search", "reverse", "lookup"}:  # pragma: no cover
+        msg = "Nominatim `request_type` must be 'search', 'reverse', or 'lookup'."
+        raise ValueError(msg)
+
+    # add nominatim API key to params if one has been provided in settings
+    if settings.nominatim_key is not None:
+        params["key"] = settings.nominatim_key
+
+    # prepare Nominatim API URL and see if request already exists in cache
+    url = settings.nominatim_url.rstrip("/") + "/" + request_type
+    prepared_url = str(requests.Request("GET", url, params=params).prepare().url)
+    cached_response_json = _http._retrieve_from_cache(prepared_url)
+    if isinstance(cached_response_json, list):
+        return cached_response_json
+
+    # how long to pause before request, in seconds. Per the Nominatim usage
+    # policy: "an absolute maximum of 1 request per second" is allowed.
+    pause = 1
+    hostname = _http._hostname_from_url(url)
+    msg = f"Pausing {pause} second(s) before making HTTP GET request to {hostname!r}"
+    utils.log(msg, level=lg.INFO)
+    time.sleep(pause)
+
+    # transmit the HTTP GET request
+    msg = f"Get {prepared_url} with timeout={settings.requests_timeout}"
+    utils.log(msg, level=lg.INFO)
+    response = requests.get(
+        url,
+        params=params,
+        timeout=settings.requests_timeout,
+        headers=_http._get_http_headers(),
+        **settings.requests_kwargs,
+    )
+
+    # handle 429 and 504 errors by pausing then recursively re-trying request
+    if response.status_code in {429, 504}:  # pragma: no cover
+        error_pause = 55
+        msg = (
+            f"{hostname!r} responded {response.status_code} {response.reason}: "
+            f"we'll retry in {error_pause} secs"
+        )
+        utils.log(msg, level=lg.WARNING)
+        time.sleep(error_pause)
+        return _nominatim_request(params, request_type=request_type)
+
+    response_json = _http._parse_response(response)
+    if not isinstance(response_json, list):
+        msg = "Nominatim API did not return a list of results."
+        raise InsufficientResponseError(msg)
+    _http._save_to_cache(prepared_url, response_json, response.ok)
+    return response_json

osmnx/source/osmnx/_osm_xml.py

@@ -0,0 +1,439 @@
+"""
+Read/write OSM XML files.
+
+For file format information see https://wiki.openstreetmap.org/wiki/OSM_XML
+"""
+
+from __future__ import annotations
+
+import bz2
+import gzip
+import logging as lg
+from contextlib import contextmanager
+from importlib.metadata import version as metadata_version
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import TextIO
+from warnings import warn
+from xml.etree.ElementTree import Element
+from xml.etree.ElementTree import ElementTree
+from xml.etree.ElementTree import SubElement
+from xml.etree.ElementTree import parse as etree_parse
+from xml.sax import parse as sax_parse
+from xml.sax.handler import ContentHandler
+
+import networkx as nx
+import pandas as pd
+
+from . import convert
+from . import projection
+from . import settings
+from . import truncate
+from . import utils
+from ._errors import GraphSimplificationError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from xml.sax.xmlreader import AttributesImpl
+
+    import geopandas as gpd
+
+
+# default values for standard "node" and "way" XML subelement attributes
+# see: https://wiki.openstreetmap.org/wiki/Elements#Common_attributes
+ATTR_DEFAULTS = {
+    "changeset": "1",
+    "timestamp": utils.ts(style="iso8601"),
+    "uid": "1",
+    "user": "OSMnx",
+    "version": "1",
+    "visible": "true",
+}
+
+# default values for standard "osm" root XML element attributes
+# current OSM editing API version: https://wiki.openstreetmap.org/wiki/API
+ROOT_ATTR_DEFAULTS = {
+    "attribution": "https://www.openstreetmap.org/copyright",
+    "copyright": "OpenStreetMap and contributors",
+    "generator": f"OSMnx {metadata_version('osmnx')}",
+    "license": "https://opendatacommons.org/licenses/odbl/1-0/",
+    "version": "0.6",
+}
+
+
+class _OSMContentHandler(ContentHandler):
+    """
+    SAX content handler for OSM XML.
+
+    Builds an Overpass-like response JSON object in self.object. For format
+    notes, see https://wiki.openstreetmap.org/wiki/OSM_XML and
+    https://overpass-api.de
+    """
+
+    def __init__(self) -> None:
+        self._element: dict[str, Any] | None = None
+        self.object: dict[str, Any] = {"elements": []}
+
+    def startElement(self, name: str, attrs: AttributesImpl) -> None:  # noqa: N802
+        # identify node/way/relation attrs to convert from string to numeric
+        float_attrs = {"lat", "lon"}
+        int_attrs = {"changeset", "id", "uid", "version"}
+
+        if name == "osm":
+            self.object.update({k: v for k, v in attrs.items() if k in ROOT_ATTR_DEFAULTS})
+
+        elif name in {"node", "way"}:
+            self._element = dict(type=name, tags={}, **attrs)
+            if name == "way":
+                self._element["nodes"] = []
+            self._element.update({k: float(v) for k, v in attrs.items() if k in float_attrs})
+            self._element.update({k: int(v) for k, v in attrs.items() if k in int_attrs})
+
+        elif name == "relation":
+            self._element = dict(type=name, tags={}, members=[], **attrs)
+            self._element.update({k: int(v) for k, v in attrs.items() if k in int_attrs})
+
+        elif name == "tag":
+            self._element["tags"].update({attrs["k"]: attrs["v"]})  # type: ignore[index]
+
+        elif name == "nd":
+            self._element["nodes"].append(int(attrs["ref"]))  # type: ignore[index]
+
+        elif name == "member":
+            self._element["members"].append(  # type: ignore[index]
+                {k: (int(v) if k == "ref" else v) for k, v in attrs.items()},
+            )
+
+    def endElement(self, name: str) -> None:  # noqa: N802
+        if name in {"node", "way", "relation"}:
+            self.object["elements"].append(self._element)
+
+
+@contextmanager
+def _open_file(filepath: Path, encoding: str) -> Iterator[TextIO]:
+    """
+    Open a file and return a file object, optionally handling bz2 or gz files.
+
+    Uses a wrapper context manager to yield the file object to ensure the file
+    will always get closed when the caller is finished with it.
+
+    Parameters
+    ----------
+    filepath
+        Path to file.
+    encoding
+        The file's character encoding.
+
+    Returns
+    -------
+    file
+        The file handle.
+    """
+    if filepath.suffix == ".bz2":
+        with bz2.open(filepath, mode="rt", encoding=encoding) as file:
+            yield file
+    elif filepath.suffix == ".gz":
+        with gzip.open(filepath, mode="rt", encoding=encoding) as file:
+            yield file
+    else:
+        with filepath.open(mode="rt", encoding=encoding) as file:
+            yield file
+
+
+def _overpass_json_from_xml(filepath: Path, encoding: str) -> dict[str, Any]:
+    """
+    Read OSM XML data from file and return Overpass-like JSON.
+
+    Parameters
+    ----------
+    filepath
+        Path to file containing OSM XML data.
+    encoding
+        The XML file's character encoding.
+
+    Returns
+    -------
+    response_json
+        A parsed JSON response from the Overpass API.
+    """
+    with _open_file(filepath, encoding) as file:
+        # warn if this XML file was generated by OSMnx itself
+        root_attrs = etree_parse(file).getroot().attrib  # noqa: S314
+        if "generator" in root_attrs and "OSMnx" in root_attrs["generator"]:
+            msg = (
+                "The XML file you are loading appears to have been generated "
+                "by OSMnx: this use case is not supported and may not behave "
+                "as expected. To save/load graphs to/from disk for later use "
+                "in OSMnx, use the `io.save_graphml` and `io.load_graphml` "
+                "functions instead. Refer to the documentation for details."
+            )
+            warn(msg, category=UserWarning, stacklevel=2)
+
+        # move back to beginning of file, then parse XML to Overpass-like JSON
+        file.seek(0)
+        handler = _OSMContentHandler()
+        sax_parse(file, handler)  # noqa: S317
+
+    return handler.object
+
+
+def _save_graph_xml(
+    G: nx.MultiDiGraph,
+    filepath: str | Path | None,
+    way_tag_aggs: dict[str, Any] | None,
+    encoding: str = "utf-8",
+) -> None:
+    """
+    Save graph to disk as an OSM XML file.
+
+    Parameters
+    ----------
+    G
+        Unsimplified, unprojected graph to save as an OSM XML file.
+    filepath
+        Path to the saved file including extension. If None, use default
+        `settings.data_folder/graph.osm`.
+    way_tag_aggs
+        Keys are OSM way tag keys and values are aggregation functions
+        (anything accepted as an argument by `pandas.agg`). Allows user to
+        aggregate graph edge attribute values into single OSM way values. If
+        None, or if some tag's key does not exist in the dict, the way
+        attribute will be assigned the value of the first edge of the way.
+    encoding
+        The character encoding of the saved OSM XML file.
+    """
+    # default "oneway" value used to fill this tag where missing
+    ONEWAY = False
+
+    # round lat/lon coordinates to 7 decimals (approx 5 to 10 mm resolution)
+    PRECISION = 7
+
+    # warn user if ox.settings.all_oneway is not currently True (but maybe it
+    # was when they created the graph)
+    if not settings.all_oneway:
+        msg = "Make sure graph was created with `ox.settings.all_oneway=True` to save as OSM XML."
+        warn(msg, category=UserWarning, stacklevel=2)
+
+    # warn user if graph is projected
+    if projection.is_projected(G.graph["crs"]):
+        msg = (
+            "Graph should be unprojected to save as OSM XML: the existing "
+            "projected x-y coordinates will be saved as lat-lon node attributes. "
+            "Project your graph back to lat-lon to avoid this."
+        )
+        warn(msg, category=UserWarning, stacklevel=2)
+
+    # raise error if graph has been simplified
+    if G.graph.get("simplified", False):
+        msg = "Graph must be unsimplified to save as OSM XML."
+        raise GraphSimplificationError(msg)
+
+    # set default filepath if None was provided
+    filepath = Path(settings.data_folder) / "graph.osm" if filepath is None else Path(filepath)
+    filepath.parent.mkdir(parents=True, exist_ok=True)
+
+    # convert graph to node/edge gdfs and create dict of spatial bounds
+    gdf_nodes, gdf_edges = convert.graph_to_gdfs(G, fill_edge_geometry=False)
+    coords = [str(round(c, PRECISION)) for c in gdf_nodes.union_all().bounds]
+    bounds = dict(zip(["minlon", "minlat", "maxlon", "maxlat"], coords, strict=True))
+
+    # add default values (if missing) for standard attrs
+    for gdf in (gdf_nodes, gdf_edges):
+        for col, value in ATTR_DEFAULTS.items():
+            if col not in gdf.columns:
+                gdf[col] = value
+            else:
+                gdf[col] = gdf[col].fillna(value)
+
+    # transform nodes gdf to meet OSM XML spec
+    # 1) reset index (osmid) then rename osmid, x, and y columns
+    # 2) round lat/lon coordinates
+    # 3) drop unnecessary geometry column
+    gdf_nodes = gdf_nodes.reset_index().rename(columns={"osmid": "id", "x": "lon", "y": "lat"})
+    gdf_nodes[["lon", "lat"]] = gdf_nodes[["lon", "lat"]].round(PRECISION)
+    gdf_nodes = gdf_nodes.drop(columns=["geometry"])
+
+    # transform edges gdf to meet OSM XML spec
+    # 1) fill and convert oneway bools to strings
+    # 2) rename osmid column (but keep (u, v, k) index for processing)
+    # 3) drop unnecessary geometry column
+    if "oneway" in gdf_edges.columns:
+        gdf_edges["oneway"] = gdf_edges["oneway"].fillna(ONEWAY).replace({True: "yes", False: "no"})
+    gdf_edges = gdf_edges.rename(columns={"osmid": "id"}).drop(columns=["geometry"])
+
+    # create parent XML element then add bounds, nodes, ways as subelements
+    element = Element("osm", attrib=ROOT_ATTR_DEFAULTS)
+    _ = SubElement(element, "bounds", attrib=bounds)
+    _add_nodes_xml(element, gdf_nodes)
+    _add_ways_xml(element, gdf_edges, way_tag_aggs)
+
+    # write to disk
+    ElementTree(element).write(filepath, encoding=encoding, xml_declaration=True)
+    msg = f"Saved graph as OSM XML file at {str(filepath)!r}"
+    utils.log(msg, level=lg.INFO)
+
+
+def _add_nodes_xml(
+    parent: Element,
+    gdf_nodes: gpd.GeoDataFrame,
+) -> None:
+    """
+    Add graph nodes as subelements of an XML parent element.
+
+    Parameters
+    ----------
+    parent
+        The XML parent element.
+    gdf_nodes
+        A GeoDataFrame of graph nodes.
+    """
+    node_tags = set(settings.useful_tags_node)
+    node_attrs = {"id", "lat", "lon"}.union(ATTR_DEFAULTS)
+
+    # add each node attrs dict as a SubElement of parent
+    for node in gdf_nodes.to_dict(orient="records"):
+        attrs = {k: str(node[k]) for k in node_attrs if pd.notna(node[k])}
+        node_element = SubElement(parent, "node", attrib=attrs)
+
+        # add each node tag dict as its own SubElement of the node SubElement
+        # for vals that are non-null (or list if node consolidation was done)
+        tags = (
+            {"k": k, "v": str(node[k])}
+            for k in node_tags & node.keys()
+            if isinstance(node[k], list) or pd.notna(node[k])
+        )
+        for tag in tags:
+            _ = SubElement(node_element, "tag", attrib=tag)
+
+
+def _add_ways_xml(
+    parent: Element,
+    gdf_edges: gpd.GeoDataFrame,
+    way_tag_aggs: dict[str, Any] | None,
+) -> None:
+    """
+    Add graph edges (grouped as ways) as subelements of an XML parent element.
+
+    Parameters
+    ----------
+    parent
+        The XML parent element.
+    gdf_edges
+        A GeoDataFrame of graph edges with OSM way "id" column for grouping
+        edges into ways.
+    way_tag_aggs
+        Keys are OSM way tag keys and values are aggregation functions
+        (anything accepted as an argument by `pandas.agg`). Allows user to
+        aggregate graph edge attribute values into single OSM way values. If
+        None, or if some tag's key does not exist in the dict, the way
+        attribute will be assigned the value of the first edge of the way.
+    """
+    way_tags = set(settings.useful_tags_way)
+    way_attrs = list({"id"}.union(ATTR_DEFAULTS))
+
+    for osmid, way in gdf_edges.groupby("id"):
+        # STEP 1: add the way and its attrs as a "way" subelement of the
+        # parent element
+        attrs = way[way_attrs].iloc[0].astype(str).to_dict()
+        way_element = SubElement(parent, "way", attrib=attrs)
+
+        # STEP 2: add the way's edges' node IDs as "nd" subelements of the
+        # "way" subelement. if way contains more than 1 edge, sort the nodes
+        # topologically, otherwise just add node "u" then "v" from index.
+        if len(way) == 1:
+            nodes = way.index[0][:2]
+        else:
+            nodes = _sort_nodes(nx.MultiDiGraph(way.index.to_list()), osmid)
+        for node in nodes:
+            _ = SubElement(way_element, "nd", attrib={"ref": str(node)})
+
+        # STEP 3: add way's edges' tags as "tag" subelements of the "way"
+        # subelement. if an agg function was provided for a tag, apply it to
+        # the values of the edges in the way. if no agg function was provided
+        # for a tag, just use the value from first edge in way.
+        for tag in way_tags.intersection(way.columns):
+            if way_tag_aggs is not None and tag in way_tag_aggs:
+                value = way[tag].agg(way_tag_aggs[tag])
+            else:
+                value = way[tag].iloc[0]
+            if pd.notna(value):
+                _ = SubElement(way_element, "tag", attrib={"k": tag, "v": str(value)})
+
+
+def _sort_nodes(G: nx.MultiDiGraph, osmid: int) -> list[int]:
+    """
+    Topologically sort the nodes of an OSM way.
+
+    Parameters
+    ----------
+    G
+        The graph representing the OSM way.
+    osmid
+        The OSM way ID.
+
+    Returns
+    -------
+    ordered_nodes
+        The way's node IDs in topologically sorted order.
+    """
+    try:
+        ordered_nodes = list(nx.topological_sort(G))
+
+    except nx.NetworkXUnfeasible:
+        # if it couldn't topologically sort the nodes, the way probably
+        # contains a cycle. try removing an edge to break the cycle. first,
+        # look for multiple edges emanating from the same source node
+        insert_before = True
+        edges = [
+            edge
+            for source in [node for node, degree in G.out_degree() if degree > 1]
+            for edge in G.out_edges(source, keys=True)
+        ]
+
+        # if none found, then look for multiple edges pointing at the same
+        # target node instead
+        if len(edges) == 0:
+            insert_before = False
+            edges = [
+                edge
+                for target in [node for node, degree in G.in_degree() if degree > 1]
+                for edge in G.in_edges(target, keys=True)
+            ]
+
+            # if still none, then take the first edge of the way: the entire
+            # way could just be a cycle in which each node appears once
+            if len(edges) == 0:
+                edges = [next(iter(G.edges))]
+
+        # remove one edge at a time and, if the graph remains connected, exit
+        # the loop and check if we are able to topologically sort the nodes
+        for edge in edges:
+            G_ = G.copy()
+            G_.remove_edge(*edge)
+            if nx.is_weakly_connected(G_):
+                break
+
+        try:
+            ordered_nodes = list(nx.topological_sort(G_))
+
+            # re-insert (before or after its neighbor as needed) the duplicate
+            # source or target node from the edge we removed
+            dupe_node = edge[0] if insert_before else edge[1]
+            neighbor = edge[1] if insert_before else edge[0]
+            position = ordered_nodes.index(neighbor)
+            position = position if insert_before else position + 1
+            ordered_nodes.insert(position, dupe_node)
+
+        except nx.NetworkXUnfeasible:
+            # if it failed again, this way probably contains multiple cycles,
+            # so remove a cycle then try to sort the nodes again, recursively.
+            # note this is destructive and will be missing in the saved data.
+            G_ = G.copy()
+            G_.remove_edges_from(nx.find_cycle(G_))
+            G_ = truncate.largest_component(G_)
+            ordered_nodes = _sort_nodes(G_, osmid)
+            msg = f"Had to remove a cycle from way {osmid!r} for topological sort"
+            utils.log(msg, level=lg.WARNING)
+
+    return ordered_nodes

osmnx/source/osmnx/_overpass.py

@@ -0,0 +1,493 @@
+"""Tools to work with the Overpass API."""
+
+from __future__ import annotations
+
+import datetime as dt
+import logging as lg
+import time
+from collections import OrderedDict
+from typing import TYPE_CHECKING
+from typing import Any
+
+import numpy as np
+import requests
+from requests.exceptions import ConnectionError as RequestsConnectionError
+
+from . import _http
+from . import projection
+from . import settings
+from . import utils
+from . import utils_geo
+from ._errors import InsufficientResponseError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from shapely import MultiPolygon
+    from shapely import Polygon
+
+
+def _get_network_filter(network_type: str) -> str:
+    """
+    Create a filter to query Overpass for the specified network type.
+
+    The filter queries Overpass for every OSM way with a "highway" tag but
+    excludes ways that are incompatible with the requested network type. You
+    can choose from the following types:
+
+    "all" retrieves all public and private-access ways currently in use,
+    excluding those that represent areas either explicitly (area=yes) or by
+    convention (rest_area, services).
+
+    "all_public" retrieves all public ways currently in use.
+
+    "bike" retrieves public bikeable ways and excludes foot ways, motor ways,
+    and anything tagged biking=no.
+
+    "drive" retrieves public drivable streets and excludes service roads,
+    anything tagged motor=no, and certain non-service roads tagged as
+    providing certain services (such as alleys or driveways).
+
+    "drive_service" retrieves public drivable streets including service roads
+    but excludes certain services (such as parking or emergency access).
+
+    "walk" retrieves public walkable ways and excludes cycle ways, motor ways,
+    and anything tagged foot=no. It includes service roads like parking lot
+    aisles and alleys that you can walk on even if they are unpleasant walks.
+
+    Parameters
+    ----------
+    network_type
+        {"all", "all_public", "bike", "drive", "drive_service", "walk"}
+        What type of street network to retrieve.
+
+    Returns
+    -------
+    way_filter
+        The Overpass query filter.
+    """
+    # define built-in queries to send to the API. specifying way["highway"]
+    # means that all ways returned must have a highway tag. the filters then
+    # remove ways by tag/value.
+    filters = {}
+
+    # driving: filter out un-drivable roads, service roads, private ways, and
+    # anything tagged motor=no. also filter out any non-service roads that are
+    # tagged as providing certain services
+    filters["drive"] = (
+        f'["highway"]["area"!~"yes"]{settings.default_access}'
+        f'["highway"!~"abandoned|bridleway|bus_guideway|construction|corridor|'
+        f"cycleway|elevator|escalator|footway|no|path|pedestrian|planned|platform|"
+        f'proposed|raceway|razed|rest_area|service|services|steps|track"]'
+        f'["motor_vehicle"!~"no"]["motorcar"!~"no"]'
+        f'["service"!~"alley|driveway|emergency_access|parking|parking_aisle|private"]'
+    )
+
+    # drive+service: allow ways tagged 'service' but filter out certain types
+    filters["drive_service"] = (
+        f'["highway"]["area"!~"yes"]{settings.default_access}'
+        f'["highway"!~"abandoned|bridleway|bus_guideway|construction|corridor|'
+        f"cycleway|elevator|escalator|footway|no|path|pedestrian|planned|platform|"
+        f'proposed|raceway|razed|rest_area|services|steps|track"]'
+        f'["motor_vehicle"!~"no"]["motorcar"!~"no"]'
+        f'["service"!~"emergency_access|parking|parking_aisle|private"]'
+    )
+
+    # walking: filter out cycle ways, motor ways, private ways, and anything
+    # tagged foot=no. allow service roads, permitting things like parking lot
+    # aisles, alleys, etc that you *can* walk on even if they're not exactly
+    # pleasant walks. some cycleways may allow pedestrians, but this filter
+    # ignores such cycleways.
+    filters["walk"] = (
+        f'["highway"]["area"!~"yes"]{settings.default_access}'
+        f'["highway"!~"abandoned|bus_guideway|construction|cycleway|motor|no|planned|'
+        f'platform|proposed|raceway|razed|rest_area|services"]'
+        f'["foot"!~"no"]["service"!~"private"]'
+        f'["sidewalk"!~"separate"]["sidewalk:both"!~"separate"]'
+        f'["sidewalk:left"!~"separate"]["sidewalk:right"!~"separate"]'
+    )
+
+    # biking: filter out foot ways, motor ways, private ways, and anything
+    # tagged biking=no
+    filters["bike"] = (
+        f'["highway"]["area"!~"yes"]{settings.default_access}'
+        f'["highway"!~"abandoned|bus_guideway|construction|corridor|elevator|'
+        f"escalator|footway|motor|no|planned|platform|proposed|raceway|razed|"
+        f'rest_area|services|steps"]'
+        f'["bicycle"!~"no"]["service"!~"private"]'
+    )
+
+    # to download all public ways, just filter out everything not currently in
+    # use or that is private-access only
+    filters["all_public"] = (
+        f'["highway"]["area"!~"yes"]{settings.default_access}'
+        f'["highway"!~"abandoned|construction|no|planned|platform|proposed|raceway|'
+        f'razed|rest_area|services"]'
+        f'["service"!~"private"]'
+    )
+
+    # to download all ways, including private-access ones, just filter out
+    # everything not currently in use
+    filters["all"] = (
+        '["highway"]["area"!~"yes"]["highway"!~"abandoned|construction|no|planned|'
+        'platform|proposed|raceway|razed|rest_area|services"]'
+    )
+
+    if network_type in filters:
+        way_filter = filters[network_type]
+    else:  # pragma: no cover
+        msg = f"Unrecognized network_type {network_type!r}."
+        raise ValueError(msg)
+
+    return way_filter
+
+
+def _get_overpass_pause(
+    base_endpoint: str,
+    *,
+    recursion_pause: float = 5,
+    default_pause: float = 60,
+) -> float:
+    """
+    Retrieve a pause duration from the Overpass API status endpoint.
+
+    Check the Overpass API status endpoint to determine how long to wait until
+    the next slot is available. You can disable this via the `settings`
+    module's `overpass_rate_limit` setting.
+
+    Parameters
+    ----------
+    base_endpoint
+        Base Overpass API URL (without "/status" at the end).
+    recursion_pause
+        How long to wait between recursive calls if the server is currently
+        running a query.
+    default_pause
+        If a fatal error occurs, fall back on this liberal pause duration.
+
+    Returns
+    -------
+    pause
+        The current pause duration specified by the Overpass status endpoint.
+    """
+    # if overpass rate limiting is False, then there is zero pause
+    if not settings.overpass_rate_limit:
+        return 0
+
+    url = base_endpoint.rstrip("/") + "/status"
+
+    # try to retrieve the URL
+    try:
+        response = requests.get(
+            url,
+            headers=_http._get_http_headers(),
+            timeout=settings.requests_timeout,
+            **settings.requests_kwargs,
+        )
+        response_text = response.text
+    except RequestsConnectionError as e:  # pragma: no cover
+        # cannot reach status endpoint: log error and return default duration
+        msg = f"Unable to reach {url}, {e}"
+        utils.log(msg, level=lg.ERROR)
+        return default_pause
+
+    # try to parse the output
+    try:
+        status = response_text.split("\n")[4]
+        status_first_part = status.split(" ")[0]
+    except (AttributeError, IndexError, ValueError):  # pragma: no cover
+        # cannot parse output: log error and return default duration
+        msg = f"Unable to parse {url} response: {response_text}"
+        utils.log(msg, level=lg.ERROR)
+        return default_pause
+
+    # determine the current status of the server
+    try:
+        # if first token is numeric, it's how many slots you have available,
+        # no wait required
+        _ = int(status_first_part)  # number of available slots
+        pause: float = 0
+
+    except ValueError:  # pragma: no cover
+        # if first token is 'Slot', it tells you when your slot will be free
+        if status_first_part == "Slot":
+            utc_time_str = status.split(" ")[3]
+            pattern = "%Y-%m-%dT%H:%M:%SZ,"
+            utc_time = dt.datetime.strptime(utc_time_str, pattern).replace(tzinfo=dt.UTC)
+            utc_now = dt.datetime.now(tz=dt.UTC)
+            seconds = int(np.ceil((utc_time - utc_now).total_seconds()))
+            pause = max(seconds, 1)
+
+        # if first token is 'Currently', it is currently running a query so
+        # check back in recursion_pause seconds
+        elif status_first_part == "Currently":
+            time.sleep(recursion_pause)
+            pause = _get_overpass_pause(base_endpoint)
+
+        # any other status is unrecognized: log error, return default duration
+        else:
+            msg = f"Unrecognized server status: {status!r}"
+            utils.log(msg, level=lg.ERROR)
+            return default_pause
+
+    return pause
+
+
+def _make_overpass_settings() -> str:
+    """
+    Make settings string to send in Overpass query.
+
+    Returns
+    -------
+    overpass_settings
+        The `settings.overpass_settings` string formatted with "timeout" and
+        "maxsize" values.
+    """
+    maxsize = "" if settings.overpass_memory is None else f"[maxsize:{settings.overpass_memory}]"
+    return settings.overpass_settings.format(timeout=settings.requests_timeout, maxsize=maxsize)
+
+
+def _make_overpass_polygon_coord_strs(polygon: Polygon | MultiPolygon) -> list[str]:
+    """
+    Subdivide query polygon and return list of coordinate strings.
+
+    Project to UTM, divide `polygon` up into sub-polygons if area exceeds a
+    max size (in meters), project back to lat-lon, then get a list of
+    polygon(s) exterior coordinates. Ignore interior ("holes") coordinates.
+
+    Parameters
+    ----------
+    polygon
+        The (Multi)Polygon to convert to exterior coordinate strings.
+
+    Returns
+    -------
+    coord_strs
+        Exterior coordinates of polygon(s).
+    """
+    # subdivide the polygon if its area exceeds max size
+    # this results in a multipolygon of 1+ constituent polygons
+    poly_proj, crs_proj = projection.project_geometry(polygon)
+    multi_poly_proj = utils_geo._consolidate_subdivide_geometry(poly_proj)
+    multi_poly, _ = projection.project_geometry(multi_poly_proj, crs=crs_proj, to_latlong=True)
+
+    # then extract each's exterior coords to the string format Overpass
+    # expects, rounding lats and lons to 6 decimals (approx 5 to 10 cm
+    # resolution) so we can hash and cache URL strings consistently
+    coord_strs = []
+    for geom in multi_poly.geoms:
+        x, y = geom.exterior.xy
+        coord_list = [f"{xy[1]:.6f}{' '}{xy[0]:.6f}" for xy in zip(x, y, strict=True)]
+        coord_strs.append(" ".join(coord_list))
+
+    return coord_strs
+
+
+def _create_overpass_features_query(  # noqa: PLR0912
+    polygon_coord_str: str,
+    tags: dict[str, bool | str | list[str]],
+) -> str:
+    """
+    Create an Overpass features query string based on tags.
+
+    Parameters
+    ----------
+    polygon_coord_str
+        The lat lon coordinates.
+    tags
+        Tags used for finding elements in the search area.
+
+    Returns
+    -------
+    query
+        The Overpass features query.
+    """
+    # create overpass settings string
+    overpass_settings = _make_overpass_settings()
+
+    # make sure every value in dict is bool, str, or list of str
+    err_msg = "`tags` must be a dict with values of bool, str, or list of str."
+    if not isinstance(tags, dict):  # pragma: no cover
+        raise TypeError(err_msg)
+
+    tags_dict: dict[str, bool | str | list[str]] = {}
+    for key, value in tags.items():
+        if isinstance(value, bool):
+            tags_dict[key] = value
+
+        elif isinstance(value, str):
+            tags_dict[key] = [value]
+
+        elif isinstance(value, list):
+            if not all(isinstance(s, str) for s in value):  # pragma: no cover
+                raise TypeError(err_msg)
+            tags_dict[key] = value
+
+        else:  # pragma: no cover
+            raise TypeError(err_msg)
+
+    # convert the tags dict into a list of {tag:value} dicts
+    tags_list: list[dict[str, bool | str | list[str]]] = []
+    for key, value in tags_dict.items():
+        if isinstance(value, bool):
+            tags_list.append({key: value})
+        else:
+            for value_item in value:
+                tags_list.append({key: value_item})  # noqa: PERF401
+
+    # add node/way/relation query components one at a time
+    components = []
+    for d in tags_list:
+        for key, value in d.items():
+            if isinstance(value, bool):
+                # if bool (ie, True) just pass the key, no value
+                tag_str = f"[{key!r}](poly:{polygon_coord_str!r});(._;>;);"
+            else:
+                # otherwise, pass "key"="value"
+                tag_str = f"[{key!r}={value!r}](poly:{polygon_coord_str!r});(._;>;);"
+
+            for kind in ("node", "way", "relation"):
+                components.append(f"({kind}{tag_str});")  # noqa: PERF401
+
+    # finalize query and return
+    components_str = "".join(components)
+    return f"{overpass_settings};({components_str});out;"
+
+
+def _download_overpass_network(
+    polygon: Polygon | MultiPolygon,
+    network_type: str,
+    custom_filter: str | list[str] | None,
+) -> Iterator[dict[str, Any]]:
+    """
+    Retrieve networked ways and nodes within boundary from the Overpass API.
+
+    Parameters
+    ----------
+    polygon
+        The boundary to fetch the network ways/nodes within.
+    network_type
+        What type of street network to get if `custom_filter` is None.
+    custom_filter
+        A custom "ways" filter to be used instead of `network_type` presets.
+
+    Yields
+    ------
+    response_json
+        JSON response from the Overpass server.
+    """
+    # create filter(s) to exclude certain kinds of ways based on the requested
+    # network_type, if provided, otherwise use custom_filter
+    way_filters = []
+    if isinstance(custom_filter, list):
+        way_filters = custom_filter
+    elif isinstance(custom_filter, str):
+        way_filters = [custom_filter]
+    else:
+        way_filters = [_get_network_filter(network_type)]
+
+    # create overpass settings string
+    overpass_settings = _make_overpass_settings()
+
+    # subdivide query polygon to get list of sub-divided polygon coord strings
+    polygon_coord_strs = _make_overpass_polygon_coord_strs(polygon)
+    msg = f"Requesting data from API in {len(polygon_coord_strs)} request(s)"
+    utils.log(msg, level=lg.INFO)
+
+    # pass exterior coordinates of each polygon in list to API, one at a time
+    # the '>' makes it recurse so we get ways and the ways' nodes.
+    for polygon_coord_str in polygon_coord_strs:
+        for way_filter in way_filters:
+            query_str = f"{overpass_settings};(way{way_filter}(poly:{polygon_coord_str!r});>;);out;"
+            yield _overpass_request(OrderedDict(data=query_str))
+
+
+def _download_overpass_features(
+    polygon: Polygon,
+    tags: dict[str, bool | str | list[str]],
+) -> Iterator[dict[str, Any]]:
+    """
+    Retrieve OSM features within some boundary polygon from the Overpass API.
+
+    Parameters
+    ----------
+    polygon
+        Boundary to retrieve elements within.
+    tags
+        Tags used for finding elements in the selected area.
+
+    Yields
+    ------
+    response_json
+        JSON response from the Overpass server.
+    """
+    # subdivide query polygon to get list of sub-divided polygon coord strings
+    polygon_coord_strs = _make_overpass_polygon_coord_strs(polygon)
+    msg = f"Requesting data from API in {len(polygon_coord_strs)} request(s)"
+    utils.log(msg, level=lg.INFO)
+
+    # pass exterior coordinates of each polygon in list to API, one at a time
+    for polygon_coord_str in polygon_coord_strs:
+        query_str = _create_overpass_features_query(polygon_coord_str, tags)
+        yield _overpass_request(OrderedDict(data=query_str))
+
+
+def _overpass_request(data: OrderedDict[str, Any]) -> dict[str, Any]:
+    """
+    Send a HTTP POST request to the Overpass API and return response.
+
+    Parameters
+    ----------
+    data
+        Key-value pairs of parameters.
+
+    Returns
+    -------
+    response_json
+        The Overpass API's response.
+    """
+    # resolve url to same IP even if there is server round-robin redirecting
+    _http._config_dns(settings.overpass_url)
+
+    # prepare the Overpass API URL and see if request already exists in cache
+    url = settings.overpass_url.rstrip("/") + "/interpreter"
+    prepared_url = str(requests.Request("GET", url, params=data).prepare().url)
+    cached_response_json = _http._retrieve_from_cache(prepared_url)
+    if isinstance(cached_response_json, dict):
+        return cached_response_json
+
+    # pause then request this URL
+    pause = _get_overpass_pause(settings.overpass_url)
+    hostname = _http._hostname_from_url(url)
+    msg = f"Pausing {pause} second(s) before making HTTP POST request to {hostname!r}"
+    utils.log(msg, level=lg.INFO)
+    time.sleep(pause)
+
+    # transmit the HTTP POST request
+    msg = f"Post {prepared_url} with timeout={settings.requests_timeout}"
+    utils.log(msg, level=lg.INFO)
+    response = requests.post(
+        url,
+        data=data,
+        timeout=settings.requests_timeout,
+        headers=_http._get_http_headers(),
+        **settings.requests_kwargs,
+    )
+
+    # handle 429 and 504 errors by pausing then recursively re-trying request
+    if response.status_code in {429, 504}:  # pragma: no cover
+        error_pause = 55
+        msg = (
+            f"{hostname!r} responded {response.status_code} {response.reason}: "
+            f"we'll retry in {error_pause} secs"
+        )
+        utils.log(msg, level=lg.WARNING)
+        time.sleep(error_pause)
+        return _overpass_request(data)
+
+    response_json = _http._parse_response(response)
+    if not isinstance(response_json, dict):  # pragma: no cover
+        msg = "Overpass API did not return a dict of results."
+        raise InsufficientResponseError(msg)
+    _http._save_to_cache(prepared_url, response_json, response.ok)
+    return response_json

osmnx/source/osmnx/_validate.py

@@ -0,0 +1,387 @@
+"""Validate that graphs and GeoDataFrames satisfy OSMnx expectations."""
+
+from __future__ import annotations
+
+import logging as lg
+from numbers import Real
+from warnings import warn
+
+import geopandas as gpd
+import networkx as nx
+import numpy as np
+
+from ._errors import ValidationError
+from .utils import log
+
+
+def _verify_numeric_edge_attribute(G: nx.MultiDiGraph, attr: str, *, strict: bool = True) -> None:
+    """
+    Verify attribute values are numeric and non-null across graph edges.
+
+    Raises a ValidationError if this attribute contains non-numeric
+    values, and issues a UserWarning if this attribute is missing or null on
+    any edges.
+
+    Parameters
+    ----------
+    G
+        Input graph.
+    attr
+        Name of the edge attribute to verify.
+    strict
+        If `True`, elevate warnings to errors.
+    """
+    is_valid = True
+    valid_msg = "Verified {attr!r} values are numeric and non-null across graph edges."
+    warn_msg = ""
+    err_msg = ""
+
+    try:
+        values_float = (np.array(tuple(G.edges(data=attr)))[:, 2]).astype(float)
+        if np.isnan(values_float).any():
+            warn_msg += f"The attribute {attr!r} is missing or null on some edges."
+            if strict:
+                is_valid = False
+    except ValueError:
+        err_msg += f"The edge attribute {attr!r} contains non-numeric values."
+        is_valid = False
+
+    _report_validation(is_valid, valid_msg, warn_msg, err_msg)
+
+
+def _validate_features_gdf(gdf: gpd.GeoDataFrame) -> None:
+    """
+    Validate that features GeoDataFrame satisfies OSMnx expectations.
+
+    Raises a `ValidationError` if validation fails.
+
+    Parameters
+    ----------
+    gdf
+        GeoDataFrame of features uniquely multi-indexed by
+        `(element_type, osmid)`.
+    """
+    is_valid = True
+    valid_msg = "Validated features GeoDataFrame."
+    warn_msg = ""
+    err_msg = ""
+
+    # ensure gdf is uniquely indexed
+    if not gdf.index.is_unique:
+        err_msg += "`gdf` must be uniquely indexed. "
+        is_valid = False
+
+    # ensure gdf is multi-indexed with 2 levels (element_type and osmid) and
+    # that the element types are all either node, way, or relation
+    features_index_levels = 2
+    check1 = gdf.index.nlevels == features_index_levels
+    element_types = set(gdf.index.get_level_values(0))
+    check2 = element_types.issubset({"node", "way", "relation"})
+    if not (check1 and check2):
+        err_msg += "`gdf` must be multi-indexed by `(element_type, osmid)`. "
+        is_valid = False
+
+    # ensure gdf has an active geometry column with all valid non-null geoms
+    if (gdf.active_geometry_name is None) or (
+        gdf.geometry.isna() | gdf.geometry.is_empty | ~gdf.geometry.is_valid
+    ).any():
+        err_msg += "`gdf` must contain valid, non-null geometries`. "
+        is_valid = False
+
+    _report_validation(is_valid, valid_msg, warn_msg, err_msg)
+
+
+def _validate_node_edge_gdfs(
+    gdf_nodes: gpd.GeoDataFrame,
+    gdf_edges: gpd.GeoDataFrame,
+    *,
+    strict: bool = True,
+) -> None:
+    """
+    Validate that node/edge GeoDataFrames can be converted to a MultiDiGraph.
+
+    Raises a `ValidationError` if validation fails.
+
+    Parameters
+    ----------
+    gdf_nodes
+        GeoDataFrame of graph nodes uniquely indexed by `osmid`.
+    gdf_edges
+        GeoDataFrame of graph edges uniquely multi-indexed by `(u, v, key)`.
+    strict
+        If `True`, elevate warnings to errors.
+    """
+    is_valid = True
+    valid_msg = "Validated that node/edge GeoDataFrames can be converted to a MultiDiGraph."
+    warn_msg = ""
+    err_msg = ""
+
+    # ensure type is GeoDataFrame
+    if not (isinstance(gdf_nodes, gpd.GeoDataFrame) and isinstance(gdf_edges, gpd.GeoDataFrame)):
+        # if they are not both GeoDataFrames
+        err_msg += "`gdf_nodes` and `gdf_edges` must be GeoDataFrames. "
+        is_valid = False
+    # if they are both GeoDataFrames...
+    # warn user if geometry values differ from coordinates in x/y columns,
+    # because we ignore the geometry column
+    elif gdf_nodes.active_geometry_name is not None:
+        msg = (
+            "Will ignore the `gdf_nodes` 'geometry' column, though its values "
+            "differ from the coordinates in the 'x' and 'y' columns. "
+        )
+        try:
+            all_x_match = (gdf_nodes.geometry.x == gdf_nodes["x"]).all()
+            all_y_match = (gdf_nodes.geometry.y == gdf_nodes["y"]).all()
+            if not (all_x_match and all_y_match):
+                # warn if x/y coords don't match geometry column
+                warn_msg += msg
+                if strict:
+                    is_valid = False
+        except ValueError:
+            # warn if geometry column contains non-point geometry types
+            warn_msg += msg
+            if strict:
+                is_valid = False
+
+    # ensure gdf_nodes has x and y columns representing node geometries
+    if not ("x" in gdf_nodes.columns and "y" in gdf_nodes.columns):
+        err_msg += "`gdf_nodes` must have 'x' and 'y' columns. "
+        is_valid = False
+
+    # ensure gdf_nodes and gdf_edges are uniquely indexed
+    if not (gdf_nodes.index.is_unique and gdf_edges.index.is_unique):
+        err_msg += "`gdf_nodes` and `gdf_edges` must each be uniquely indexed. "
+        is_valid = False
+
+    # ensure 1) gdf_edges are multi-indexed with 3 levels and 2) that its u
+    # and v values (first two index levels) all appear among gdf_nodes index
+    edges_index_levels = 3
+    check1 = gdf_edges.index.nlevels == edges_index_levels
+    try:
+        uv = set(gdf_edges.index.get_level_values(0)) | set(gdf_edges.index.get_level_values(1))
+        check2 = uv.issubset(set(gdf_nodes.index))
+    except IndexError:
+        check2 = False
+    if not (check1 and check2):
+        err_msg += "`gdf_edges` must be multi-indexed by `(u, v, key)`. "
+        is_valid = False
+
+    _report_validation(is_valid, valid_msg, warn_msg, err_msg)
+
+
+def _validate_nodes(G: nx.MultiDiGraph, strict: bool) -> tuple[bool, str, str]:  # noqa: FBT001
+    """
+    Validate that a graph's nodes satisfy OSMnx expectations.
+
+    Parameters
+    ----------
+    G
+        The input graph.
+    strict
+        If `True`, elevate warnings to errors.
+
+    Returns
+    -------
+    is_valid, err_msg, warn_msg
+        Whether validation passed, plus any error or warning messages.
+    """
+    # assume nodes are valid but try to falsify that through a series of tests
+    is_valid = True
+    err_msg = ""
+    warn_msg = ""
+
+    # ERR: must have at least 1 node
+    if not len(G.nodes) > 0:
+        err_msg += "G must have at least 1 node. "
+        is_valid = False
+
+    # otherwise, it has at least 1 node, so validate the node attributes
+    else:
+        # ERR: nodes must have "x" and "y" data attributes
+        if not all("x" in d and "y" in d for d in dict(G.nodes(data=True)).values()):
+            err_msg += "Nodes must have 'x' and 'y' data attributes. "
+            is_valid = False
+
+        # WARN: nodes' "x" and "y" data attributes should be type Real
+        valid_xs = all(isinstance(x, Real) for x in nx.get_node_attributes(G, name="x").values())
+        valid_ys = all(isinstance(y, Real) for y in nx.get_node_attributes(G, name="y").values())
+        if not (valid_xs and valid_ys):
+            warn_msg += "Node 'x' and 'y' data attributes should be numeric. "
+            if strict:
+                is_valid = False
+
+        # WARN: nodes should have "street_count" data attributes
+        if not all("street_count" in d for d in dict(G.nodes(data=True)).values()):
+            warn_msg += "Nodes should have 'street_count' data attributes. "
+            if strict:
+                is_valid = False
+
+        # WARN: nodes' "x" and "y" data attributes should be type Real
+        valid_xs = all(isinstance(x, Real) for x in nx.get_node_attributes(G, name="x").values())
+        valid_ys = all(isinstance(y, Real) for y in nx.get_node_attributes(G, name="y").values())
+        if not (valid_xs and valid_ys):
+            warn_msg += "Node 'x' and 'y' data attributes should be numeric. "
+            if strict:
+                is_valid = False
+
+        # WARN: node IDs should be type int
+        if not all(isinstance(n, int) for n in G.nodes):
+            warn_msg += "Node IDs should be type int. "
+            if strict:
+                is_valid = False
+
+    return is_valid, err_msg, warn_msg
+
+
+def _validate_edges(G: nx.MultiDiGraph, strict: bool) -> tuple[bool, str, str]:  # noqa: FBT001
+    """
+    Validate that a graph's edges satisfy OSMnx expectations.
+
+    Parameters
+    ----------
+    G
+        The input graph.
+    strict
+        If `True`, elevate warnings to errors.
+
+    Returns
+    -------
+    is_valid, err_msg, warn_msg
+        Whether validation passed, plus any error or warning messages.
+    """
+    # assume edges are valid but try to falsify that through a series of tests
+    is_valid = True
+    err_msg = ""
+    warn_msg = ""
+
+    # ERR: must have at least 1 edge
+    if not len(G.edges) > 0:
+        err_msg += "G must have at least 1 edge. "
+        is_valid = False
+
+    # otherwise, it has at least 1 edge, so validate the edge attributes
+    else:
+        # ERR: edges must have "osmid" data attributes
+        edge_osmids = nx.get_edge_attributes(G, name="osmid")
+        if set(edge_osmids) != set(G.edges):
+            err_msg += "Edges must have 'osmid' data attributes. "
+            is_valid = False
+
+        # WARN: edge "osmid" data attributes should be type int or list[int]
+        if not all(isinstance(x, (int, list)) for x in edge_osmids.values()):
+            warn_msg += "Edge 'osmid' data attributes should be type `int` or `list[int]`. "
+            if strict:
+                is_valid = False
+
+        # ERR: edges must have "length" data attributes
+        edge_lengths = nx.get_edge_attributes(G, name="length")
+        if set(edge_lengths) != set(G.edges):
+            err_msg += "Edges must have 'length' data attributes. "
+            is_valid = False
+
+        # WARN: edge "length" data attributes should be numeric
+        if not all(isinstance(x, Real) for x in edge_lengths.values()):
+            warn_msg += "Edge 'length' data attributes should be numeric. "
+            if strict:
+                is_valid = False
+
+    return is_valid, err_msg, warn_msg
+
+
+def _validate_graph_attrs(G: nx.MultiDiGraph) -> tuple[bool, str, str]:
+    """
+    Validate that a graph's attributes satisfy OSMnx expectations.
+
+    Parameters
+    ----------
+    G
+        The input graph.
+
+    Returns
+    -------
+    is_valid, err_msg, warn_msg
+        Whether validation passed, plus any error or warning messages.
+    """
+    # assume G is valid but try to falsify that through a series of tests
+    is_valid = True
+    err_msg = ""
+    warn_msg = ""
+
+    # ERR: must be a NetworkX MultiDiGraph
+    if not isinstance(G, nx.MultiDiGraph):
+        err_msg += "G must be a NetworkX MultiDiGraph. "
+        is_valid = False
+
+    # ERR: must have top-level graph, nodes, and edges attributes
+    if not (hasattr(G, "graph") and hasattr(G, "nodes") and hasattr(G, "edges")):
+        err_msg += "G must have top-level graph, nodes, and edges attributes. "
+        is_valid = False
+
+    # ERR: graph attr dict must have a "crs" key defining its CRS
+    crs = getattr(G, "graph", {}).get("crs")
+    if crs is None:
+        err_msg += "G.graph must have a 'crs' data attribute. "
+        is_valid = False
+
+    # ERR: graph attr dict "crs" value must be a valid pyproj CRS
+    else:
+        try:
+            _ = gpd.GeoSeries(crs=crs).crs
+        except RuntimeError:  # RuntimeError is parent of pyproj CRSError
+            err_msg += "G.graph['crs'] must be a valid CRS. "
+            is_valid = False
+
+    return is_valid, err_msg, warn_msg
+
+
+def _validate_graph(G: nx.MultiDiGraph, *, strict: bool = True) -> None:
+    """
+    Validate that a graph object satisfies OSMnx expectations.
+
+    Raises `ox._errors.ValidationError` if validation fails.
+
+    Parameters
+    ----------
+    G
+        The input graph.
+    strict
+        If `True`, elevate warnings to errors.
+    """
+    # validate graph, nodes, and edges
+    is_valid_graph, err_msg_graph, warn_msg_graph = _validate_graph_attrs(G)
+    is_valid_nodes, err_msg_nodes, warn_msg_nodes = _validate_nodes(G, strict)
+    is_valid_edges, err_msg_edges, warn_msg_edges = _validate_edges(G, strict)
+
+    # report results
+    is_valid = is_valid_graph and is_valid_nodes and is_valid_edges
+    err_msg = err_msg_graph + err_msg_nodes + err_msg_edges
+    warn_msg = warn_msg_graph + warn_msg_nodes + warn_msg_edges
+    valid_msg = "Successfully validated graph."
+    _report_validation(is_valid, valid_msg, warn_msg, err_msg)
+
+
+def _report_validation(is_valid: bool, valid_msg: str, warn_msg: str, err_msg: str) -> None:  # noqa: FBT001
+    """
+    Report validation results by logging, warning, or raising an exception.
+
+    Parameters
+    ----------
+    is_valid
+        Whether or not the validation succeeded.
+    valid_msg
+        The message to log if validation succeeded.
+    warn_msg
+        Any warning messages to log and either issue a warning or include in
+        error message.
+    err_msg
+        Any error messages to include when raising exception if validation
+        failed.
+    """
+    if is_valid:
+        log(valid_msg, level=lg.INFO)
+        if warn_msg != "":
+            log(warn_msg, level=lg.WARNING)
+            warn(warn_msg, category=UserWarning, stacklevel=2)
+    else:
+        log(err_msg + warn_msg, level=lg.ERROR)
+        raise ValidationError(err_msg + warn_msg)

osmnx/source/osmnx/bearing.py

@@ -0,0 +1,302 @@
+"""Calculate graph edge bearings and orientation entropy."""
+
+from __future__ import annotations
+
+from types import ModuleType
+from typing import TYPE_CHECKING
+from typing import overload
+from warnings import warn
+
+import networkx as nx
+import numpy as np
+import numpy.typing as npt
+
+from . import projection
+
+if TYPE_CHECKING:
+    from types import ModuleType
+
+# scipy is an optional dependency for entropy calculation
+scipy: ModuleType | None
+try:
+    import scipy
+except ImportError:  # pragma: no cover
+    scipy = None
+
+
+# if coords are all floats, return float
+@overload
+def calculate_bearing(
+    lat1: float,
+    lon1: float,
+    lat2: float,
+    lon2: float,
+) -> float: ...
+
+
+# if coords are all arrays, return array
+@overload
+def calculate_bearing(
+    lat1: npt.NDArray[np.float64],
+    lon1: npt.NDArray[np.float64],
+    lat2: npt.NDArray[np.float64],
+    lon2: npt.NDArray[np.float64],
+) -> npt.NDArray[np.float64]: ...
+
+
+def calculate_bearing(
+    lat1: float | npt.NDArray[np.float64],
+    lon1: float | npt.NDArray[np.float64],
+    lat2: float | npt.NDArray[np.float64],
+    lon2: float | npt.NDArray[np.float64],
+) -> float | npt.NDArray[np.float64]:
+    """
+    Calculate the compass bearing(s) between pairs of lat-lon points.
+
+    Vectorized function to calculate initial bearings between two points'
+    coordinates or between arrays of points' coordinates. Expects coordinates
+    in decimal degrees. The bearing represents the clockwise angle in degrees
+    between north and the geodesic line from `(lat1, lon1)` to `(lat2, lon2)`.
+
+    Parameters
+    ----------
+    lat1
+        First point's latitude coordinate(s).
+    lon1
+        First point's longitude coordinate(s).
+    lat2
+        Second point's latitude coordinate(s).
+    lon2
+        Second point's longitude coordinate(s).
+
+    Returns
+    -------
+    bearing
+        The bearing(s) in decimal degrees.
+    """
+    # get the latitudes and the difference in longitudes, all in radians
+    lat1 = np.deg2rad(lat1)
+    lat2 = np.deg2rad(lat2)
+    delta_lon = np.deg2rad(lon2 - lon1)
+
+    # calculate initial bearing from -180 degrees to +180 degrees
+    y = np.sin(delta_lon) * np.cos(lat2)
+    x = np.cos(lat1) * np.sin(lat2) - np.sin(lat1) * np.cos(lat2) * np.cos(delta_lon)
+    initial_bearing = np.rad2deg(np.arctan2(y, x))
+
+    # normalize to 0-360 degrees to get compass bearing
+    bearing: float | npt.NDArray[np.float64] = initial_bearing % 360
+    return bearing
+
+
+def add_edge_bearings(G: nx.MultiDiGraph) -> nx.MultiDiGraph:
+    """
+    Calculate and add compass `bearing` attributes to all graph edges.
+
+    Vectorized function to calculate (initial) bearing from origin node to
+    destination node for each edge in a directed, unprojected graph then add
+    these bearings as new `bearing` edge attributes. Bearing represents angle
+    in degrees (clockwise) between north and the geodesic line from the origin
+    node to the destination node. Ignores self-loop edges as their bearings
+    are undefined.
+
+    Parameters
+    ----------
+    G
+        Unprojected graph.
+
+    Returns
+    -------
+    G
+        Graph with `bearing` attributes on the edges.
+    """
+    if projection.is_projected(G.graph["crs"]):  # pragma: no cover
+        msg = "Graph must be unprojected to add edge bearings."
+        raise ValueError(msg)
+
+    # extract edge IDs and corresponding coordinates from their nodes
+    uvk = [(u, v, k) for u, v, k in G.edges if u != v]
+    x = G.nodes(data="x")
+    y = G.nodes(data="y")
+    coords = np.array([(y[u], x[u], y[v], x[v]) for u, v, k in uvk])
+
+    # calculate bearings then set as edge attributes
+    bearings = calculate_bearing(coords[:, 0], coords[:, 1], coords[:, 2], coords[:, 3])
+    values = zip(uvk, bearings, strict=True)
+    nx.set_edge_attributes(G, dict(values), name="bearing")
+
+    return G
+
+
+def orientation_entropy(
+    G: nx.MultiGraph | nx.MultiDiGraph,
+    *,
+    num_bins: int = 36,
+    min_length: float = 0,
+    weight: str | None = None,
+) -> float:
+    """
+    Calculate graph's orientation entropy.
+
+    Orientation entropy is the Shannon entropy of the graphs' edges' bearings
+    across evenly spaced bins. Ignores self-loop edges as their bearings are
+    undefined. If `G` is a MultiGraph, all edge bearings will be bidirectional
+    (ie, two reciprocal bearings per undirected edge). If `G` is a
+    MultiDiGraph, all edge bearings will be directional (ie, one bearing per
+    directed edge).
+
+    For more info see: Boeing, G. 2019. "Urban Spatial Order: Street Network
+    Orientation, Configuration, and Entropy." Applied Network Science, 4 (1),
+    67. https://doi.org/10.1007/s41109-019-0189-1
+
+    Parameters
+    ----------
+    G
+        Unprojected graph with `bearing` attributes on each edge.
+    num_bins
+        Number of bins. For example, if `num_bins=36` is provided, then each
+        bin will represent 10 degrees around the compass.
+    min_length
+        Ignore edges with "length" attributes less than `min_length`. Useful
+        to ignore the noise of many very short edges.
+    weight
+        If None, apply equal weight for each bearing. Otherwise, weight edges'
+        bearings by this (non-null) edge attribute. For example, if "length"
+        is provided, each edge's bearing observation will be weighted by its
+        "length" attribute value.
+
+    Returns
+    -------
+    entropy
+        The orientation entropy of `G`.
+    """
+    # check if we were able to import scipy
+    if scipy is None:  # pragma: no cover
+        msg = "scipy must be installed as an optional dependency to calculate entropy."
+        raise ImportError(msg)
+    bin_counts, _ = _bearings_distribution(G, num_bins, min_length, weight)
+    entropy: float = scipy.stats.entropy(bin_counts)
+    return entropy
+
+
+def _extract_edge_bearings(
+    G: nx.MultiGraph | nx.MultiDiGraph,
+    min_length: float,
+    weight: str | None,
+) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
+    """
+    Extract graph's edge bearings.
+
+    Ignores self-loop edges as their bearings are undefined. If `G` is a
+    MultiGraph, all edge bearings will be bidirectional (ie, two reciprocal
+    bearings per undirected edge). If `G` is a MultiDiGraph, all edge bearings
+    will be directional (ie, one bearing per directed edge). For example, if
+    an undirected edge has a bearing of 90 degrees then we will record
+    bearings of both 90 degrees and 270 degrees for this edge.
+
+    Parameters
+    ----------
+    G
+        Unprojected graph with `bearing` attributes on each edge.
+    min_length
+        Ignore edges with `length` attributes less than `min_length`. Useful
+        to ignore the noise of many very short edges.
+    weight
+        If None, apply equal weight for each bearing. Otherwise, weight edges'
+        bearings by this (non-null) edge attribute. For example, if "length"
+        is provided, each edge's bearing observation will be weighted by its
+        "length" attribute value.
+
+    Returns
+    -------
+    bearings, weights
+        The edge bearings of `G` and their corresponding weights.
+    """
+    if projection.is_projected(G.graph["crs"]):  # pragma: no cover
+        msg = "Graph must be unprojected to analyze edge bearings."
+        raise ValueError(msg)
+    bearings = []
+    weights = []
+    for u, v, data in G.edges(data=True):
+        # ignore self-loops and any edges below min_length
+        if u != v and data["length"] >= min_length:
+            bearings.append(data["bearing"])
+            weights.append(data[weight] if weight is not None else 1.0)
+
+    # drop any nulls
+    bearings_array = np.array(bearings)
+    weights_array = np.array(weights)
+    keep_idx = ~np.isnan(bearings_array)
+    bearings_array = bearings_array[keep_idx]
+    weights_array = weights_array[keep_idx]
+    if nx.is_directed(G):
+        msg = (
+            "`G` is a MultiDiGraph, so edge bearings will be directional (one per "
+            "edge). If you want bidirectional edge bearings (two reciprocal bearings "
+            "per edge), pass a MultiGraph instead. Use `convert.to_undirected`."
+        )
+        warn(msg, category=UserWarning, stacklevel=2)
+        return bearings_array, weights_array
+    # for undirected graphs, add reverse bearings
+    bearings_array = np.concatenate([bearings_array, (bearings_array - 180) % 360])
+    weights_array = np.concatenate([weights_array, weights_array])
+    return bearings_array, weights_array
+
+
+def _bearings_distribution(
+    G: nx.MultiGraph | nx.MultiDiGraph,
+    num_bins: int,
+    min_length: float,
+    weight: str | None,
+) -> tuple[npt.NDArray[np.floating], npt.NDArray[np.floating]]:
+    """
+    Compute distribution of bearings across evenly spaced bins.
+
+    Prevents bin-edge effects around common values like 0 degrees and 90
+    degrees by initially creating twice as many bins as desired, then merging
+    them in pairs. For example, if `num_bins=36` is provided, then each bin
+    will represent 10 degrees around the compass, with the first bin
+    representing 355 degrees to 5 degrees.
+
+    Parameters
+    ----------
+    G
+        Unprojected graph with `bearing` attributes on each edge.
+    num_bins
+        Number of bins for the bearing histogram.
+    min_length
+        Ignore edges with `length` attributes less than `min_length`. Useful
+        to ignore the noise of many very short edges.
+    weight
+        If None, apply equal weight for each bearing. Otherwise, weight edges'
+        bearings by this (non-null) edge attribute. For example, if "length"
+        is provided, each edge's bearing observation will be weighted by its
+        "length" attribute value.
+
+    Returns
+    -------
+    bin_counts, bin_centers
+        Counts of bearings per bin and the bins' centers in degrees. Both
+        arrays are of length `num_bins`.
+    """
+    # Split bins in half to prevent bin-edge effects around common values.
+    # Bins will be merged in pairs after the histogram is computed. The last
+    # bin edge is the same as the first (i.e., 0 degrees = 360 degrees).
+    num_split_bins = num_bins * 2
+    split_bin_edges = np.linspace(0, 360, num_split_bins + 1)
+
+    bearings, weights = _extract_edge_bearings(G, min_length, weight)
+    split_bin_counts, split_bin_edges = np.histogram(
+        bearings,
+        bins=split_bin_edges,
+        weights=weights,
+    )
+
+    # Move last bin to front, so eg 0.01 degrees and 359.99 degrees will be
+    # binned together. Then combine counts from pairs of split bins.
+    split_bin_counts = np.roll(split_bin_counts, 1)
+    bin_counts = split_bin_counts[::2] + split_bin_counts[1::2]
+
+    # Every other edge of the split bins is the center of a merged bin.
+    bin_centers = split_bin_edges[range(0, num_split_bins - 1, 2)]
+    return bin_counts, bin_centers

osmnx/source/osmnx/convert.py

@@ -0,0 +1,564 @@
+"""Convert spatial graphs to/from different data types."""
+
+from __future__ import annotations
+
+import itertools
+import logging as lg
+from typing import Any
+from typing import Literal
+from typing import overload
+
+import geopandas as gpd
+import networkx as nx
+import pandas as pd
+from shapely import LineString
+from shapely import Point
+
+from . import _validate
+from . import utils
+
+
+def validate_graph(G: nx.MultiDiGraph, *, strict: bool = True) -> None:
+    """
+    Validate that a graph object satisfies OSMnx expectations.
+
+    Raises `ox._errors.GraphValidationError` if validation fails.
+
+    Parameters
+    ----------
+    G
+        The input graph.
+    strict
+        If `True`, enforce optional rules in addition to required rules. These
+        optional rules primarily enforce expected attribute data types.
+    """
+    _validate._validate_graph(G, strict=strict)
+
+
+def validate_node_edge_gdfs(
+    gdf_nodes: gpd.GeoDataFrame,
+    gdf_edges: gpd.GeoDataFrame,
+    *,
+    strict: bool = True,
+) -> None:
+    """
+    Validate that node/edge GeoDataFrames can be converted to a MultiDiGraph.
+
+    Raises a `ValidationError` if validation fails.
+
+    Parameters
+    ----------
+    gdf_nodes
+        GeoDataFrame of graph nodes uniquely indexed by `osmid`.
+    gdf_edges
+        GeoDataFrame of graph edges uniquely multi-indexed by `(u, v, key)`.
+    strict
+        If `True`, elevate warnings to errors.
+    """
+    _validate._validate_node_edge_gdfs(gdf_nodes, gdf_edges, strict=strict)
+
+
+def validate_features_gdf(gdf: gpd.GeoDataFrame) -> None:
+    """
+    Validate that features GeoDataFrame satisfies OSMnx expectations.
+
+    Raises a `ValidationError` if validation fails.
+
+    Parameters
+    ----------
+    gdf
+        GeoDataFrame of features uniquely multi-indexed by
+        `(element_type, osmid)`.
+    """
+    _validate._validate_features_gdf(gdf)
+
+
+# nodes and edges are both missing (therefore both default true)
+@overload
+def graph_to_gdfs(
+    G: nx.MultiGraph | nx.MultiDiGraph,
+    *,
+    node_geometry: bool = True,
+    fill_edge_geometry: bool = True,
+) -> tuple[gpd.GeoDataFrame, gpd.GeoDataFrame]: ...
+
+
+# both present/True
+@overload
+def graph_to_gdfs(
+    G: nx.MultiGraph | nx.MultiDiGraph,
+    *,
+    nodes: Literal[True],
+    edges: Literal[True],
+    node_geometry: bool = True,
+    fill_edge_geometry: bool = True,
+) -> tuple[gpd.GeoDataFrame, gpd.GeoDataFrame]: ...
+
+
+# both present, nodes true, edges false
+@overload
+def graph_to_gdfs(
+    G: nx.MultiGraph | nx.MultiDiGraph,
+    *,
+    nodes: Literal[True],
+    edges: Literal[False],
+    node_geometry: bool = True,
+    fill_edge_geometry: bool = True,
+) -> gpd.GeoDataFrame: ...
+
+
+# both present, nodes false, edges true
+@overload
+def graph_to_gdfs(
+    G: nx.MultiGraph | nx.MultiDiGraph,
+    *,
+    nodes: Literal[False],
+    edges: Literal[True],
+    node_geometry: bool = True,
+    fill_edge_geometry: bool = True,
+) -> gpd.GeoDataFrame: ...
+
+
+# nodes missing (therefore default true), edges present/true
+@overload
+def graph_to_gdfs(
+    G: nx.MultiGraph | nx.MultiDiGraph,
+    *,
+    edges: Literal[True],
+    node_geometry: bool = True,
+    fill_edge_geometry: bool = True,
+) -> tuple[gpd.GeoDataFrame, gpd.GeoDataFrame]: ...
+
+
+# nodes missing (therefore default true), edges present/false
+@overload
+def graph_to_gdfs(
+    G: nx.MultiGraph | nx.MultiDiGraph,
+    *,
+    edges: Literal[False],
+    node_geometry: bool = True,
+    fill_edge_geometry: bool = True,
+) -> gpd.GeoDataFrame: ...
+
+
+# nodes present/true, edges missing (therefore default true)
+@overload
+def graph_to_gdfs(
+    G: nx.MultiGraph | nx.MultiDiGraph,
+    *,
+    nodes: Literal[True],
+    edges: bool = True,
+    node_geometry: bool = True,
+    fill_edge_geometry: bool = True,
+) -> tuple[gpd.GeoDataFrame, gpd.GeoDataFrame]: ...
+
+
+# nodes present/false, edges missing (therefore default true)
+@overload
+def graph_to_gdfs(
+    G: nx.MultiGraph | nx.MultiDiGraph,
+    *,
+    nodes: Literal[False],
+    edges: bool = True,
+    node_geometry: bool = True,
+    fill_edge_geometry: bool = True,
+) -> gpd.GeoDataFrame: ...
+
+
+def graph_to_gdfs(
+    G: nx.MultiGraph | nx.MultiDiGraph,
+    *,
+    nodes: bool = True,
+    edges: bool = True,
+    node_geometry: bool = True,
+    fill_edge_geometry: bool = True,
+) -> gpd.GeoDataFrame | tuple[gpd.GeoDataFrame, gpd.GeoDataFrame]:
+    """
+    Convert a MultiGraph or MultiDiGraph to node and/or edge GeoDataFrames.
+
+    This function is the inverse of `graph_from_gdfs`.
+
+    Parameters
+    ----------
+    G
+        Input graph.
+    nodes
+        If True, convert graph nodes to a GeoDataFrame and return it.
+    edges
+        If True, convert graph edges to a GeoDataFrame and return it.
+    node_geometry
+        If True, create a geometry column from node "x" and "y" attributes.
+    fill_edge_geometry
+        If True, fill missing edge geometry fields using endpoint nodes'
+        coordinates to create a LineString.
+
+    Returns
+    -------
+    gdf_nodes or gdf_edges or (gdf_nodes, gdf_edges)
+        `gdf_nodes` is indexed by `osmid` and `gdf_edges` is multi-indexed by
+        `(u, v, key)` following normal MultiGraph/MultiDiGraph structure.
+    """
+    crs = G.graph["crs"]
+
+    if nodes:
+        if len(G.nodes) == 0:  # pragma: no cover
+            msg = "Graph contains no nodes."
+            raise ValueError(msg)
+
+        uvk, data = zip(*G.nodes(data=True), strict=True)
+
+        if node_geometry:
+            # convert node x/y attributes to Points for geometry column
+            node_geoms = (Point(d["x"], d["y"]) for d in data)
+            gdf_nodes = gpd.GeoDataFrame(data, index=uvk, crs=crs, geometry=list(node_geoms))
+        else:
+            gdf_nodes = gpd.GeoDataFrame(data, index=uvk)
+
+        gdf_nodes.index = gdf_nodes.index.rename("osmid")
+        msg = "Created nodes GeoDataFrame from graph"
+        utils.log(msg, level=lg.INFO)
+
+    if edges:
+        if len(G.edges) == 0:  # pragma: no cover
+            msg = "Graph contains no edges."
+            raise ValueError(msg)
+
+        u, v, k, data = zip(*G.edges(keys=True, data=True), strict=True)
+
+        if fill_edge_geometry:
+            node_coords = {n: (G.nodes[n]["x"], G.nodes[n]["y"]) for n in G}
+            edge_geoms = (
+                d.get("geometry", LineString((node_coords[u], node_coords[v])))
+                for u, v, _, d in G.edges(keys=True, data=True)
+            )
+            gdf_edges = gpd.GeoDataFrame(data, crs=crs, geometry=list(edge_geoms))
+
+        else:
+            gdf_edges = gpd.GeoDataFrame(data)
+            if "geometry" not in gdf_edges.columns:
+                # if no edges have a geometry attribute, create null column
+                gdf_edges = gdf_edges.set_geometry([None] * len(gdf_edges))
+            gdf_edges = gdf_edges.set_crs(crs)
+
+        # add u, v, key attributes as index
+        gdf_edges["u"] = u
+        gdf_edges["v"] = v
+        gdf_edges["key"] = k
+        gdf_edges = gdf_edges.set_index(["u", "v", "key"])
+
+        msg = "Created edges GeoDataFrame from graph"
+        utils.log(msg, level=lg.INFO)
+
+    if nodes and edges:
+        return gdf_nodes, gdf_edges
+
+    if nodes:
+        return gdf_nodes
+
+    if edges:
+        return gdf_edges
+
+    # otherwise
+    msg = "You must request nodes or edges or both."
+    raise ValueError(msg)
+
+
+def graph_from_gdfs(
+    gdf_nodes: gpd.GeoDataFrame,
+    gdf_edges: gpd.GeoDataFrame,
+    *,
+    graph_attrs: dict[str, Any] | None = None,
+) -> nx.MultiDiGraph:
+    """
+    Convert node and edge GeoDataFrames to a MultiDiGraph.
+
+    This function is the inverse of `graph_to_gdfs` and is designed to work in
+    conjunction with it. However, you can convert arbitrary node and edge
+    GeoDataFrames as long as 1) `gdf_nodes` is uniquely indexed by `osmid`, 2)
+    `gdf_nodes` contains `x` and `y` coordinate columns representing node
+    geometries, 3) `gdf_edges` is uniquely multi-indexed by `(u, v, key)`
+    (following normal MultiDiGraph structure). This allows you to load any
+    node/edge Shapefiles or GeoPackage layers as GeoDataFrames then convert
+    them to a MultiDiGraph for network analysis.
+
+    Note that any `geometry` attribute on `gdf_nodes` is discarded, since `x`
+    and `y` provide the necessary node geometry information instead.
+
+    Parameters
+    ----------
+    gdf_nodes
+        GeoDataFrame of graph nodes uniquely indexed by `osmid`.
+    gdf_edges
+        GeoDataFrame of graph edges uniquely multi-indexed by `(u, v, key)`.
+    graph_attrs
+        The new `G.graph` attribute dictionary. If None, use `gdf_edges`'s CRS
+        as the only graph-level attribute (`gdf_edges` must have its `crs`
+        attribute set).
+
+    Returns
+    -------
+    G
+        The converted MultiDiGraph.
+    """
+    validate_node_edge_gdfs(gdf_nodes, gdf_edges)
+
+    # drop geometry column from gdf_nodes (since we use x and y for geometry
+    # information), but warn the user if the geometry values differ from the
+    # coordinates in the x and y columns. this results in a df instead of gdf.
+    if gdf_nodes.active_geometry_name is None:  # pragma: no cover
+        df_nodes = pd.DataFrame(gdf_nodes)
+    else:
+        df_nodes = gdf_nodes.drop(columns=gdf_nodes.active_geometry_name)
+
+    # create graph and add graph-level attribute dict
+    if graph_attrs is None:
+        graph_attrs = {"crs": gdf_edges.crs}
+    G = nx.MultiDiGraph(**graph_attrs)
+
+    # add edges and their attributes to graph, but filter out null attribute
+    # values so that edges only get attributes with non-null values
+    attr_names = gdf_edges.columns.to_list()
+    for (u, v, k), attr_vals in zip(gdf_edges.index, gdf_edges.to_numpy(), strict=True):
+        data_all = zip(attr_names, attr_vals, strict=True)
+        data = {name: val for name, val in data_all if isinstance(val, list) or pd.notna(val)}
+        G.add_edge(u, v, key=k, **data)
+
+    # add any nodes with no incident edges, since they wouldn't be added above
+    G.add_nodes_from(set(df_nodes.index) - set(G.nodes))
+
+    # now all nodes are added, so set nodes' attributes
+    for col in df_nodes.columns:
+        nx.set_node_attributes(G, name=col, values=df_nodes[col].dropna())
+
+    msg = "Created graph from node/edge GeoDataFrames"
+    utils.log(msg, level=lg.INFO)
+    return G
+
+
+def to_digraph(G: nx.MultiDiGraph, *, weight: str = "length") -> nx.DiGraph:
+    """
+    Convert MultiDiGraph to DiGraph.
+
+    Chooses between parallel edges by minimizing `weight` attribute value. See
+    also `to_undirected` to convert MultiDiGraph to MultiGraph.
+
+    Parameters
+    ----------
+    G
+        Input graph.
+    weight
+        Attribute value to minimize when choosing between parallel edges.
+
+    Returns
+    -------
+    D
+        The converted DiGraph.
+    """
+    # make a copy to not mutate original graph object caller passed in
+    G = G.copy()
+    to_remove: list[tuple[int, int, int]] = []
+
+    # identify all the parallel edges in the MultiDiGraph
+    parallels = ((u, v) for u, v in G.edges(keys=False) if G.number_of_edges(u, v) > 1)
+
+    # among all sets of parallel edges, remove all except the one with the
+    # minimum "weight" attribute value
+    for u, v in set(parallels):
+        k_min, _ = min(G.get_edge_data(u, v).items(), key=lambda x: x[1][weight])
+        to_remove.extend((u, v, k) for k in G[u][v] if k != k_min)
+
+    G.remove_edges_from(to_remove)
+    msg = "Converted MultiDiGraph to DiGraph"
+    utils.log(msg, level=lg.INFO)
+
+    return nx.DiGraph(G)
+
+
+def to_undirected(G: nx.MultiDiGraph) -> nx.MultiGraph:
+    """
+    Convert MultiDiGraph to undirected MultiGraph.
+
+    This function has a limited use case: it allows you to create a MultiGraph
+    for use with functions/algorithms that only accept a MultiGraph object.
+    Rather, if you want a fully bidirectional graph (such as for a walking
+    network), configure the `settings` module's `bidirectional_network_types`
+    before creating your graph to generate a fully bidirectional MultiDiGraph.
+
+    This function maintains parallel edges only if their geometries differ.
+    See also `to_digraph` to convert MultiDiGraph to DiGraph.
+
+    Parameters
+    ----------
+    G
+        Input graph.
+
+    Returns
+    -------
+    Gu
+        The converted MultiGraph.
+    """
+    # make a copy to not mutate original graph object caller passed in
+    G = G.copy()
+
+    # set from/to nodes before making graph undirected
+    for u, v, d in G.edges(data=True):
+        d["from"] = u
+        d["to"] = v
+
+        # add geometry if missing, to compare parallel edges' geometries
+        if "geometry" not in d:
+            point_u = (G.nodes[u]["x"], G.nodes[u]["y"])
+            point_v = (G.nodes[v]["x"], G.nodes[v]["y"])
+            d["geometry"] = LineString([point_u, point_v])
+
+    # increment parallel edges' keys so we don't retain only one edge of sets
+    # of true parallel edges when we convert from MultiDiGraph to MultiGraph
+    G = _update_edge_keys(G)
+
+    # convert MultiDiGraph to MultiGraph, retaining edges in both directions
+    # of parallel edges and self-loops for now
+    Gu = nx.MultiGraph(**G.graph)
+    Gu.add_nodes_from(G.nodes(data=True))
+    Gu.add_edges_from(G.edges(keys=True, data=True))
+
+    # the previous operation added all directed edges from G as undirected
+    # edges in Gu. we now have duplicate edges for each bidirectional parallel
+    # edge or self-loop. so, look through the edges and remove any duplicates.
+    duplicate_edges = set()
+    for u1, v1, key1, data1 in Gu.edges(keys=True, data=True):
+        # if we haven't already flagged this edge as a duplicate
+        if (u1, v1, key1) not in duplicate_edges:
+            # look at every other edge between u and v, one at a time
+            for key2 in Gu[u1][v1]:
+                # don't compare this edge to itself
+                if key1 != key2:
+                    # compare the first edge's data to the second's
+                    # if they match up, flag the duplicate for removal
+                    data2 = Gu.edges[u1, v1, key2]
+                    if _is_duplicate_edge(data1, data2):
+                        duplicate_edges.add((u1, v1, key2))
+
+    Gu.remove_edges_from(duplicate_edges)
+    msg = "Converted MultiDiGraph to undirected MultiGraph"
+    utils.log(msg, level=lg.INFO)
+
+    return Gu
+
+
+def _is_duplicate_edge(data1: dict[str, Any], data2: dict[str, Any]) -> bool:
+    """
+    Check if two graph edge data dicts have the same `osmid` and `geometry`.
+
+    Parameters
+    ----------
+    data1
+        The first edge's attribute data.
+    data2
+        The second edge's attribute data.
+
+    Returns
+    -------
+    is_dupe
+        True if `osmid` and `geometry` are the same, otherwise False.
+    """
+    is_dupe = False
+
+    # if either edge's osmid contains multiple values (due to simplification)
+    # compare them as sets to see if they contain the same values
+    osmid1 = set(data1["osmid"]) if isinstance(data1["osmid"], list) else data1["osmid"]
+    osmid2 = set(data2["osmid"]) if isinstance(data2["osmid"], list) else data2["osmid"]
+
+    # if they contain the same osmid or set of osmids (due to simplification)
+    if osmid1 == osmid2:
+        # if both edges have geometry attributes and they match each other
+        if ("geometry" in data1) and ("geometry" in data2):
+            if _is_same_geometry(data1["geometry"], data2["geometry"]):
+                is_dupe = True
+
+        # if neither edge has a geometry attribute
+        elif ("geometry" not in data1) and ("geometry" not in data2):
+            is_dupe = True
+
+        # if one edge has geometry attribute but the other doesn't: not dupes
+        else:
+            pass
+
+    return is_dupe
+
+
+def _is_same_geometry(ls1: LineString, ls2: LineString) -> bool:
+    """
+    Determine if two LineString geometries are the same (in either direction).
+
+    Check both the normal and reversed orders of their constituent points.
+
+    Parameters
+    ----------
+    ls1
+        The first LineString geometry.
+    ls2
+        The second LineString geometry.
+
+    Returns
+    -------
+    is_same
+        True if geometries are the same in either direction, otherwise False.
+    """
+    # extract coordinates from each LineString geometry
+    geom1 = [tuple(coords) for coords in ls1.xy]
+    geom2 = [tuple(coords) for coords in ls2.xy]
+
+    # reverse the first LineString's coordinates' direction
+    geom1_r = [tuple(reversed(coords)) for coords in ls1.xy]
+
+    # if second geometry matches first in either direction, return True
+    return geom2 in (geom1, geom1_r)
+
+
+def _update_edge_keys(G: nx.MultiDiGraph) -> nx.MultiDiGraph:
+    """
+    Increment key of one edge of parallel edges that differ in geometry.
+
+    For example, two streets from `u` to `v` that bow away from each other as
+    separate streets, rather than opposite direction edges of a single street.
+    Increment one of these edge's keys so that they do not match across
+    `(u, v, k)` or `(v, u, k)` so we can add both to an undirected MultiGraph.
+
+    Parameters
+    ----------
+    G
+        Input graph.
+
+    Returns
+    -------
+    G
+        Graph with incremented keys where needed.
+    """
+    # identify all the edges that are duplicates based on a sorted combination
+    # of their origin, destination, and key. that is, edge uv will match edge vu
+    # as a duplicate, but only if they have the same key
+    edges = graph_to_gdfs(G, nodes=False, fill_edge_geometry=False)
+    edges["uvk"] = ["_".join([*sorted([str(u), str(v)]), str(k)]) for u, v, k in edges.index]
+    mask = edges["uvk"].duplicated(keep=False)
+    dupes = edges[mask].dropna(subset=["geometry"])
+
+    different_streets = []
+    groups = dupes[["geometry", "uvk"]].groupby("uvk")
+
+    # for each group of duplicate edges
+    for _, group in groups:
+        # for each pair of edges within this group
+        for geom1, geom2 in itertools.combinations(group["geometry"], 2):
+            # if they don't have the same geometry, flag them as different
+            # streets: flag edge uvk, but not edge vuk, otherwise we would
+            # increment both their keys and they'll still duplicate each other
+            if not _is_same_geometry(geom1, geom2):
+                different_streets.append(group.index[0])
+
+    # for each unique different street, increment its key to make it unique
+    for u, v, k in set(different_streets):
+        new_key = max(list(G[u][v]) + list(G[v][u])) + 1
+        G.add_edge(u, v, key=new_key, **G.get_edge_data(u, v, k))
+        G.remove_edge(u, v, key=k)
+
+    return G

osmnx/source/osmnx/distance.py

@@ -0,0 +1,545 @@
+"""Calculate distances and find nearest graph node/edge(s) to point(s)."""
+
+from __future__ import annotations
+
+import logging as lg
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+from typing import Literal
+from typing import overload
+
+import networkx as nx
+import numpy as np
+import numpy.typing as npt
+from shapely import Point
+from shapely.strtree import STRtree
+
+from . import convert
+from . import projection
+from . import utils
+
+if TYPE_CHECKING:
+    from types import ModuleType
+
+# scipy is optional dependency for projected nearest-neighbor search
+scipy: ModuleType | None
+try:
+    import scipy
+except ImportError:  # pragma: no cover
+    scipy = None
+
+# scikit-learn is optional dependency for unprojected nearest-neighbor search
+try:
+    from sklearn.neighbors import BallTree
+except ImportError:  # pragma: no cover
+    BallTree = None
+
+EARTH_RADIUS_M = 6_371_009
+
+
+# if coords are all floats, return float
+@overload
+def great_circle(lat1: float, lon1: float, lat2: float, lon2: float) -> float: ...
+
+
+# if coords are all floats (and optional arg is provided), return float
+@overload
+def great_circle(
+    lat1: float,
+    lon1: float,
+    lat2: float,
+    lon2: float,
+    earth_radius: float,
+) -> float: ...
+
+
+# if coords are all arrays, return array
+@overload
+def great_circle(
+    lat1: npt.NDArray[np.float64],
+    lon1: npt.NDArray[np.float64],
+    lat2: npt.NDArray[np.float64],
+    lon2: npt.NDArray[np.float64],
+) -> npt.NDArray[np.float64]: ...
+
+
+# if coords are all arrays (and optional arg is provided), return array
+@overload
+def great_circle(
+    lat1: npt.NDArray[np.float64],
+    lon1: npt.NDArray[np.float64],
+    lat2: npt.NDArray[np.float64],
+    lon2: npt.NDArray[np.float64],
+    earth_radius: float,
+) -> npt.NDArray[np.float64]: ...
+
+
+def great_circle(
+    lat1: float | npt.NDArray[np.float64],
+    lon1: float | npt.NDArray[np.float64],
+    lat2: float | npt.NDArray[np.float64],
+    lon2: float | npt.NDArray[np.float64],
+    earth_radius: float = EARTH_RADIUS_M,
+) -> float | npt.NDArray[np.float64]:
+    """
+    Calculate great-circle distances between pairs of points.
+
+    Vectorized function to calculate the great-circle distance between two
+    points' coordinates or between arrays of points' coordinates using the
+    haversine formula. Expects coordinates in decimal degrees.
+
+    Parameters
+    ----------
+    lat1
+        First point's latitude coordinate(s).
+    lon1
+        First point's longitude coordinate(s).
+    lat2
+        Second point's latitude coordinate(s).
+    lon2
+        Second point's longitude coordinate(s).
+    earth_radius
+        Earth's radius in units in which distance will be returned (default
+        represents meters).
+
+    Returns
+    -------
+    dist
+        Distance from each `(lat1, lon1)` point to each `(lat2, lon2)` point
+        in units of `earth_radius`.
+    """
+    y1 = np.deg2rad(lat1)
+    y2 = np.deg2rad(lat2)
+    delta_y = y2 - y1
+
+    x1 = np.deg2rad(lon1)
+    x2 = np.deg2rad(lon2)
+    delta_x = x2 - x1
+
+    h = np.sin(delta_y / 2) ** 2 + np.cos(y1) * np.cos(y2) * np.sin(delta_x / 2) ** 2
+    h = np.minimum(1, h)  # protect against floating point errors
+    arc = 2 * np.arcsin(np.sqrt(h))
+
+    # return distance in units of earth_radius
+    dist: float | npt.NDArray[np.float64] = arc * earth_radius
+    return dist
+
+
+# if coords are all floats, return float
+@overload
+def euclidean(y1: float, x1: float, y2: float, x2: float) -> float: ...
+
+
+# if coords are all arrays, return array
+@overload
+def euclidean(
+    y1: npt.NDArray[np.float64],
+    x1: npt.NDArray[np.float64],
+    y2: npt.NDArray[np.float64],
+    x2: npt.NDArray[np.float64],
+) -> npt.NDArray[np.float64]: ...
+
+
+def euclidean(
+    y1: float | npt.NDArray[np.float64],
+    x1: float | npt.NDArray[np.float64],
+    y2: float | npt.NDArray[np.float64],
+    x2: float | npt.NDArray[np.float64],
+) -> float | npt.NDArray[np.float64]:
+    """
+    Calculate Euclidean distances between pairs of points.
+
+    Vectorized function to calculate the Euclidean distance between two
+    points' coordinates or between arrays of points' coordinates. For accurate
+    results, use projected coordinates rather than decimal degrees.
+
+    Parameters
+    ----------
+    y1
+        First point's y coordinate(s).
+    x1
+        First point's x coordinate(s).
+    y2
+        Second point's y coordinate(s).
+    x2
+        Second point's x coordinate(s).
+
+    Returns
+    -------
+    dist
+        Distance from each `(x1, y1)` point to each `(x2, y2)` point in same
+        units as the points' coordinates.
+    """
+    # pythagorean theorem
+    dist: float | npt.NDArray[np.float64] = ((x1 - x2) ** 2 + (y1 - y2) ** 2) ** 0.5
+    return dist
+
+
+def add_edge_lengths(
+    G: nx.MultiDiGraph,
+    *,
+    edges: Iterable[tuple[int, int, int]] | None = None,
+) -> nx.MultiDiGraph:
+    """
+    Calculate and add `length` attribute (in meters) to each edge.
+
+    Vectorized function to calculate great-circle distance between each edge's
+    incident nodes. Ensure graph is unprojected and unsimplified to calculate
+    accurate distances.
+
+    Note: this function is run by all the `graph.graph_from_x` functions
+    automatically to add `length` attributes to all edges. It calculates edge
+    lengths as the great-circle distance from node `u` to node `v`. When
+    OSMnx automatically runs this function upon graph creation, it does it
+    before simplifying the graph: thus it calculates the straight-line lengths
+    of edge segments that are themselves all straight. Only after
+    simplification do edges take on (potentially) curvilinear geometry. If you
+    wish to calculate edge lengths later, note that you will be calculating
+    straight-line distances which necessarily ignore the curvilinear geometry.
+    Thus you only want to run this function on a graph with all straight edges
+    (such as is the case with an unsimplified graph).
+
+    Parameters
+    ----------
+    G
+        Unprojected and unsimplified input graph.
+    edges
+        The subset of edges to add `length` attributes to, as `(u, v, k)`
+        tuples. If None, add lengths to all edges.
+
+    Returns
+    -------
+    G
+        Graph with `length` attributes on the edges.
+    """
+    uvk = G.edges if edges is None else edges
+
+    # extract edge IDs and corresponding coordinates from their nodes
+    x = G.nodes(data="x")
+    y = G.nodes(data="y")
+    msg = "Some edges missing nodes, possibly due to input data clipping issue."
+    try:
+        # two-dimensional array of coordinates: y0, x0, y1, x1
+        c = np.array([(y[u], x[u], y[v], x[v]) for u, v, k in uvk])
+    except KeyError as e:  # pragma: no cover
+        raise ValueError(msg) from e
+    else:
+        # ensure all coordinates can be converted to float and are non-null
+        if np.isnan(c.astype(float)).any():
+            raise ValueError(msg)
+
+    # calculate great circle distances, round, and fill nulls with zeros
+    dists = great_circle(c[:, 0], c[:, 1], c[:, 2], c[:, 3])
+    dists[np.isnan(dists)] = 0
+    nx.set_edge_attributes(G, values=dict(zip(uvk, dists, strict=True)), name="length")
+
+    msg = "Added length attributes to graph edges"
+    utils.log(msg, level=lg.INFO)
+    return G
+
+
+# if X and Y are floats and return_dist is not provided (defaults False)
+@overload
+def nearest_nodes(G: nx.MultiDiGraph, X: float, Y: float) -> int: ...
+
+
+# if X and Y are floats and return_dist is provided/False
+@overload
+def nearest_nodes(
+    G: nx.MultiDiGraph,
+    X: float,
+    Y: float,
+    *,
+    return_dist: Literal[False],
+) -> int: ...
+
+
+# if X and Y are floats and return_dist is provided/True
+@overload
+def nearest_nodes(
+    G: nx.MultiDiGraph,
+    X: float,
+    Y: float,
+    *,
+    return_dist: Literal[True],
+) -> tuple[npt.NDArray[np.int64], npt.NDArray[np.float64]]: ...
+
+
+# if X and Y are iterable and return_dist is not provided (defaults False)
+@overload
+def nearest_nodes(
+    G: nx.MultiDiGraph,
+    X: Iterable[float],
+    Y: Iterable[float],
+) -> npt.NDArray[np.int64]: ...
+
+
+# if X and Y are iterable and return_dist is provided/False
+@overload
+def nearest_nodes(
+    G: nx.MultiDiGraph,
+    X: Iterable[float],
+    Y: Iterable[float],
+    *,
+    return_dist: Literal[False],
+) -> npt.NDArray[np.int64]: ...
+
+
+# if X and Y are iterable and return_dist is provided/True
+@overload
+def nearest_nodes(
+    G: nx.MultiDiGraph,
+    X: Iterable[float],
+    Y: Iterable[float],
+    *,
+    return_dist: Literal[True],
+) -> tuple[npt.NDArray[np.int64], npt.NDArray[np.float64]]: ...
+
+
+def nearest_nodes(
+    G: nx.MultiDiGraph,
+    X: float | Iterable[float],
+    Y: float | Iterable[float],
+    *,
+    return_dist: bool = False,
+) -> (
+    int
+    | npt.NDArray[np.int64]
+    | tuple[int, float]
+    | tuple[npt.NDArray[np.int64], npt.NDArray[np.float64]]
+):
+    """
+    Find the nearest node to a point or to each of several points.
+
+    If `X` and `Y` are single coordinate values, this function will return the
+    nearest node to that point. If `X` and `Y` are iterables of coordinate
+    values, it will return the nearest node to each point.
+
+    This function is vectorized: if you have many points to search for, pass
+    them in one call as numpy arrays (avoid using loops) to maximize runtime
+    speed. If the graph is projected, it uses a k-d tree for Euclidean nearest
+    neighbor search, which requires that scipy is installed as an optional
+    dependency. If the graph is unprojected, it uses a ball tree for haversine
+    nearest neighbor search, which requires that scikit-learn is installed as
+    an optional dependency.
+
+    Parameters
+    ----------
+    G
+        Graph in which to find nearest nodes.
+    X
+        The points' x (longitude) coordinates, in same CRS/units as graph and
+        containing no nulls.
+    Y
+        The points' y (latitude) coordinates, in same CRS/units as graph and
+        containing no nulls.
+    return_dist
+        If True, optionally also return the distance(s) between point(s) and
+        nearest node(s).
+
+    Returns
+    -------
+    nn or (nn, dist)
+        Nearest node ID(s) or optionally a tuple of ID(s) and distance(s)
+        between each point and its nearest node.
+    """
+    # make coordinates arrays whether user passed iterable values or not
+    if not (isinstance(X, Iterable) and isinstance(Y, Iterable)):
+        is_scalar = True
+        X_arr = np.array([X])
+        Y_arr = np.array([Y])
+    else:
+        is_scalar = False
+        X_arr = np.array(X)
+        Y_arr = np.array(Y)
+
+    if np.isnan(X_arr).any() or np.isnan(Y_arr).any():  # pragma: no cover
+        msg = "`X` and `Y` cannot contain nulls."
+        raise ValueError(msg)
+
+    nodes = convert.graph_to_gdfs(G, edges=False, node_geometry=False)[["x", "y"]]
+    nn_array: npt.NDArray[np.int64]
+    dist_array: npt.NDArray[np.float64]
+
+    if projection.is_projected(G.graph["crs"]):
+        # if projected, use k-d tree for euclidean nearest-neighbor search
+        if scipy is None:  # pragma: no cover
+            msg = "scipy must be installed as an optional dependency to search a projected graph."
+            raise ImportError(msg)
+        dist_array, pos = scipy.spatial.cKDTree(nodes).query(np.array([X_arr, Y_arr]).T, k=1)
+        nn_array = nodes.index[pos].to_numpy()
+
+    else:
+        # if unprojected, use ball tree for haversine nearest-neighbor search
+        if BallTree is None:  # pragma: no cover
+            msg = "scikit-learn must be installed as an optional dependency to search an unprojected graph."
+            raise ImportError(msg)
+        # haversine requires lat, lon coords in radians
+        nodes_rad = np.deg2rad(nodes[["y", "x"]])
+        points_rad = np.deg2rad(np.array([Y_arr, X_arr]).T)
+        dist_array, pos = BallTree(nodes_rad, metric="haversine").query(points_rad, k=1)
+        dist_array = dist_array[:, 0] * EARTH_RADIUS_M  # convert radians -> meters
+        nn_array = nodes.index[pos[:, 0]].to_numpy()
+
+    # convert results to correct types for return
+    if is_scalar:
+        nn = int(nn_array[0])
+        dist = float(dist_array[0])
+        if return_dist:
+            return nn, dist
+        # otherwise
+        return nn
+
+    # otherwise
+    if return_dist:
+        return nn_array, dist_array
+    # otherwise
+    return nn_array
+
+
+# if X and Y are floats and return_dist is not provided (defaults False)
+@overload
+def nearest_edges(G: nx.MultiDiGraph, X: float, Y: float) -> tuple[int, int, int]: ...
+
+
+# if X and Y are floats and return_dist is provided/False
+@overload
+def nearest_edges(
+    G: nx.MultiDiGraph,
+    X: float,
+    Y: float,
+    *,
+    return_dist: Literal[False],
+) -> tuple[int, int, int]: ...
+
+
+# if X and Y are floats and return_dist is provided/True
+@overload
+def nearest_edges(
+    G: nx.MultiDiGraph,
+    X: float,
+    Y: float,
+    *,
+    return_dist: Literal[True],
+) -> tuple[tuple[int, int, int], float]: ...
+
+
+# if X and Y are iterable and return_dist is not provided (defaults False)
+@overload
+def nearest_edges(
+    G: nx.MultiDiGraph,
+    X: Iterable[float],
+    Y: Iterable[float],
+) -> npt.NDArray[np.object_]: ...
+
+
+# if X and Y are iterable and return_dist is provided/False
+@overload
+def nearest_edges(
+    G: nx.MultiDiGraph,
+    X: Iterable[float],
+    Y: Iterable[float],
+    *,
+    return_dist: Literal[False],
+) -> npt.NDArray[np.object_]: ...
+
+
+# if X and Y are iterable and return_dist is provided/True
+@overload
+def nearest_edges(
+    G: nx.MultiDiGraph,
+    X: Iterable[float],
+    Y: Iterable[float],
+    *,
+    return_dist: Literal[True],
+) -> tuple[npt.NDArray[np.object_], npt.NDArray[np.float64]]: ...
+
+
+def nearest_edges(
+    G: nx.MultiDiGraph,
+    X: float | Iterable[float],
+    Y: float | Iterable[float],
+    *,
+    return_dist: bool = False,
+) -> (
+    tuple[int, int, int]
+    | npt.NDArray[np.object_]
+    | tuple[tuple[int, int, int], float]
+    | tuple[npt.NDArray[np.object_], npt.NDArray[np.float64]]
+):
+    """
+    Find the nearest edge to a point or to each of several points.
+
+    If `X` and `Y` are single coordinate values, this function will return the
+    nearest edge to that point. If `X` and `Y` are iterables of coordinate
+    values, it will return the nearest edge to each point.
+
+    This function is vectorized: if you have many points to search for, pass
+    them in one call as numpy arrays (avoid using loops) to maximize runtime
+    speed. It uses an R-tree spatial index and minimizes the Euclidean
+    distance from each point to the possible matches. For accurate results,
+    use a projected graph and projected points.
+
+    Parameters
+    ----------
+    G
+        Graph in which to find nearest edges.
+    X
+        The points' x (longitude) coordinates, in same CRS/units as graph and
+        containing no nulls.
+    Y
+        The points' y (latitude) coordinates, in same CRS/units as graph and
+        containing no nulls.
+    return_dist
+        If True, optionally also return the distance(s) between point(s) and
+        nearest edge(s), in same units as graph and points.
+
+    Returns
+    -------
+    ne or (ne, dist)
+        Nearest edge ID(s) as `(u, v, k)` tuples, or optionally a tuple of
+        ID(s) and distance(s) between each point and its nearest edge.
+    """
+    # make coordinates arrays whether user passed iterable values or not
+    if not (isinstance(X, Iterable) and isinstance(Y, Iterable)):
+        is_scalar = True
+        X_arr = np.array([X])
+        Y_arr = np.array([Y])
+    else:
+        is_scalar = False
+        X_arr = np.array(X)
+        Y_arr = np.array(Y)
+
+    if np.isnan(X_arr).any() or np.isnan(Y_arr).any():  # pragma: no cover
+        msg = "`X` and `Y` cannot contain nulls."
+        raise ValueError(msg)
+    geoms = convert.graph_to_gdfs(G, nodes=False)["geometry"]
+    ne_array: npt.NDArray[np.object_]  # array of tuple[int, int, int]
+    dist_array: npt.NDArray[np.float64]
+
+    # build an r-tree spatial index by position for subsequent iloc
+    rtree = STRtree(geoms)
+
+    # use the r-tree to find each point's nearest neighbor and distance
+    points = [Point(xy) for xy in zip(X_arr, Y_arr, strict=True)]
+    pos, dist_array = rtree.query_nearest(points, all_matches=False, return_distance=True)
+
+    # if user passed X/Y lists, the 2nd subarray contains geom indices
+    if len(pos.shape) > 1:
+        pos = pos[1]
+    ne_array = geoms.iloc[pos].index.to_numpy()
+
+    # convert results to correct types for return
+    if is_scalar:
+        ne: tuple[int, int, int] = ne_array[0]
+        dist = float(dist_array[0])
+        if return_dist:
+            return ne, dist
+        # otherwise
+        return ne
+
+    # otherwise
+    if return_dist:
+        return ne_array, dist_array
+    # otherwise
+    return ne_array

osmnx/source/osmnx/elevation.py

@@ -0,0 +1,331 @@
+"""Add node elevations from raster files or web APIs, and calculate edge grades."""
+
+from __future__ import annotations
+
+import logging as lg
+import multiprocessing as mp
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import Any
+
+import networkx as nx
+import numpy as np
+import pandas as pd
+import requests
+
+from . import _http
+from . import convert
+from . import settings
+from . import utils
+from ._errors import InsufficientResponseError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+# rasterio and rio-vrt are optional dependencies for raster querying
+try:
+    import rasterio
+except ImportError:  # pragma: no cover
+    rasterio = None
+try:
+    from rio_vrt import build_vrt
+except ImportError:  # pragma: no cover
+    build_vrt = None
+
+
+def add_edge_grades(G: nx.MultiDiGraph, *, add_absolute: bool = True) -> nx.MultiDiGraph:
+    """
+    Calculate and add `grade` attributes to all graph edges.
+
+    Vectorized function to calculate the directed grade (i.e., rise over run)
+    for each edge in the graph and add it to the edge as an attribute. Nodes
+    must already have `elevation` and `length` attributes before using this
+    function.
+
+    See also the `add_node_elevations_raster` and `add_node_elevations_google`
+    functions.
+
+    Parameters
+    ----------
+    G
+        Graph with `elevation` node attributes.
+    add_absolute
+        If True, also add absolute value of grade as `grade_abs` attribute.
+
+    Returns
+    -------
+    G
+        Graph with `grade` (and optionally `grade_abs`) attributes on the
+        edges.
+    """
+    elev_lookup = G.nodes(data="elevation")
+    u, v, k, lengths = zip(*G.edges(keys=True, data="length"), strict=True)
+    uvk = tuple(zip(u, v, k, strict=True))
+
+    # calculate edges' elevation changes from u to v then divide by lengths
+    elevs = np.array([(elev_lookup[u], elev_lookup[v]) for u, v, k in uvk])
+    grades = (elevs[:, 1] - elevs[:, 0]) / np.array(lengths)
+    nx.set_edge_attributes(G, dict(zip(uvk, grades, strict=True)), name="grade")
+
+    # optionally add grade absolute value to the edge attributes
+    if add_absolute:
+        nx.set_edge_attributes(G, dict(zip(uvk, np.abs(grades), strict=True)), name="grade_abs")
+
+    msg = "Added grade attributes to all edges"
+    utils.log(msg, level=lg.INFO)
+    return G
+
+
+def _query_raster(
+    nodes: pd.DataFrame,
+    filepath: str | Path,
+    band: int,
+) -> Iterable[tuple[int, Any]]:
+    """
+    Query a raster file for values at coordinates in DataFrame x/y columns.
+
+    Parameters
+    ----------
+    nodes
+        DataFrame indexed by node ID and with two columns representing x and y
+        coordinates.
+    filepath
+        Path to the raster file or VRT to query.
+    band
+        Which raster band to query.
+
+    Returns
+    -------
+    nodes_values
+        Zip of node IDs and corresponding raster values.
+    """
+    # must open raster file here: cannot pickle it to pass in multiprocessing
+    with rasterio.open(filepath) as raster:
+        values = np.array(tuple(raster.sample(nodes.to_numpy(), band)), dtype=float).squeeze()
+        values[values == raster.nodata] = np.nan
+        return zip(nodes.index, values, strict=True)
+
+
+def _build_vrt_file(raster_paths: Iterable[str | Path]) -> Path:
+    """
+    Build a virtual raster file compositing multiple individual raster files.
+
+    See also https://gdal.org/en/stable/drivers/raster/vrt.html
+
+    Parameters
+    ----------
+    raster_paths
+        The paths to the raster files.
+
+    Returns
+    -------
+    vrt_path
+        The path to the VRT file.
+    """
+    if build_vrt is None:  # pragma: no cover
+        msg = "rio-vrt must be installed as an optional dependency to build VRTs."
+        raise ImportError(msg)
+
+    # determine VRT cache filepath, from stringified sorted raster filepaths
+    raster_paths = sorted(raster_paths)
+    vrt_path = _http._resolve_cache_filepath(str(raster_paths), "vrt")
+
+    # build the VRT file if it doesn't already exist in the cache
+    if not vrt_path.is_file():
+        msg = f"Building VRT for {len(raster_paths):,} rasters at {str(vrt_path)!r}..."
+        utils.log(msg, level=lg.INFO)
+        vrt_path.parent.mkdir(parents=True, exist_ok=True)
+        build_vrt(vrt_path, raster_paths)
+
+    return vrt_path
+
+
+def add_node_elevations_raster(
+    G: nx.MultiDiGraph,
+    filepath: str | Path | Iterable[str | Path],
+    *,
+    band: int = 1,
+    cpus: int | None = None,
+) -> nx.MultiDiGraph:
+    """
+    Add `elevation` attributes to all nodes from local raster file(s).
+
+    If `filepath` is an iterable of paths, this will generate a virtual raster
+    composed of the files at those paths as an intermediate step.
+
+    See also the `add_edge_grades` function.
+
+    Parameters
+    ----------
+    G
+        Graph in same CRS as raster.
+    filepath
+        The path(s) to the raster file(s) to query.
+    band
+        Which raster band to query.
+    cpus
+        How many CPU cores to use if multiprocessing. If None, use all
+        available. If you are multiprocessing, make sure you protect your
+        entry point: see the Python docs for details.
+
+    Returns
+    -------
+    G
+        Graph with `elevation` attributes on the nodes.
+    """
+    if rasterio is None:  # pragma: no cover
+        msg = "rasterio must be installed as an optional dependency to query rasters."
+        raise ImportError(msg)
+
+    # if multiple filepaths are passed in, compose them as a virtual raster
+    if not isinstance(filepath, (str, Path)):
+        filepath = _build_vrt_file(filepath)
+
+    if cpus is None:
+        cpus = mp.cpu_count()
+    cpus = min(cpus, mp.cpu_count())
+    msg = f"Attaching elevations with {cpus} CPUs..."
+    utils.log(msg, level=lg.INFO)
+
+    nodes = convert.graph_to_gdfs(G, edges=False, node_geometry=False)[["x", "y"]]
+    if cpus == 1:
+        elevs = dict(_query_raster(nodes, filepath, band))
+    else:
+        # divide nodes into equal-sized chunks for multiprocessing
+        size = int(np.ceil(len(nodes) / cpus))
+        args = ((nodes.iloc[i : i + size], filepath, band) for i in range(0, len(nodes), size))
+        with mp.get_context().Pool(cpus) as pool:
+            results = pool.starmap_async(_query_raster, args).get()
+        elevs = {k: v for kv in results for k, v in kv}
+
+    nx.set_node_attributes(G, elevs, name="elevation")
+    msg = "Added elevation data from raster to all nodes"
+    utils.log(msg, level=lg.INFO)
+    return G
+
+
+def add_node_elevations_google(
+    G: nx.MultiDiGraph,
+    *,
+    api_key: str | None = None,
+    batch_size: int = 512,
+    pause: float = 0,
+) -> nx.MultiDiGraph:
+    """
+    Add `elevation` (meters) attributes to all nodes using a web API.
+
+    By default this uses the Google Maps Elevation API, but you could instead
+    use any equivalent API with the same interface and response format (such
+    as the Open Topo Data API or the Open-Elevation API) via the `settings`
+    module's `elevation_url_template`. Adjust the `batch_size` and `pause`
+    arguments as needed for the provider. The Google Maps Elevation API
+    requires an API key but other providers may not. You can find more
+    information about the Google Maps Elevation API interface and format at:
+    https://developers.google.com/maps/documentation/elevation
+
+    For a free local alternative see the `add_node_elevations_raster`
+    function. See also the `add_edge_grades` function.
+
+    Parameters
+    ----------
+    G
+        Graph to add elevation data to.
+    api_key
+        A valid API key. Can be None if the API does not require a key.
+    batch_size
+        Max number of coordinate pairs to submit in each request (depends on
+        provider's limits). Google's limit is 512.
+    pause
+        How long to pause in seconds between API calls, which can be increased
+        if you get rate limited.
+
+    Returns
+    -------
+    G
+        Graph with `elevation` attributes on the nodes.
+    """
+    # make a pandas series of all the nodes' coordinates as "lat,lon" and
+    # round coordinates to 6 decimal places (approx 5 to 10 cm resolution)
+    node_points = pd.Series({n: f"{d['y']:.6f},{d['x']:.6f}" for n, d in G.nodes(data=True)})
+    n_calls = int(np.ceil(len(node_points) / batch_size))
+    hostname = _http._hostname_from_url(settings.elevation_url_template)
+
+    msg = f"Requesting node elevations from {hostname!r} in {n_calls} request(s)"
+    utils.log(msg, level=lg.INFO)
+
+    # break the series of coordinates into chunks of batch_size
+    # API format is locations=lat,lon|lat,lon|lat,lon|lat,lon...
+    results = []
+    for i in range(0, len(node_points), batch_size):
+        chunk = node_points.iloc[i : i + batch_size]
+        locations = "|".join(chunk)
+        url = settings.elevation_url_template.format(locations=locations, key=api_key)
+
+        # download and append these elevation results to list of all results
+        response_json = _elevation_request(url, pause)
+        if "results" in response_json and len(response_json["results"]) > 0:
+            results.extend(response_json["results"])
+        else:
+            raise InsufficientResponseError(str(response_json))
+
+    # sanity check that all our vectors have the same number of elements
+    msg = f"Graph has {len(G):,} nodes and we received {len(results):,} results from {hostname!r}"
+    utils.log(msg, level=lg.INFO)
+    if not (len(results) == len(G) == len(node_points)):  # pragma: no cover
+        err_msg = f"{msg}\n{response_json}"
+        raise InsufficientResponseError(err_msg)
+
+    # add elevation as an attribute to the nodes
+    df_elev = pd.DataFrame(node_points, columns=["node_points"])
+    df_elev["elevation"] = [result["elevation"] for result in results]
+    nx.set_node_attributes(G, name="elevation", values=df_elev["elevation"].to_dict())
+    msg = f"Added elevation data from {hostname!r} to all nodes."
+    utils.log(msg, level=lg.INFO)
+
+    return G
+
+
+def _elevation_request(url: str, pause: float) -> dict[str, Any]:
+    """
+    Send a HTTP GET request to a Google Maps-style elevation API.
+
+    Parameters
+    ----------
+    url
+        URL of API endpoint, populated with request data.
+    pause
+        How long to pause in seconds before request.
+
+    Returns
+    -------
+    response_json
+        The elevation API's response.
+    """
+    # check if request already exists in cache
+    cached_response_json = _http._retrieve_from_cache(url)
+    if isinstance(cached_response_json, dict):
+        return cached_response_json
+
+    # pause then request this URL
+    hostname = _http._hostname_from_url(url)
+    msg = f"Pausing {pause} second(s) before making HTTP GET request to {hostname!r}"
+    utils.log(msg, level=lg.INFO)
+    time.sleep(pause)
+
+    # transmit the HTTP GET request
+    msg = f"Get {url} with timeout={settings.requests_timeout}"
+    utils.log(msg, level=lg.INFO)
+    response = requests.get(
+        url,
+        timeout=settings.requests_timeout,
+        headers=_http._get_http_headers(),
+        **settings.requests_kwargs,
+    )
+
+    response_json = _http._parse_response(response)
+    if not isinstance(response_json, dict):  # pragma: no cover
+        msg = "Elevation API did not return a dict of results."
+        raise InsufficientResponseError(msg)
+    _http._save_to_cache(url, response_json, response.ok)
+    return response_json

osmnx/source/osmnx/features.py

@@ -0,0 +1,734 @@
+"""
+Download and create GeoDataFrames from OpenStreetMap geospatial features.
+
+Retrieve points of interest, building footprints, transit lines/stops, or any
+other map features from OSM, including their geometries and attribute data,
+then construct a GeoDataFrame of them. You can use this module to query for
+nodes, ways, and relations (the latter of type "multipolygon" or "boundary"
+only) by passing a dictionary of desired OSM tags.
+
+For more details, see https://wiki.openstreetmap.org/wiki/Map_features and
+https://wiki.openstreetmap.org/wiki/Elements
+
+Refer to the Getting Started guide for usage limitations.
+"""
+
+from __future__ import annotations
+
+import logging as lg
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import Any
+
+import geopandas as gpd
+import pandas as pd
+from shapely import LineString
+from shapely import MultiLineString
+from shapely import MultiPolygon
+from shapely import Point
+from shapely import Polygon
+from shapely import prepare
+from shapely.errors import GEOSException
+from shapely.ops import linemerge
+from shapely.ops import polygonize
+from shapely.ops import unary_union
+
+from . import _osm_xml
+from . import _overpass
+from . import geocoder
+from . import settings
+from . import utils
+from . import utils_geo
+from ._errors import CacheOnlyInterruptError
+from ._errors import InsufficientResponseError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+# define what types of OSM relations we currently handle
+_RELATION_TYPES = {"boundary", "multipolygon"}
+
+# OSM tags to determine if closed ways should be polygons, based on JSON from
+# https://wiki.openstreetmap.org/wiki/Overpass_turbo/Polygon_Features
+_POLYGON_FEATURES: dict[str, dict[str, str | set[str]]] = {
+    "aeroway": {"polygon": "blocklist", "values": {"taxiway"}},
+    "amenity": {"polygon": "all"},
+    "area": {"polygon": "all"},
+    "area:highway": {"polygon": "all"},
+    "barrier": {
+        "polygon": "passlist",
+        "values": {"city_wall", "ditch", "hedge", "retaining_wall", "spikes"},
+    },
+    "boundary": {"polygon": "all"},
+    "building": {"polygon": "all"},
+    "building:part": {"polygon": "all"},
+    "craft": {"polygon": "all"},
+    "golf": {"polygon": "all"},
+    "highway": {"polygon": "passlist", "values": {"elevator", "escape", "rest_area", "services"}},
+    "historic": {"polygon": "all"},
+    "indoor": {"polygon": "all"},
+    "landuse": {"polygon": "all"},
+    "leisure": {"polygon": "all"},
+    "man_made": {"polygon": "blocklist", "values": {"cutline", "embankment", "pipeline"}},
+    "military": {"polygon": "all"},
+    "natural": {
+        "polygon": "blocklist",
+        "values": {"arete", "cliff", "coastline", "ridge", "tree_row"},
+    },
+    "office": {"polygon": "all"},
+    "place": {"polygon": "all"},
+    "power": {"polygon": "passlist", "values": {"generator", "plant", "substation", "transformer"}},
+    "public_transport": {"polygon": "all"},
+    "railway": {
+        "polygon": "passlist",
+        "values": {"platform", "roundhouse", "station", "turntable"},
+    },
+    "ruins": {"polygon": "all"},
+    "shop": {"polygon": "all"},
+    "tourism": {"polygon": "all"},
+    "waterway": {"polygon": "passlist", "values": {"boatyard", "dam", "dock", "riverbank"}},
+}
+
+
+def features_from_bbox(
+    bbox: tuple[float, float, float, float],
+    tags: dict[str, bool | str | list[str]],
+) -> gpd.GeoDataFrame:
+    """
+    Download OSM features within a lat-lon bounding box.
+
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings. This function searches for
+    features using tags. For more details, see:
+    https://wiki.openstreetmap.org/wiki/Map_features
+
+    Parameters
+    ----------
+    bbox
+        Bounding box as `(left, bottom, right, top)`. Coordinates should be in
+        unprojected latitude-longitude degrees (EPSG:4326).
+    tags
+        Tags for finding elements in the selected area. Results are the union,
+        not intersection of the tags and each result matches at least one tag.
+        The keys are OSM tags (e.g. `building`, `landuse`, `highway`, etc) and
+        the values can be either `True` to retrieve all elements matching the
+        tag, or a string to retrieve a single `tag:value` combination, or a
+        list of strings to retrieve multiple values for the tag. For example,
+        `tags = {'building': True}` would return all buildings in the area.
+        Or, `tags = {'amenity':True, 'landuse':['retail','commercial'],
+        'highway':'bus_stop'}` would return all amenities, any landuse=retail,
+        any landuse=commercial, and any highway=bus_stop.
+
+    Returns
+    -------
+    gdf
+        The features, multi-indexed by element type and OSM ID.
+    """
+    # convert bbox to polygon then create GeoDataFrame of features within it
+    polygon = utils_geo.bbox_to_poly(bbox)
+    return features_from_polygon(polygon, tags)
+
+
+def features_from_point(
+    center_point: tuple[float, float],
+    tags: dict[str, bool | str | list[str]],
+    dist: float,
+) -> gpd.GeoDataFrame:
+    """
+    Download OSM features within some distance of a lat-lon point.
+
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings. This function searches for
+    features using tags. For more details, see:
+    https://wiki.openstreetmap.org/wiki/Map_features
+
+    Parameters
+    ----------
+    center_point
+        The `(lat, lon)` center point around which to retrieve the features.
+        Coordinates should be in unprojected latitude-longitude degrees
+        (EPSG:4326).
+    tags
+        Tags for finding elements in the selected area. Results are the union,
+        not intersection of the tags and each result matches at least one tag.
+        The keys are OSM tags (e.g. `building`, `landuse`, `highway`, etc) and
+        the values can be either `True` to retrieve all elements matching the
+        tag, or a string to retrieve a single `tag:value` combination, or a
+        list of strings to retrieve multiple values for the tag. For example,
+        `tags = {'building': True}` would return all buildings in the area.
+        Or, `tags = {'amenity':True, 'landuse':['retail','commercial'],
+        'highway':'bus_stop'}` would return all amenities, any landuse=retail,
+        any landuse=commercial, and any highway=bus_stop.
+    dist
+        Distance in meters from `center_point` to create a bounding box to
+        query.
+
+    Returns
+    -------
+    gdf
+        The features, multi-indexed by element type and OSM ID.
+    """
+    # create bbox from point and dist, then create gdf of features within it
+    bbox = utils_geo.bbox_from_point(center_point, dist)
+    return features_from_bbox(bbox, tags)
+
+
+def features_from_address(
+    address: str,
+    tags: dict[str, bool | str | list[str]],
+    dist: float,
+) -> gpd.GeoDataFrame:
+    """
+    Download OSM features within some distance of an address.
+
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings. This function searches for
+    features using tags. For more details, see:
+    https://wiki.openstreetmap.org/wiki/Map_features
+
+    Parameters
+    ----------
+    address
+        The address to geocode and use as the center point around which to
+        retrieve the features.
+    tags
+        Tags for finding elements in the selected area. Results are the union,
+        not intersection of the tags and each result matches at least one tag.
+        The keys are OSM tags (e.g. `building`, `landuse`, `highway`, etc) and
+        the values can be either `True` to retrieve all elements matching the
+        tag, or a string to retrieve a single `tag:value` combination, or a
+        list of strings to retrieve multiple values for the tag. For example,
+        `tags = {'building': True}` would return all buildings in the area.
+        Or, `tags = {'amenity':True, 'landuse':['retail','commercial'],
+        'highway':'bus_stop'}` would return all amenities, any landuse=retail,
+        any landuse=commercial, and any highway=bus_stop.
+    dist
+        Distance in meters from `address` to create a bounding box to query.
+
+    Returns
+    -------
+    gdf
+        The features, multi-indexed by element type and OSM ID.
+    """
+    # geocode the address to a point, then create gdf of features around it
+    center_point = geocoder.geocode(address)
+    return features_from_point(center_point, tags, dist)
+
+
+def features_from_place(
+    query: str | dict[str, str] | list[str | dict[str, str]],
+    tags: dict[str, bool | str | list[str]],
+    *,
+    which_result: int | None | list[int | None] = None,
+) -> gpd.GeoDataFrame:
+    """
+    Download OSM features within the boundaries of some place(s).
+
+    The query must be geocodable and OSM must have polygon boundaries for the
+    geocode result. If OSM does not have a polygon for this place, you can
+    instead get features within it using the `features_from_address`
+    function, which geocodes the place name to a point and gets the features
+    within some distance of that point.
+
+    If OSM does have polygon boundaries for this place but you're not finding
+    it, try to vary the query string, pass in a structured query dict, or vary
+    the `which_result` argument to use a different geocode result. If you know
+    the OSM ID of the place, you can retrieve its boundary polygon using the
+    `geocode_to_gdf` function, then pass it to the `features_from_polygon`
+    function.
+
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings. This function searches for
+    features using tags. For more details, see:
+    https://wiki.openstreetmap.org/wiki/Map_features
+
+    Parameters
+    ----------
+    query
+        The query or queries to geocode to retrieve place boundary polygon(s).
+    tags
+        Tags for finding elements in the selected area. Results are the union,
+        not intersection of the tags and each result matches at least one tag.
+        The keys are OSM tags (e.g. `building`, `landuse`, `highway`, etc) and
+        the values can be either `True` to retrieve all elements matching the
+        tag, or a string to retrieve a single `tag:value` combination, or a
+        list of strings to retrieve multiple values for the tag. For example,
+        `tags = {'building': True}` would return all buildings in the area.
+        Or, `tags = {'amenity':True, 'landuse':['retail','commercial'],
+        'highway':'bus_stop'}` would return all amenities, any landuse=retail,
+        any landuse=commercial, and any highway=bus_stop.
+    which_result
+        Which search result to return. If None, auto-select the first
+        (Multi)Polygon or raise an error if OSM doesn't return one.
+
+    Returns
+    -------
+    gdf
+        The features, multi-indexed by element type and OSM ID.
+    """
+    # extract the geometry from the GeoDataFrame to use in query
+    polygon = geocoder.geocode_to_gdf(query, which_result=which_result).union_all()
+    msg = "Constructed place geometry polygon(s) to query Overpass"
+    utils.log(msg, level=lg.INFO)
+
+    # create GeoDataFrame using this polygon(s) geometry
+    return features_from_polygon(polygon, tags)
+
+
+def features_from_polygon(
+    polygon: Polygon | MultiPolygon,
+    tags: dict[str, bool | str | list[str]],
+) -> gpd.GeoDataFrame:
+    """
+    Download OSM features within the boundaries of a (Multi)Polygon.
+
+    You can use the `settings` module to retrieve a snapshot of historical OSM
+    data as of a certain date, or to configure the Overpass server timeout,
+    memory allocation, and other custom settings. This function searches for
+    features using tags. For more details, see:
+    https://wiki.openstreetmap.org/wiki/Map_features
+
+    Parameters
+    ----------
+    polygon
+        The geometry within which to retrieve features. Coordinates should be
+        in unprojected latitude-longitude degrees (EPSG:4326).
+    tags
+        Tags for finding elements in the selected area. Results are the union,
+        not intersection of the tags and each result matches at least one tag.
+        The keys are OSM tags (e.g. `building`, `landuse`, `highway`, etc) and
+        the values can be either `True` to retrieve all elements matching the
+        tag, or a string to retrieve a single `tag:value` combination, or a
+        list of strings to retrieve multiple values for the tag. For example,
+        `tags = {'building': True}` would return all buildings in the area.
+        Or, `tags = {'amenity':True, 'landuse':['retail','commercial'],
+        'highway':'bus_stop'}` would return all amenities, any landuse=retail,
+        any landuse=commercial, and any highway=bus_stop.
+
+    Returns
+    -------
+    gdf
+        The features, multi-indexed by element type and OSM ID.
+    """
+    # verify that the geometry is valid and is a Polygon/MultiPolygon
+    if not polygon.is_valid:
+        msg = "The geometry of `polygon` is invalid."
+        raise ValueError(msg)
+
+    if not isinstance(polygon, (Polygon, MultiPolygon)):
+        msg = (
+            "Boundaries must be a Polygon or MultiPolygon. If you requested "
+            "`features_from_place`, ensure your query geocodes to a Polygon "
+            "or MultiPolygon. See the documentation for details."
+        )
+        raise TypeError(msg)
+
+    # retrieve the data from Overpass then turn it into a GeoDataFrame
+    response_jsons = _overpass._download_overpass_features(polygon, tags)
+    return _create_gdf(response_jsons, polygon, tags)
+
+
+def features_from_xml(
+    filepath: str | Path,
+    *,
+    polygon: Polygon | MultiPolygon | None = None,
+    tags: dict[str, bool | str | list[str]] | None = None,
+    encoding: str = "utf-8",
+) -> gpd.GeoDataFrame:
+    """
+    Create a GeoDataFrame of OSM features from data in an OSM XML file.
+
+    Because this function creates a GeoDataFrame of features from an OSM XML
+    file that has already been downloaded (i.e., no query is made to the
+    Overpass API), the `polygon` and `tags` arguments are optional. If they
+    are None, filtering will be skipped.
+
+    Parameters
+    ----------
+    filepath
+        Path to file containing OSM XML data.
+    polygon
+        Spatial boundaries to optionally filter the final GeoDataFrame.
+    tags
+        Query tags to optionally filter the final GeoDataFrame.
+    encoding
+        The OSM XML file's character encoding.
+
+    Returns
+    -------
+    gdf
+        The features, multi-indexed by element type and OSM ID.
+    """
+    # if tags or polygon is None, create an empty object to skip filtering
+    if tags is None:
+        tags = {}
+    if polygon is None:
+        polygon = Polygon()
+
+    # transmogrify OSM XML file to JSON then create GeoDataFrame from it
+    response_jsons = [_osm_xml._overpass_json_from_xml(Path(filepath), encoding)]
+    gdf = _create_gdf(response_jsons, polygon, tags)
+
+    # drop misc element attrs that might have been added from OSM XML file
+    to_drop = set(gdf.columns) & {"changeset", "timestamp", "uid", "user", "version"}
+    return gdf.drop(columns=list(to_drop))
+
+
+def _create_gdf(
+    response_jsons: Iterable[dict[str, Any]],
+    polygon: Polygon | MultiPolygon,
+    tags: dict[str, bool | str | list[str]],
+) -> gpd.GeoDataFrame:
+    """
+    Convert Overpass API JSON responses to a GeoDataFrame of features.
+
+    Parameters
+    ----------
+    response_jsons
+        Iterable of Overpass API JSON responses.
+    polygon
+        Spatial boundaries to optionally filter the final GeoDataFrame.
+    tags
+        Query tags to optionally filter the final GeoDataFrame.
+
+    Returns
+    -------
+    gdf
+        GeoDataFrame of features with tags and geometry columns.
+    """
+    # consume response_jsons generator to download data from server
+    elements = []
+    response_count = 0
+    for response_json in response_jsons:
+        response_count += 1
+        if not settings.cache_only_mode:
+            elements.extend(response_json["elements"])
+
+    msg = f"Retrieved {len(elements):,} elements from API in {response_count} request(s)"
+    utils.log(msg, level=lg.INFO)
+    if settings.cache_only_mode:
+        msg = "Interrupted because `settings.cache_only_mode=True`."
+        raise CacheOnlyInterruptError(msg)
+
+    # convert the elements into a GeoDataFrame of features
+    gdf = (
+        gpd.GeoDataFrame(
+            data=_process_features(elements, set(tags.keys())),
+            geometry="geometry",
+            crs=settings.default_crs,
+        )
+        .set_index(["element", "id"])
+        .sort_index()
+    )
+    return _filter_features(gdf, polygon, tags)
+
+
+def _process_features(
+    elements: list[dict[str, Any]],
+    query_tag_keys: set[str],
+) -> list[dict[str, Any]]:
+    """
+    Convert node/way/relation elements into features with geometries.
+
+    Parameters
+    ----------
+    elements
+        The node/way/relation elements retrieved from the server.
+    query_tag_keys
+        The keys of the tags used to query for matching features.
+
+    Returns
+    -------
+    features
+        The features with geometries.
+    """
+    nodes = []  # all nodes, including ones that just compose ways
+    feature_nodes = []  # nodes that possibly match our query tags
+    node_coords = {}  # hold node lon,lat tuples to create way geoms
+    ways = []  # all ways, including ones that just compose relations
+    feature_ways = []  # ways that possibly match our query tags
+    way_geoms = {}  # hold way geoms to create relation geoms
+    relations = []  # all relations
+
+    # sort elements by node, way, and relation. only retain relations that
+    # match the relation types we currently handle. remove any geometry tags
+    # (they shouldn't exist) or they'll overwrite our geom attributes later
+    for element in elements:
+        element.get("tags", {}).pop("geometry", None)
+        et = element["type"]
+        if et == "node":
+            nodes.append(element)
+        elif et == "way":
+            ways.append(element)
+        elif et == "relation" and element.get("tags", {}).get("type") in _RELATION_TYPES:
+            relations.append(element)
+
+    # extract all nodes' coords, then add to features any nodes with tags that
+    # match the passed query tags, or with any tags if no query tags passed
+    for node in nodes:
+        node_coords[node["id"]] = (node["lon"], node["lat"])
+        if (len(query_tag_keys) == 0 and len(node.get("tags", {}).keys()) > 0) or (
+            len(query_tag_keys & node.get("tags", {}).keys()) > 0
+        ):
+            node["element"] = node.pop("type")
+            node["geometry"] = Point(node.pop("lon"), node.pop("lat"))
+            node.update(node.pop("tags"))
+            feature_nodes.append(node)
+
+    # build all ways' geometries, then add to features any ways with tags that
+    # match the passed query tags, or with any tags if no query tags passed
+    for way in ways:
+        way["geometry"] = _build_way_geometry(
+            way["id"],
+            way.pop("nodes"),
+            way.get("tags", {}),
+            node_coords,
+        )
+        way_geoms[way["id"]] = way["geometry"]
+        if (len(query_tag_keys) == 0 and len(way.get("tags", {}).keys()) > 0) or (
+            len(query_tag_keys & way.get("tags", {}).keys()) > 0
+        ):
+            way["element"] = way.pop("type")
+            way.update(way.pop("tags"))
+            feature_ways.append(way)
+
+    # process relations and build their geometries
+    for relation in relations:
+        relation["element"] = "relation"
+        relation.update(relation.pop("tags"))
+        relation["geometry"] = _build_relation_geometry(relation.pop("members"), way_geoms)
+
+    features = [*feature_nodes, *feature_ways, *relations]
+    if len(features) == 0:
+        msg = "No matching features. Check query location, tags, and log."
+        raise InsufficientResponseError(msg)
+
+    return features
+
+
+def _build_way_geometry(
+    way_id: int,
+    way_nodes: list[int],
+    way_tags: dict[str, Any],
+    node_coords: dict[int, tuple[float, float]],
+) -> LineString | Polygon:
+    """
+    Build a way's geometry from its constituent nodes' coordinates.
+
+    A way can be a LineString (open or closed way) or a Polygon (closed way)
+    but multi-geometries and polygons with holes are represented as relations.
+    See documentation: https://wiki.openstreetmap.org/wiki/Way#Types_of_ways
+
+    Parameters
+    ----------
+    way_id
+        The way's OSM ID.
+    way_nodes
+        The way's constituent nodes.
+    way_tags
+        The way's tags.
+    node_coords
+        Keyed by OSM node ID with values of `(lat, lon)` coordinate tuples.
+
+    Returns
+    -------
+    geometry
+        The way's geometry.
+    """
+    # a way is a LineString by default, but if it's a closed way and it's not
+    # tagged area=no, check if any of its tags denote it as a polygon instead
+    geom_type = LineString
+    if way_nodes[0] == way_nodes[-1] and way_tags.get("area") != "no":
+        for tag in way_tags.keys() & _POLYGON_FEATURES.keys():
+            rule = _POLYGON_FEATURES[tag]["polygon"]
+            values = _POLYGON_FEATURES[tag].get("values", set())
+            if (
+                rule == "all"
+                or (rule == "passlist" and way_tags[tag] in values)
+                or (rule == "blocklist" and way_tags[tag] not in values)
+            ):
+                geom_type = Polygon
+                break
+
+    # create the way geometry from its constituent nodes' coordinates
+    try:
+        return geom_type(node_coords[node] for node in way_nodes)
+    except (GEOSException, KeyError, ValueError) as e:
+        msg = f"Could not build geometry of way {way_id}: {e!r}"
+        utils.log(msg, level=lg.WARNING)
+        return geom_type()
+
+
+def _build_relation_geometry(
+    members: list[dict[str, Any]],
+    way_geoms: dict[int, LineString | Polygon],
+) -> Polygon | MultiPolygon:
+    """
+    Build a relation's geometry from its constituent member ways' geometries.
+
+    OSM represents simple polygons as closed ways (see `_build_way_geometry`),
+    but it uses relations to represent multipolygons (with or without holes)
+    and polygons with holes. For the former, the relation contains multiple
+    members with role "outer". For the latter, the relation contains at least
+    one member with role "outer" representing the shell(s), and at least one
+    member with role "inner" representing the hole(s). For documentation, see
+    https://wiki.openstreetmap.org/wiki/Relation:multipolygon
+
+    Parameters
+    ----------
+    members
+        The members constituting the relation.
+    way_geoms
+        Keyed by OSM way ID with values of their geometries.
+
+    Returns
+    -------
+    geometry
+        The relation's geometry.
+    """
+    inner_linestrings = []
+    outer_linestrings = []
+    inner_polygons = []
+    outer_polygons = []
+
+    # sort member geometries by member role and geometry type
+    for member in members:
+        if member["type"] == "way":
+            geom = way_geoms.get(member["ref"])
+            if geom is None:
+                # a member's geometry may be missing when loaded from XML, if
+                # so, we cannot build this relation's complete geometry, so
+                # just return a null geometry to be removed at final filtering
+                msg = f"Cannot build relation geometry, missing member way {member['ref']}"
+                utils.log(msg, level=lg.WARNING)
+                return Polygon()
+            role = member["role"]
+            if role == "outer" and geom.geom_type == "LineString":
+                outer_linestrings.append(geom)
+            elif role == "outer" and geom.geom_type == "Polygon":
+                outer_polygons.append(geom)
+            elif role == "inner" and geom.geom_type == "LineString":
+                inner_linestrings.append(geom)
+            elif role == "inner" and geom.geom_type == "Polygon":
+                inner_polygons.append(geom)
+
+    # merge/polygonize outer linestring fragments then add to outer polygons
+    merged_outer_linestrings = linemerge(outer_linestrings)
+    if merged_outer_linestrings.geom_type == "LineString":
+        merged_outer_linestrings = MultiLineString([merged_outer_linestrings])
+    for merged_outer_linestring in merged_outer_linestrings.geoms:
+        outer_polygons += polygonize(merged_outer_linestring)
+
+    # merge/polygonize inner linestring fragments then add to inner polygons
+    merged_inner_linestrings = linemerge(inner_linestrings)
+    if merged_inner_linestrings.geom_type == "LineString":
+        merged_inner_linestrings = MultiLineString([merged_inner_linestrings])
+    for merged_inner_linestring in merged_inner_linestrings.geoms:
+        inner_polygons += polygonize(merged_inner_linestring)
+
+    # remove holes from polygons, if any, then retun
+    return _remove_polygon_holes(outer_polygons, inner_polygons)
+
+
+def _remove_polygon_holes(
+    outer_polygons: list[Polygon],
+    inner_polygons: list[Polygon],
+) -> Polygon | MultiPolygon:
+    """
+    Subtract inner holes from outer polygons.
+
+    This allows possible island polygons within a larger polygon's holes.
+
+    Parameters
+    ----------
+    outer_polygons
+        Polygons, including possible islands within a larger polygon's holes.
+    inner_polygons
+        Inner holes to subtract from the outer polygons that contain them.
+
+    Returns
+    -------
+    geometry
+        The geometry minus inner holes.
+    """
+    if len(inner_polygons) == 0:
+        # if there are no holes to remove, geom is the union of outer polygons
+        geometry = unary_union(outer_polygons)
+    else:
+        # otherwise, remove from each outer poly all inner polys it contains
+        polygons_with_holes = []
+        for outer in outer_polygons:
+            prepare(outer)
+            holes = [inner for inner in inner_polygons if outer.contains(inner)]
+            polygons_with_holes.append(outer.difference(unary_union(holes)))
+        geometry = unary_union(polygons_with_holes)
+
+    # ensure returned geometry is a Polygon or MultiPolygon
+    if isinstance(geometry, (Polygon, MultiPolygon)):
+        return geometry
+    return Polygon()
+
+
+def _filter_features(
+    gdf: gpd.GeoDataFrame,
+    polygon: Polygon | MultiPolygon,
+    tags: dict[str, bool | str | list[str]],
+) -> gpd.GeoDataFrame:
+    """
+    Filter features GeoDataFrame by spatial boundaries and query tags.
+
+    If the `polygon` and `tags` arguments are empty objects, the final
+    GeoDataFrame will not be filtered accordingly.
+
+    Parameters
+    ----------
+    gdf
+        Original GeoDataFrame of features.
+    polygon
+        If not empty, the spatial boundaries to filter the GeoDataFrame.
+    tags
+        If not empty, the query tags to filter the GeoDataFrame.
+
+    Returns
+    -------
+    gdf
+        Filtered GeoDataFrame of features.
+    """
+    # remove any null or empty geometries then fix any invalid geometries
+    gdf = gdf[~(gdf["geometry"].isna() | gdf["geometry"].is_empty)]
+    gdf.loc[:, "geometry"] = gdf["geometry"].make_valid()
+
+    # retain rows with geometries that intersect the polygon
+    if polygon.is_empty:
+        geom_filter = pd.Series(data=True, index=gdf.index)
+    else:
+        idx = utils_geo._intersect_index_quadrats(gdf["geometry"], polygon)
+        geom_filter = gdf.index.isin(idx)
+
+    # retain rows that have any of their tag filters satisfied
+    if len(tags) == 0:
+        tags_filter = pd.Series(data=True, index=gdf.index)
+    else:
+        tags_filter = pd.Series(data=False, index=gdf.index)
+        for col in set(gdf.columns) & tags.keys():
+            value = tags[col]
+            if value is True:
+                tags_filter |= gdf[col].notna()
+            elif isinstance(value, str):
+                tags_filter |= gdf[col] == value
+            elif isinstance(value, list):
+                tags_filter |= gdf[col].isin(set(value))
+
+    # filter gdf then drop any columns with only nulls left after filtering
+    gdf = gdf[geom_filter & tags_filter].dropna(axis="columns", how="all")
+    if len(gdf) == 0:  # pragma: no cover
+        msg = "No matching features. Check query location, tags, and log."
+        raise InsufficientResponseError(msg)
+
+    msg = f"{len(gdf):,} features in the final GeoDataFrame"
+    utils.log(msg, level=lg.INFO)
+    return gdf

osmnx/source/osmnx/geocoder.py

@@ -0,0 +1,244 @@
+"""
+Geocode place names or addresses or retrieve OSM elements by place name or ID.
+
+This module uses the Nominatim API's "search" and "lookup" endpoints. For more
+details see https://wiki.openstreetmap.org/wiki/Elements and
+https://nominatim.org/.
+"""
+
+from __future__ import annotations
+
+import logging as lg
+from collections import OrderedDict
+from typing import Any
+
+import geopandas as gpd
+import pandas as pd
+
+from . import _nominatim
+from . import settings
+from . import utils
+from ._errors import InsufficientResponseError
+
+
+def geocode(query: str) -> tuple[float, float]:
+    """
+    Geocode place names or addresses to `(lat, lon)` with the Nominatim API.
+
+    This geocodes the query via the Nominatim "search" endpoint.
+
+    Parameters
+    ----------
+    query
+        The query string to geocode.
+
+    Returns
+    -------
+    point
+        The `(lat, lon)` coordinates returned by the geocoder.
+    """
+    # define the parameters
+    params: OrderedDict[str, int | str] = OrderedDict()
+    params["format"] = "json"
+    params["limit"] = 1
+    params["dedupe"] = 0  # prevent deduping to get precise number of results
+    params["q"] = query
+    response_json = _nominatim._nominatim_request(params=params)
+
+    # if results were returned, parse lat and lon out of the result
+    if response_json and "lat" in response_json[0] and "lon" in response_json[0]:
+        lat = float(response_json[0]["lat"])
+        lon = float(response_json[0]["lon"])
+        point = (lat, lon)
+
+        msg = f"Geocoded {query!r} to {point}"
+        utils.log(msg, level=lg.INFO)
+        return point
+
+    # otherwise we got no results back
+    msg = f"Nominatim could not geocode query {query!r}."
+    raise InsufficientResponseError(msg)
+
+
+def geocode_to_gdf(
+    query: str | dict[str, str] | list[str | dict[str, str]],
+    *,
+    which_result: int | None | list[int | None] = None,
+    by_osmid: bool = False,
+) -> gpd.GeoDataFrame:
+    """
+    Retrieve OSM elements by place name or OSM ID with the Nominatim API.
+
+    If searching by place name, the `query` argument can be a string or
+    structured dict, or a list of such strings/dicts to send to the geocoder.
+    This uses the Nominatim "search" endpoint to geocode the place name to the
+    best-matching OSM element, then returns that element and its attribute
+    data.
+
+    You can instead query by OSM ID by passing `by_osmid=True`. This uses the
+    Nominatim "lookup" endpoint to retrieve the OSM element with that ID. In
+    this case, the function treats the `query` argument as an OSM ID (or list
+    of OSM IDs), which must be prepended with their types: node (N), way (W),
+    or relation (R) in accordance with the Nominatim API format. For example,
+    `query=["R2192363", "N240109189", "W427818536"]`.
+
+    If `query` is a list, then `which_result` must be either an int or a list
+    with the same length as `query`. The queries you provide must be
+    resolvable to elements in the Nominatim database. The resulting
+    GeoDataFrame's geometry column contains place boundaries if they exist.
+
+    Parameters
+    ----------
+    query
+        The query string(s) or structured dict(s) to geocode.
+    which_result
+        Which search result to return. If None, auto-select the first
+        (Multi)Polygon or raise an error if OSM doesn't return one. To get
+        the top match (sorted by importance) regardless of geometry type, set
+        `which_result=1`. Ignored if `by_osmid=True`.
+    by_osmid
+        If True, treat query as an OSM ID lookup rather than text search.
+
+    Returns
+    -------
+    gdf
+        GeoDataFrame with one row for each query result.
+    """
+    if isinstance(query, list):
+        # if query is a list of queries but which_result is int/None, then
+        # turn which_result into a list with same length as query list
+        q_list = query
+        wr_list = which_result if isinstance(which_result, list) else [which_result] * len(query)
+    else:
+        # if query is not already a list, turn it into one
+        # if which_result was a list, take 0th element, otherwise make it list
+        q_list = [query]
+        wr_list = [which_result[0]] if isinstance(which_result, list) else [which_result]
+
+    # ensure same length
+    if len(q_list) != len(wr_list):  # pragma: no cover
+        msg = "`which_result` length must equal `query` length."
+        raise ValueError(msg)
+
+    # geocode each query, concat as GeoDataFrame rows, then set the CRS
+    results = (
+        _geocode_query_to_gdf(q, wr, by_osmid) for q, wr in zip(q_list, wr_list, strict=True)
+    )
+    gdf = pd.concat(results, ignore_index=True).set_crs(settings.default_crs)
+
+    msg = f"Created GeoDataFrame with {len(gdf)} rows from {len(q_list)} queries"
+    utils.log(msg, level=lg.INFO)
+    return gdf
+
+
+def _geocode_query_to_gdf(
+    query: str | dict[str, str],
+    which_result: int | None,
+    by_osmid: bool,  # noqa: FBT001
+) -> gpd.GeoDataFrame:
+    """
+    Geocode a single place query to a GeoDataFrame.
+
+    Parameters
+    ----------
+    query
+        Query string or structured dict to geocode.
+    which_result
+        Which search result to return. If None, auto-select the first
+        (Multi)Polygon or raise an error if OSM doesn't return one. To get
+        the top match regardless of geometry type, set `which_result=1`.
+        Ignored if `by_osmid=True`.
+    by_osmid
+        If True, treat query as an OSM ID lookup rather than text search.
+
+    Returns
+    -------
+    gdf
+        GeoDataFrame with one row containing the geocoding result.
+    """
+    limit = 50 if which_result is None else which_result
+    results = _nominatim._download_nominatim_element(query, by_osmid=by_osmid, limit=limit)
+
+    # ensure geocoder results are sorted from most to least important
+    results = sorted(results, key=lambda x: x["importance"], reverse=True)
+
+    # choose the right result from the JSON response
+    if len(results) == 0:
+        # if no results were returned, raise error
+        msg = f"Nominatim geocoder returned 0 results for query {query!r}."
+        raise InsufficientResponseError(msg)
+
+    if by_osmid:
+        # if searching by OSM ID, always take the first (ie, only) result
+        result = results[0]
+
+    elif which_result is None:
+        # else, if which_result=None, auto-select the first (Multi)Polygon
+        try:
+            result = _get_first_polygon(results)
+        except TypeError as e:
+            msg = f"Nominatim did not geocode query {query!r} to a geometry of type (Multi)Polygon."
+            raise TypeError(msg) from e
+
+    elif len(results) >= which_result:
+        # else, if we got at least which_result results, choose that one
+        result = results[which_result - 1]
+
+    else:  # pragma: no cover
+        # else, we got fewer results than which_result, raise error
+        msg = f"Nominatim returned {len(results)} result(s) but `which_result={which_result}`."
+        raise InsufficientResponseError(msg)
+
+    # if we got a non (Multi)Polygon geometry type (like a point), log warning
+    geom_type = result["geojson"]["type"]
+    if geom_type not in {"Polygon", "MultiPolygon"}:
+        msg = f"Nominatim geocoder returned a {geom_type} as the geometry for query {query!r}"
+        utils.log(msg, level=lg.WARNING)
+
+    # build the GeoJSON feature from the chosen result
+    bottom, top, left, right = result["boundingbox"]
+    feature = {
+        "type": "Feature",
+        "geometry": result["geojson"],
+        "properties": {
+            "bbox_west": left,
+            "bbox_south": bottom,
+            "bbox_east": right,
+            "bbox_north": top,
+        },
+    }
+
+    # add the other attributes we retrieved
+    for attr in result:
+        if attr not in {"address", "boundingbox", "geojson", "icon", "licence"}:
+            feature["properties"][attr] = result[attr]
+
+    # create and return the GeoDataFrame
+    gdf = gpd.GeoDataFrame.from_features([feature])
+    cols = ["lat", "lon", "bbox_north", "bbox_south", "bbox_east", "bbox_west"]
+    gdf[cols] = gdf[cols].astype(float)
+    return gdf
+
+
+def _get_first_polygon(results: list[dict[str, Any]]) -> dict[str, Any]:
+    """
+    Choose first result of geometry type (Multi)Polygon from list of results.
+
+    Parameters
+    ----------
+    results
+        Results from the Nominatim API.
+
+    Returns
+    -------
+    result
+        The chosen result.
+    """
+    polygon_types = {"Polygon", "MultiPolygon"}
+
+    for result in results:
+        if "geojson" in result and result["geojson"]["type"] in polygon_types:
+            return result
+
+    # if we never found a polygon, raise an error
+    raise TypeError

osmnx/source/osmnx/graph.py

@@ -0,0 +1,863 @@
+"""
+Download and create graphs from OpenStreetMap data.
+
+Refer to the Getting Started guide for usage limitations.
+"""
+
+from __future__ import annotations
+
+import logging as lg
+from collections.abc import Iterable
+from importlib.metadata import version as metadata_version
+from itertools import groupby
+from itertools import pairwise
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import Any
+
+import networkx as nx
+from shapely import MultiPolygon
+from shapely import Polygon
+
+from . import _osm_xml
+from . import _overpass
+from . import distance
+from . import geocoder
+from . import projection
+from . import settings
+from . import simplification
+from . import stats
+from . import truncate
+from . import utils
+from . import utils_geo
+from ._errors import CacheOnlyInterruptError
+from ._errors import InsufficientResponseError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+def graph_from_bbox(
+    bbox: tuple[float, float, float, float],
+    *,
+    network_type: str = "all",
+    simplify: bool = True,
+    retain_all: bool = False,
+    truncate_by_edge: bool = False,
+    custom_filter: str | list[str] | None = None,
+) -> nx.MultiDiGraph:
+    """
+    Download and create a graph within a lat-lon bounding box.
+
+    This function uses filters to query the Overpass API: you can either
+    specify a pre-defined `network_type` or provide your own `custom_filter`
+    with Overpass QL.
+
+    Use the `settings` module's `useful_tags_node` and `useful_tags_way`
+    settings to configure which OSM node/way tags are added as graph node/edge
+    attributes. If you want a fully bidirectional network, ensure your
+    `network_type` is in `settings.bidirectional_network_types` before
+    creating your graph. You can also use the `settings` module to retrieve a
+    snapshot of historical OSM data as of a certain date, or to configure the
+    Overpass server timeout, memory allocation, and other customizations.
+
+    Parameters
+    ----------
+    bbox
+        Bounding box as `(left, bottom, right, top)`. Coordinates should be in
+        unprojected latitude-longitude degrees (EPSG:4326).
+    network_type
+        {"all", "all_public", "bike", "drive", "drive_service", "walk"}
+        What type of street network to retrieve if `custom_filter` is None.
+    simplify
+        If True, simplify graph topology via the `simplify_graph` function.
+    retain_all
+        If True, return the entire graph even if it is not connected. If
+        False, retain only the largest weakly connected component.
+    truncate_by_edge
+        If True, retain nodes the outside bounding box if at least one of
+        the node's neighbors lies within the bounding box.
+    custom_filter
+        A custom ways filter to be used instead of the `network_type` presets,
+        e.g. `'["power"~"line"]' or '["highway"~"motorway|trunk"]'`. If `str`,
+        the intersection of keys/values will be used, e.g., `'[maxspeed=50][lanes=2]'`
+        will return all ways having both maxspeed of 50 and two lanes. If
+        `list`, the union of the `list` items will be used, e.g.,
+        `['[maxspeed=50]', '[lanes=2]']` will return all ways having either
+        maximum speed of 50 or two lanes. Also pass in a `network_type` that
+        is in `settings.bidirectional_network_types` if you want the graph to
+        be fully bidirectional.
+
+    Returns
+    -------
+    G
+        The resulting MultiDiGraph.
+
+    Notes
+    -----
+    Very large query areas use the `utils_geo._consolidate_subdivide_geometry`
+    function to automatically make multiple requests: see that function's
+    documentation for caveats.
+    """
+    # convert bounding box to a polygon
+    polygon = utils_geo.bbox_to_poly(bbox)
+
+    # create graph using this polygon geometry
+    G = graph_from_polygon(
+        polygon,
+        network_type=network_type,
+        simplify=simplify,
+        retain_all=retain_all,
+        truncate_by_edge=truncate_by_edge,
+        custom_filter=custom_filter,
+    )
+
+    msg = f"graph_from_bbox returned graph with {len(G):,} nodes and {len(G.edges):,} edges"
+    utils.log(msg, level=lg.INFO)
+    return G
+
+
+def graph_from_point(
+    center_point: tuple[float, float],
+    dist: float,
+    *,
+    dist_type: str = "bbox",
+    network_type: str = "all",
+    simplify: bool = True,
+    retain_all: bool = False,
+    truncate_by_edge: bool = False,
+    custom_filter: str | list[str] | None = None,
+) -> nx.MultiDiGraph:
+    """
+    Download and create a graph within some distance of a lat-lon point.
+
+    This function uses filters to query the Overpass API: you can either
+    specify a pre-defined `network_type` or provide your own `custom_filter`
+    with Overpass QL.
+
+    Use the `settings` module's `useful_tags_node` and `useful_tags_way`
+    settings to configure which OSM node/way tags are added as graph node/edge
+    attributes. If you want a fully bidirectional network, ensure your
+    `network_type` is in `settings.bidirectional_network_types` before
+    creating your graph. You can also use the `settings` module to retrieve a
+    snapshot of historical OSM data as of a certain date, or to configure the
+    Overpass server timeout, memory allocation, and other customizations.
+
+    Parameters
+    ----------
+    center_point
+        The `(lat, lon)` center point around which to construct the graph.
+        Coordinates should be in unprojected latitude-longitude degrees
+        (EPSG:4326).
+    dist
+        Retain only those nodes within this many meters of `center_point`,
+        measuring distance according to `dist_type`.
+    dist_type
+        {"bbox", "network"}
+        If "bbox", retain only those nodes within a bounding box of `dist`
+        length/width. If "network", retain only those nodes within `dist`
+        network distance of the nearest node to `center_point`.
+    network_type
+        {"all", "all_public", "bike", "drive", "drive_service", "walk"}
+        What type of street network to retrieve if `custom_filter` is None.
+    simplify
+        If True, simplify graph topology with the `simplify_graph` function.
+    retain_all
+        If True, return the entire graph even if it is not connected. If
+        False, retain only the largest weakly connected component.
+    truncate_by_edge
+        If True, retain nodes the outside bounding box if at least one of
+        the node's neighbors lies within the bounding box.
+    custom_filter
+        A custom ways filter to be used instead of the `network_type` presets,
+        e.g. `'["power"~"line"]' or '["highway"~"motorway|trunk"]'`. If `str`,
+        the intersection of keys/values will be used, e.g., `'[maxspeed=50][lanes=2]'`
+        will return all ways having both maxspeed of 50 and two lanes. If
+        `list`, the union of the `list` items will be used, e.g.,
+        `['[maxspeed=50]', '[lanes=2]']` will return all ways having either
+        maximum speed of 50 or two lanes. Also pass in a `network_type` that
+        is in `settings.bidirectional_network_types` if you want the graph to
+        be fully bidirectional.
+
+    Returns
+    -------
+    G
+        The resulting MultiDiGraph.
+
+    Notes
+    -----
+    Very large query areas use the `utils_geo._consolidate_subdivide_geometry`
+    function to automatically make multiple requests: see that function's
+    documentation for caveats.
+    """
+    if dist_type not in {"bbox", "network"}:  # pragma: no cover
+        msg = "`dist_type` must be 'bbox' or 'network'."
+        raise ValueError(msg)
+
+    # create bounding box from center point and distance in each direction
+    bbox = utils_geo.bbox_from_point(center_point, dist)
+
+    # create a graph from the bounding box
+    G = graph_from_bbox(
+        bbox,
+        network_type=network_type,
+        simplify=simplify,
+        retain_all=retain_all,
+        truncate_by_edge=truncate_by_edge,
+        custom_filter=custom_filter,
+    )
+
+    if dist_type == "network":
+        # find node nearest to center then truncate graph by dist from it
+        node = distance.nearest_nodes(G, X=center_point[1], Y=center_point[0])
+        G = truncate.truncate_graph_dist(G, node, dist)
+
+    msg = f"graph_from_point returned graph with {len(G):,} nodes and {len(G.edges):,} edges"
+    utils.log(msg, level=lg.INFO)
+    return G
+
+
+def graph_from_address(
+    address: str,
+    dist: float,
+    *,
+    dist_type: str = "bbox",
+    network_type: str = "all",
+    simplify: bool = True,
+    retain_all: bool = False,
+    truncate_by_edge: bool = False,
+    custom_filter: str | list[str] | None = None,
+) -> nx.MultiDiGraph:
+    """
+    Download and create a graph within some distance of an address.
+
+    This function uses filters to query the Overpass API: you can either
+    specify a pre-defined `network_type` or provide your own `custom_filter`
+    with Overpass QL.
+
+    Use the `settings` module's `useful_tags_node` and `useful_tags_way`
+    settings to configure which OSM node/way tags are added as graph node/edge
+    attributes. If you want a fully bidirectional network, ensure your
+    `network_type` is in `settings.bidirectional_network_types` before
+    creating your graph. You can also use the `settings` module to retrieve a
+    snapshot of historical OSM data as of a certain date, or to configure the
+    Overpass server timeout, memory allocation, and other customizations.
+
+    Parameters
+    ----------
+    address
+        The address to geocode and use as the central point around which to
+        construct the graph.
+    dist
+        Retain only those nodes within this many meters of `center_point`,
+        measuring distance according to `dist_type`.
+    dist_type
+        {"network", "bbox"}
+        If "bbox", retain only those nodes within a bounding box of `dist`. If
+        "network", retain only those nodes within `dist` network distance from
+        the centermost node.
+    network_type
+        {"all", "all_public", "bike", "drive", "drive_service", "walk"}
+        What type of street network to retrieve if `custom_filter` is None.
+    simplify
+        If True, simplify graph topology with the `simplify_graph` function.
+    retain_all
+        If True, return the entire graph even if it is not connected. If
+        False, retain only the largest weakly connected component.
+    truncate_by_edge
+        If True, retain nodes the outside bounding box if at least one of
+        the node's neighbors lies within the bounding box.
+    custom_filter
+        A custom ways filter to be used instead of the `network_type` presets,
+        e.g. `'["power"~"line"]' or '["highway"~"motorway|trunk"]'`. If `str`,
+        the intersection of keys/values will be used, e.g., `'[maxspeed=50][lanes=2]'`
+        will return all ways having both maxspeed of 50 and two lanes. If
+        `list`, the union of the `list` items will be used, e.g.,
+        `['[maxspeed=50]', '[lanes=2]']` will return all ways having either
+        maximum speed of 50 or two lanes. Also pass in a `network_type` that
+        is in `settings.bidirectional_network_types` if you want the graph to
+        be fully bidirectional.
+
+    Returns
+    -------
+    G
+        The resulting MultiDiGraph.
+
+    Notes
+    -----
+    Very large query areas use the `utils_geo._consolidate_subdivide_geometry`
+    function to automatically make multiple requests: see that function's
+    documentation for caveats.
+    """
+    # geocode the address string to a (lat, lon) point
+    point = geocoder.geocode(address)
+
+    # then create a graph from this point
+    G = graph_from_point(
+        point,
+        dist,
+        dist_type=dist_type,
+        network_type=network_type,
+        simplify=simplify,
+        retain_all=retain_all,
+        truncate_by_edge=truncate_by_edge,
+        custom_filter=custom_filter,
+    )
+
+    msg = f"graph_from_address returned graph with {len(G):,} nodes and {len(G.edges):,} edges"
+    utils.log(msg, level=lg.INFO)
+    return G
+
+
+def graph_from_place(
+    query: str | dict[str, str] | list[str | dict[str, str]],
+    *,
+    network_type: str = "all",
+    simplify: bool = True,
+    retain_all: bool = False,
+    truncate_by_edge: bool = False,
+    which_result: int | None | list[int | None] = None,
+    custom_filter: str | list[str] | None = None,
+) -> nx.MultiDiGraph:
+    """
+    Download and create a graph within the boundaries of some place(s).
+
+    The query must be geocodable and OSM must have polygon boundaries for the
+    geocode result. If OSM does not have a polygon for this place, you can
+    instead get its street network using the `graph_from_address` function,
+    which geocodes the place name to a point and gets the network within some
+    distance of that point.
+
+    If OSM does have polygon boundaries for this place but you're not finding
+    it, try to vary the query string, pass in a structured query dict, or vary
+    the `which_result` argument to use a different geocode result. If you know
+    the OSM ID of the place, you can retrieve its boundary polygon using the
+    `geocode_to_gdf` function, then pass it to the `features_from_polygon`
+    function.
+
+    This function uses filters to query the Overpass API: you can either
+    specify a pre-defined `network_type` or provide your own `custom_filter`
+    with Overpass QL.
+
+    Use the `settings` module's `useful_tags_node` and `useful_tags_way`
+    settings to configure which OSM node/way tags are added as graph node/edge
+    attributes. If you want a fully bidirectional network, ensure your
+    `network_type` is in `settings.bidirectional_network_types` before
+    creating your graph. You can also use the `settings` module to retrieve a
+    snapshot of historical OSM data as of a certain date, or to configure the
+    Overpass server timeout, memory allocation, and other customizations.
+
+    Parameters
+    ----------
+    query
+        The query or queries to geocode to retrieve place boundary polygon(s).
+    network_type
+        {"all", "all_public", "bike", "drive", "drive_service", "walk"}
+        What type of street network to retrieve if `custom_filter` is None.
+    simplify
+        If True, simplify graph topology with the `simplify_graph` function.
+    retain_all
+        If True, return the entire graph even if it is not connected. If
+        False, retain only the largest weakly connected component.
+    truncate_by_edge
+        If True, retain nodes outside the place boundary polygon(s) if at
+        least one of the node's neighbors lies within the polygon(s).
+    which_result
+        Which geocoding result to use. if None, auto-select the first
+        (Multi)Polygon or raise an error if OSM doesn't return one.
+    custom_filter
+        A custom ways filter to be used instead of the `network_type` presets,
+        e.g. `'["power"~"line"]' or '["highway"~"motorway|trunk"]'`. If `str`,
+        the intersection of keys/values will be used, e.g., `'[maxspeed=50][lanes=2]'`
+        will return all ways having both maxspeed of 50 and two lanes. If
+        `list`, the union of the `list` items will be used, e.g.,
+        `['[maxspeed=50]', '[lanes=2]']` will return all ways having either
+        maximum speed of 50 or two lanes. Also pass in a `network_type` that
+        is in `settings.bidirectional_network_types` if you want the graph to
+        be fully bidirectional.
+
+    Returns
+    -------
+    G
+        The resulting MultiDiGraph.
+
+    Notes
+    -----
+    Very large query areas use the `utils_geo._consolidate_subdivide_geometry`
+    function to automatically make multiple requests: see that function's
+    documentation for caveats.
+    """
+    # extract the geometry from the GeoDataFrame to use in query
+    polygon = geocoder.geocode_to_gdf(query, which_result=which_result).union_all()
+    msg = "Constructed place geometry polygon(s) to query Overpass"
+    utils.log(msg, level=lg.INFO)
+
+    # create graph using this polygon(s) geometry
+    G = graph_from_polygon(
+        polygon,
+        network_type=network_type,
+        simplify=simplify,
+        retain_all=retain_all,
+        truncate_by_edge=truncate_by_edge,
+        custom_filter=custom_filter,
+    )
+
+    msg = f"graph_from_place returned graph with {len(G):,} nodes and {len(G.edges):,} edges"
+    utils.log(msg, level=lg.INFO)
+    return G
+
+
+def graph_from_polygon(
+    polygon: Polygon | MultiPolygon,
+    *,
+    network_type: str = "all",
+    simplify: bool = True,
+    retain_all: bool = False,
+    truncate_by_edge: bool = False,
+    custom_filter: str | list[str] | None = None,
+) -> nx.MultiDiGraph:
+    """
+    Download and create a graph within the boundaries of a (Multi)Polygon.
+
+    This function uses filters to query the Overpass API: you can either
+    specify a pre-defined `network_type` or provide your own `custom_filter`
+    with Overpass QL.
+
+    Use the `settings` module's `useful_tags_node` and `useful_tags_way`
+    settings to configure which OSM node/way tags are added as graph node/edge
+    attributes. If you want a fully bidirectional network, ensure your
+    `network_type` is in `settings.bidirectional_network_types` before
+    creating your graph. You can also use the `settings` module to retrieve a
+    snapshot of historical OSM data as of a certain date, or to configure the
+    Overpass server timeout, memory allocation, and other customizations.
+
+    Parameters
+    ----------
+    polygon
+        The geometry within which to construct the graph. Coordinates should
+        be in unprojected latitude-longitude degrees (EPSG:4326).
+    network_type
+        {"all", "all_public", "bike", "drive", "drive_service", "walk"}
+        What type of street network to retrieve if `custom_filter` is None.
+    simplify
+        If True, simplify graph topology with the `simplify_graph` function.
+    retain_all
+        If True, return the entire graph even if it is not connected. If
+        False, retain only the largest weakly connected component.
+    truncate_by_edge
+        If True, retain nodes outside `polygon` if at least one of the node's
+        neighbors lies within `polygon`.
+    custom_filter
+        A custom ways filter to be used instead of the `network_type` presets,
+        e.g. `'["power"~"line"]' or '["highway"~"motorway|trunk"]'`. If `str`,
+        the intersection of keys/values will be used, e.g., `'[maxspeed=50][lanes=2]'`
+        will return all ways having both maxspeed of 50 and two lanes. If
+        `list`, the union of the `list` items will be used, e.g.,
+        `['[maxspeed=50]', '[lanes=2]']` will return all ways having either
+        maximum speed of 50 or two lanes. Also pass in a `network_type` that
+        is in `settings.bidirectional_network_types` if you want the graph to
+        be fully bidirectional.
+
+    Returns
+    -------
+    G
+        The resulting MultiDiGraph.
+
+    Notes
+    -----
+    Very large query areas use the `utils_geo._consolidate_subdivide_geometry`
+    function to automatically make multiple requests: see that function's
+    documentation for caveats.
+    """
+    # verify that the geometry is valid and is a shapely Polygon/MultiPolygon
+    # before proceeding
+    if not polygon.is_valid:  # pragma: no cover
+        msg = "The geometry of `polygon` is invalid."
+        raise ValueError(msg)
+    if not isinstance(polygon, (Polygon, MultiPolygon)):  # pragma: no cover
+        msg = (
+            "Geometry must be a shapely Polygon or MultiPolygon. If you "
+            "requested graph from place name, make sure your query resolves "
+            "to a Polygon or MultiPolygon, and not some other geometry, like "
+            "a Point. See OSMnx documentation for details."
+        )
+        raise TypeError(msg)
+
+    # create a new buffered polygon 0.5km around the desired one
+    poly_proj, crs_utm = projection.project_geometry(polygon)
+    poly_proj_buff = poly_proj.buffer(500)
+    poly_buff, _ = projection.project_geometry(poly_proj_buff, crs=crs_utm, to_latlong=True)
+
+    # download the network data from OSM within buffered polygon
+    response_jsons = _overpass._download_overpass_network(poly_buff, network_type, custom_filter)
+
+    # create buffered graph from the downloaded data
+    bidirectional = network_type in settings.bidirectional_network_types
+    G_buff = _create_graph(response_jsons, bidirectional)
+
+    # truncate buffered graph to the buffered polygon and retain_all for
+    # now. needed because overpass returns entire ways that also include
+    # nodes outside the poly if the way (that is, a way with a single OSM
+    # ID) has a node inside the poly at some point.
+    G_buff = truncate.truncate_graph_polygon(G_buff, poly_buff, truncate_by_edge=truncate_by_edge)
+
+    # keep only the largest weakly connected component if retain_all is False
+    if not retain_all:
+        G_buff = truncate.largest_component(G_buff, strongly=False)
+
+    # simplify the graph topology
+    if simplify:
+        G_buff = simplification.simplify_graph(G_buff)
+
+    # truncate graph by original polygon to return graph within polygon
+    # caller wants. don't simplify again: this allows us to retain
+    # intersections along the street that may now only connect 2 street
+    # segments in the network, but in reality also connect to an
+    # intersection just outside the polygon
+    G = truncate.truncate_graph_polygon(G_buff, polygon, truncate_by_edge=truncate_by_edge)
+
+    # keep only the largest weakly connected component if retain_all is False
+    # we're doing this again in case the last truncate disconnected anything
+    # on the periphery
+    if not retain_all:
+        G = truncate.largest_component(G, strongly=False)
+
+    # count how many physical streets in buffered graph connect to each
+    # intersection in un-buffered graph, to retain true counts for each
+    # intersection, even if some of its neighbors are outside the polygon
+    spn = stats.count_streets_per_node(G_buff, nodes=G.nodes)
+    nx.set_node_attributes(G, values=spn, name="street_count")
+
+    msg = f"graph_from_polygon returned graph with {len(G):,} nodes and {len(G.edges):,} edges"
+    utils.log(msg, level=lg.INFO)
+    return G
+
+
+def graph_from_xml(
+    filepath: str | Path,
+    *,
+    bidirectional: bool = False,
+    simplify: bool = True,
+    retain_all: bool = False,
+    encoding: str = "utf-8",
+) -> nx.MultiDiGraph:
+    """
+    Create a graph from data in an OSM XML file.
+
+    Do not load an XML file previously generated by OSMnx: this use case is
+    not supported and may not behave as expected. To save/load graphs to/from
+    disk for later use in OSMnx, use the `io.save_graphml` and
+    `io.load_graphml` functions instead.
+
+    Use the `settings` module's `useful_tags_node` and `useful_tags_way`
+    settings to configure which OSM node/way tags are added as graph node/edge
+    attributes.
+
+    Parameters
+    ----------
+    filepath
+        Path to file containing OSM XML data.
+    bidirectional
+        If True, create bidirectional edges for one-way streets.
+    simplify
+        If True, simplify graph topology with the `simplify_graph` function.
+    retain_all
+        If True, return the entire graph even if it is not connected. If
+        False, retain only the largest weakly connected component.
+    encoding
+        The OSM XML file's character encoding.
+
+    Returns
+    -------
+    G
+        The resulting MultiDiGraph.
+    """
+    # transmogrify file of OSM XML data into JSON
+    response_jsons = [_osm_xml._overpass_json_from_xml(Path(filepath), encoding)]
+
+    # create graph using this response JSON
+    G = _create_graph(response_jsons, bidirectional)
+
+    # keep only the largest weakly connected component if retain_all is False
+    if not retain_all:
+        G = truncate.largest_component(G, strongly=False)
+
+    # simplify the graph topology as the last step
+    if simplify:
+        G = simplification.simplify_graph(G)
+
+    msg = f"graph_from_xml returned graph with {len(G):,} nodes and {len(G.edges):,} edges"
+    utils.log(msg, level=lg.INFO)
+    return G
+
+
+def _create_graph(
+    response_jsons: Iterable[dict[str, Any]],
+    bidirectional: bool,  # noqa: FBT001
+) -> nx.MultiDiGraph:
+    """
+    Create a NetworkX MultiDiGraph from Overpass API responses.
+
+    Adds length attributes in meters (great-circle distance between endpoints)
+    to all of the graph's (pre-simplified, straight-line) edges via the
+    `distance.add_edge_lengths` function.
+
+    Parameters
+    ----------
+    response_jsons
+        Iterable of JSON responses from the Overpass API.
+    bidirectional
+        If True, create bidirectional edges for one-way streets.
+
+    Returns
+    -------
+    G
+        The resulting MultiDiGraph.
+    """
+    # each dict's keys are OSM IDs and values are dicts of attributes
+    nodes: dict[int, dict[str, Any]] = {}
+    paths: dict[int, dict[str, Any]] = {}
+
+    # consume response_jsons generator to download data from server. if
+    # cache_only_mode, just consume response_jsons then continue next loop.
+    # otherwise, extract nodes and paths from the downloaded OSM data.
+    response_count = 0
+    for response_json in response_jsons:
+        response_count += 1
+        if not settings.cache_only_mode:
+            nodes_temp, paths_temp = _parse_nodes_paths(response_json)
+            nodes.update(nodes_temp)
+            paths.update(paths_temp)
+
+    msg = f"Retrieved all data from API in {response_count} request(s)"
+    utils.log(msg, level=lg.INFO)
+    if settings.cache_only_mode:  # pragma: no cover
+        # after consuming all response_jsons in loop, raise exception to catch
+        msg = "Interrupted because `settings.cache_only_mode=True`."
+        raise CacheOnlyInterruptError(msg)
+
+    # ensure we got some node/way data back from the server request(s)
+    if (len(nodes) == 0) and (len(paths) == 0):  # pragma: no cover
+        msg = "No data elements in server response. Check query location/filters and log."
+        raise InsufficientResponseError(msg)
+
+    # create the MultiDiGraph and set its graph-level attributes
+    metadata = {
+        "created_date": utils.ts(),
+        "created_with": f"OSMnx {metadata_version('osmnx')}",
+        "crs": settings.default_crs,
+    }
+    G = nx.MultiDiGraph(**metadata)
+
+    # add each OSM node and way (a path of edges) to the graph
+    msg = f"Creating graph from {len(nodes):,} OSM nodes and {len(paths):,} OSM ways..."
+    utils.log(msg, level=lg.INFO)
+    G.add_nodes_from(nodes.items())
+    _add_paths(G, paths.values(), bidirectional)
+
+    msg = f"Created graph with {len(G):,} nodes and {len(G.edges):,} edges"
+    utils.log(msg, level=lg.INFO)
+
+    # add length (great-circle distance between nodes) attribute to each edge
+    if len(G.edges) > 0:
+        G = distance.add_edge_lengths(G)
+
+    return G
+
+
+def _convert_node(element: dict[str, Any]) -> dict[str, Any]:
+    """
+    Convert an OSM node element into the format for a NetworkX node.
+
+    Parameters
+    ----------
+    element
+        OSM element of type "node".
+
+    Returns
+    -------
+    node
+        The converted node.
+    """
+    node = {"y": element["lat"], "x": element["lon"]}
+    if "tags" in element:
+        for useful_tag in settings.useful_tags_node:
+            if useful_tag in element["tags"]:
+                node[useful_tag] = element["tags"][useful_tag]
+    return node
+
+
+def _convert_path(element: dict[str, Any]) -> dict[str, Any]:
+    """
+    Convert an OSM way element into the format for a NetworkX path.
+
+    Parameters
+    ----------
+    element
+        OSM element of type "way".
+
+    Returns
+    -------
+    path
+        The converted path.
+    """
+    path = {"osmid": element["id"]}
+
+    # remove any consecutive duplicate elements in the list of nodes
+    path["nodes"] = [group[0] for group in groupby(element["nodes"])]
+
+    if "tags" in element:
+        for useful_tag in settings.useful_tags_way:
+            if useful_tag in element["tags"]:
+                path[useful_tag] = element["tags"][useful_tag]
+    return path
+
+
+def _parse_nodes_paths(
+    response_json: dict[str, Any],
+) -> tuple[dict[int, dict[str, Any]], dict[int, dict[str, Any]]]:
+    """
+    Construct dicts of nodes and paths from an Overpass response.
+
+    Parameters
+    ----------
+    response_json
+        JSON response from the Overpass API.
+
+    Returns
+    -------
+    nodes, paths
+        Each dict's keys are OSM IDs and values are dicts of attributes.
+    """
+    nodes = {}
+    paths = {}
+    for element in response_json["elements"]:
+        if element["type"] == "node":
+            nodes[element["id"]] = _convert_node(element)
+        elif element["type"] == "way":
+            paths[element["id"]] = _convert_path(element)
+
+    return nodes, paths
+
+
+def _is_path_one_way(attrs: dict[str, Any], bidirectional: bool, oneway_values: set[str]) -> bool:  # noqa: FBT001
+    """
+    Determine if a path of nodes allows travel in only one direction.
+
+    Parameters
+    ----------
+    attrs
+        A path's `tag:value` attribute data.
+    bidirectional
+        Whether this is a bidirectional network type.
+    oneway_values
+        The values OSM uses in its "oneway" tag to denote True.
+
+    Returns
+    -------
+    is_one_way
+        True if path allows travel in only one direction, otherwise False.
+    """
+    # rule 1
+    if settings.all_oneway:
+        # if globally configured to set every edge one-way, then it's one-way
+        return True
+
+    # rule 2
+    if bidirectional:
+        # if this is a bidirectional network type, then nothing in it is
+        # considered one-way. eg, if this is a walking network, this may very
+        # well be a one-way street (as cars/bikes go), but in a walking-only
+        # network it is a bidirectional edge (you can walk both directions on
+        # a one-way street). so we will add this path (in both directions) to
+        # the graph and set its oneway attribute to False.
+        return False
+
+    # rule 3
+    if "oneway" in attrs and attrs["oneway"] in oneway_values:
+        # if this path is tagged as one-way and if it is not a bidirectional
+        # network type then we'll add the path in one direction only
+        return True
+
+    # rule 4
+    if "junction" in attrs and attrs["junction"] == "roundabout":  # noqa: SIM103
+        # roundabouts are also one-way but are not explicitly tagged as such
+        return True
+
+    # otherwise, if no rule passed then this path is not tagged as a one-way
+    return False
+
+
+def _is_path_reversed(attrs: dict[str, Any], reversed_values: set[str]) -> bool:
+    """
+    Determine if the order of nodes in a path should be reversed.
+
+    Parameters
+    ----------
+    attrs
+        A path's `tag:value` attribute data.
+    reversed_values
+        The values OSM uses in its 'oneway' tag to denote travel can only
+        occur in the opposite direction of the node order.
+
+    Returns
+    -------
+    is_reversed
+        True if nodes' order should be reversed, otherwise False.
+    """
+    return "oneway" in attrs and attrs["oneway"] in reversed_values
+
+
+def _add_paths(
+    G: nx.MultiDiGraph,
+    paths: Iterable[dict[str, Any]],
+    bidirectional: bool,  # noqa: FBT001
+) -> None:
+    """
+    Add OSM paths to the graph as edges.
+
+    Parameters
+    ----------
+    G
+        The graph to add paths to.
+    paths
+        Iterable of paths' `tag:value` attribute data dicts.
+    bidirectional
+        If True, create bidirectional edges for one-way streets.
+    """
+    # the values OSM uses in its 'oneway' tag to denote True, and to denote
+    # travel can only occur in the opposite direction of the node order. see:
+    # https://wiki.openstreetmap.org/wiki/Key:oneway
+    # https://www.geofabrik.de/de/data/geofabrik-osm-gis-standard-0.7.pdf
+    oneway_values = {"yes", "true", "1", "-1", "reverse", "T", "F"}
+    reversed_values = {"-1", "reverse", "T"}
+
+    for path in paths:
+        # extract/remove the ordered list of nodes from this path element so
+        # we don't add it as a superfluous attribute to the edge later
+        nodes = path.pop("nodes")
+
+        # reverse the order of nodes in the path if this path is both one-way
+        # and only allows travel in the opposite direction of nodes' order
+        is_one_way = _is_path_one_way(path, bidirectional, oneway_values)
+        if is_one_way and _is_path_reversed(path, reversed_values):
+            nodes.reverse()
+
+        # set the oneway attribute, but only if when not forcing all edges to
+        # oneway with the all_oneway setting. With the all_oneway setting, you
+        # want to preserve the original OSM oneway attribute for later clarity
+        if not settings.all_oneway:
+            path["oneway"] = is_one_way
+
+        # zip path nodes to get (u, v) tuples like [(0,1), (1,2), (2,3)].
+        edges = list(pairwise(nodes))
+
+        # add all the edge tuples and give them the path's tag:value attrs
+        path["reversed"] = False
+        G.add_edges_from(edges, **path)
+
+        # if the path is NOT one-way, reverse direction of each edge and add
+        # this path going the opposite direction too
+        if not is_one_way:
+            path["reversed"] = True
+            G.add_edges_from([(v, u) for u, v in edges], **path)