osmnx package

osmnx.bearing module

Calculate graph edge bearings.

osmnx.bearing.add_edge_bearings(G, precision=1)

Add bearing attributes to all graph edges.

Calculate the compass bearing from origin node to destination node for each edge in the directed graph then add each bearing as a new edge attribute.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • precision (int) – decimal precision to round bearing

Returns

G – graph with edge bearing attributes

Return type

networkx.MultiDiGraph

osmnx.bearing.get_bearing(origin_point, destination_point)

Calculate the bearing between two lat-lng points.

Each tuple should represent (lat, lng) as decimal degrees.

Parameters
  • origin_point (tuple) – (lat, lng)

  • destination_point (tuple) – (lat, lng)

Returns

bearing – the compass bearing in decimal degrees from the origin point to the destination point

Return type

float

osmnx.boundaries module

Create GeoDataFrames of place boundaries.

osmnx.boundaries.gdf_from_place(query, which_result=1, buffer_dist=None)

Create a GeoDataFrame from a single place name query.

Geocode the query with Nominatim then turn it into a GeoDataFrame with a geometry column.

Parameters
  • query (string or dict) – query string or structured query dict to geocode/download

  • which_result (int) – max number of results to return and which to process upon receipt

  • buffer_dist (float) – distance to buffer around the place geometry, in meters

Returns

gdf

Return type

geopandas.GeoDataFrame

osmnx.boundaries.gdf_from_places(queries, which_results=None, buffer_dist=None)

Create a GeoDataFrame from a list of place name queries.

Geocode the queries with Nominatim then turn result into GeoDataFrame with a geometry column.

Parameters
  • queries (list) – list of query strings or structured query dicts to geocode/download, one at a time

  • which_results (list) – if not None, a list of max number of results to return and which to process upon receipt, for each query in queries

  • buffer_dist (float) – distance to buffer around the place geometry, in meters

Returns

gdf

Return type

geopandas.GeoDataFrame

osmnx.distance module

Functions to calculate distances and find nearest node/edge(s) to point(s).

osmnx.distance.euclidean_dist_vec(y1, x1, y2, x2)

Calculate euclidean distances.

Vectorized function to calculate the euclidean distance between two points or between arrays of points.

Parameters
  • y1 (float or np.array of float) – first y coord

  • x1 (float or np.array of float) – first x coord

  • y2 (float or np.array of float) – second y coord

  • x2 (float or np.array of float) – second x coord

Returns

dist – distance or vector of distances from (x1, y1) to (x2, y2) in graph units

Return type

float or np.array of float

osmnx.distance.get_nearest_edge(G, point, return_geom=False, return_dist=False)

Return the nearest edge to a point, by minimum euclidean distance.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • point (tuple) – the (lat, lng) or (y, x) point for which we will find the nearest edge in the graph

  • return_geom (bool) – Optionally return the geometry of the nearest edge

  • return_dist (bool) – Optionally return the distance in graph’s coordinates’ units between the point and the nearest edge

Returns

Graph edge unique identifier as a tuple of (u, v, key). Or a tuple of (u, v, key, geom) if return_geom is True. Or a tuple of (u, v, key, dist) if return_dist is True. Or a tuple of (u, v, key, geom, dist) if return_geom and return_dist are True.

Return type

tuple

osmnx.distance.get_nearest_edges(G, X, Y, method=None, dist=0.0001)

Return the graph edges nearest to a list of points.

Pass in points as separate vectors of X and Y coordinates. The ‘kdtree’ method is by far the fastest with large data sets, but only finds approximate nearest edges if working in unprojected coordinates like lat-lng (it precisely finds the nearest edge if working in projected coordinates). The ‘balltree’ method is second fastest with large data sets, but it is precise if working in unprojected coordinates like lat-lng. As a rule of thumb, if you have a small graph just use method=None. If you have a large graph with lat-lng coordinates, use method=’balltree’. If you have a large graph with projected coordinates, use method=’kdtree’. Note that if you are working in units of lat-lng, the X vector corresponds to longitude and the Y vector corresponds to latitude. The method creates equally distanced points along the edges of the network. Then, these points are used in a kdTree or BallTree search to identify which is nearest.Note that this method will not give the exact perpendicular point along the edge, but the smaller the dist parameter, the closer the solution will be.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • X (list-like) – The vector of longitudes or x’s for which we will find the nearest edge in the graph. For projected graphs, use the projected coordinates, usually in meters.

  • Y (list-like) – The vector of latitudes or y’s for which we will find the nearest edge in the graph. For projected graphs, use the projected coordinates, usually in meters.

  • method (string {None, 'kdtree', 'balltree'}) – Which method to use for finding nearest edge to each point. If None, we manually find each edge one at a time using get_nearest_edge. If ‘kdtree’ we use scipy.spatial.cKDTree for very fast euclidean search. Recommended for projected graphs. If ‘balltree’, we use sklearn.neighbors.BallTree for fast haversine search. Recommended for unprojected graphs.

  • dist (float) – spacing length along edges. Units are the same as the geom; Degrees for unprojected geometries and meters for projected geometries. The smaller the value, the more points are created.

Returns

ne – array of nearest edges represented by u and v (the IDs of the nodes they link) and key

Return type

np.array

osmnx.distance.get_nearest_node(G, point, method='haversine', return_dist=False)

Find node nearest to a point.

Return the graph node nearest to some specified (lat, lng) or (y, x) point and optionally the distance between the node and the point. This function can use either a haversine or euclidean distance calculator.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • point (tuple) – The (lat, lng) or (y, x) point for which we will find the nearest node in the graph

  • method (string {'haversine', 'euclidean'}) – Which method to use for calculating distances to find nearest node. If ‘haversine’, graph nodes’ coordinates must be in units of decimal degrees. If ‘euclidean’, graph nodes’ coordinates must be projected.

  • return_dist (bool) – Optionally also return the distance (in meters if haversine, or graph node coordinate units if euclidean) between the point and the nearest node

Returns

Nearest node ID or optionally a tuple of (node ID, dist), where dist is the distance (in meters if haversine, or graph node coordinate units if euclidean) between the point and nearest node

Return type

int or tuple of (int, float)

osmnx.distance.get_nearest_nodes(G, X, Y, method=None)

Return the graph nodes nearest to a list of points.

Pass in points as separate vectors of X and Y coordinates. The ‘kdtree’ method is by far the fastest with large data sets, but only finds approximate nearest nodes if working in unprojected coordinates like lat-lng (it precisely finds the nearest node if working in projected coordinates). The ‘balltree’ method is second fastest with large data sets but it is precise if working in unprojected coordinates like lat-lng.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • X (list-like) – The vector of longitudes or x’s for which we will find the nearest node in the graph

  • Y (list-like) – The vector of latitudes or y’s for which we will find the nearest node in the graph

  • method (string {None, 'kdtree', 'balltree'}) – Which method to use for finding nearest node to each point. If None, we manually find each node one at a time using utils.get_nearest_node and haversine. If ‘kdtree’ we use scipy.spatial.cKDTree for very fast euclidean search. If ‘balltree’, we use sklearn.neighbors.BallTree for fast haversine search.

Returns

nn – list of nearest node IDs

Return type

np.array

osmnx.distance.great_circle_vec(lat1, lng1, lat2, lng2, earth_radius=6371009)

Calculate great-circle distances.

Vectorized function to calculate the great-circle distance between two points or between vectors of points, using haversine.

Parameters
  • lat1 (float or array of float) – first lat coord

  • lng1 (float or array of float) – first lng coord

  • lat2 (float or array of float) – second lat coord

  • lng2 (float or array of float) – second lng coord

  • earth_radius (numeric) – radius of earth in units in which distance will be returned (default is meters)

Returns

dist – distance or array of distances from (lat1, lng1) to (lat2, lng2) in units of earth_radius

Return type

float or np.array of floats

osmnx.downloader module

Interact with the OSM APIs.

osmnx.downloader.nominatim_request(params, request_type='search', pause=1, error_pause=180)

Send a request to the Nominatim API via HTTP GET and return JSON response.

Parameters
  • params (dict or OrderedDict) – key-value pairs of parameters

  • request_type (string) – Type of Nominatim query. One of: search, reverse, or lookup

  • pause (int) – how long to pause before requests, in seconds

  • error_pause (int) – how long to pause in seconds before re-trying requests if error

Returns

response_json

Return type

dict

osmnx.downloader.overpass_request(data, pause=None, error_pause=None)

Send a request to the Overpass API via HTTP POST and return JSON response.

Parameters
  • data (dict or OrderedDict) – key-value pairs of parameters to post to the API

  • pause (int) – how long to pause in seconds before requests, if None, will query API status endpoint to find when next slot is available

  • error_pause (int) – how long to pause in seconds before re-trying requests if error

Returns

Return type

dict

osmnx.elevation module

Get node elevations and calculate edge grades.

osmnx.elevation.add_edge_grades(G, add_absolute=True, precision=3)

Add grade attribute to each graph edge.

Get the directed grade (ie, rise over run) for each edge in the network and add it to the edge as an attribute. Nodes must have elevation attributes to use this function.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • add_absolute (bool) – if True, also add the absolute value of the grade as an edge attribute called grade_abs

  • precision (int) – decimal precision to round grades

Returns

G – graph with edge grade (and optionally grade_abs) attributes

Return type

networkx.MultiDiGraph

osmnx.elevation.add_node_elevations(G, api_key, max_locations_per_batch=350, pause_duration=0.02, precision=3)

Add elevation (meters) attribute to each node.

Uses the google maps elevation API.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • api_key (string) – your google maps elevation API key

  • max_locations_per_batch (int) – max number of coordinate pairs to submit in each API call (if this is too high, the server will reject the request because its character limit exceeds the max)

  • pause_duration (float) – time to pause between API calls

  • precision (int) – decimal precision to round elevation

Returns

G – graph with node elevation attributes

Return type

networkx.MultiDiGraph

osmnx.folium module

Create leaflet web maps via folium.

osmnx.folium.plot_graph_folium(G, graph_map=None, popup_attribute=None, tiles='cartodbpositron', zoom=1, fit_bounds=True, edge_color='#333333', edge_width=5, edge_opacity=1, **kwargs)

Plot a graph on an interactive folium web map.

Note that anything larger than a small city can take a long time to plot and create a large web map file that is very slow to load as JavaScript.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • graph_map (folium.folium.Map or folium.FeatureGroup) – if not None, plot the graph on this preexisting folium map object

  • popup_attribute (string) – edge attribute to display in a pop-up when an edge is clicked

  • tiles (string) – name of a folium tileset

  • zoom (int) – initial zoom level for the map

  • fit_bounds (bool) – if True, fit the map to the boundaries of the route’s edges

  • edge_color (string) – color of the edge lines

  • edge_width (numeric) – width of the edge lines

  • edge_opacity (numeric) – opacity of the edge lines

  • kwargs (dict) – Extra keyword arguments passed through to folium

Returns

graph_map

Return type

folium.folium.Map

osmnx.folium.plot_route_folium(G, route, route_map=None, popup_attribute=None, tiles='cartodbpositron', zoom=1, fit_bounds=True, route_color='#cc0000', route_width=5, route_opacity=1, **kwargs)

Plot a route on an interactive folium web map.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • route (list) – the route as a list of nodes

  • route_map (folium.folium.Map) – if not None, plot the route on this preexisting folium map object

  • popup_attribute (string) – edge attribute to display in a pop-up when an edge is clicked

  • tiles (string) – name of a folium tileset

  • zoom (int) – initial zoom level for the map

  • fit_bounds (bool) – if True, fit the map to the boundaries of the route’s edges

  • route_color (string) – color of the route’s line

  • route_width (numeric) – width of the route’s line

  • route_opacity (numeric) – opacity of the route lines

  • kwargs (dict) – Extra parameters passed through to folium

Returns

route_map

Return type

folium.folium.Map

osmnx.footprints module

Download and plot footprints from OpenStreetMap.

osmnx.footprints.footprints_from_address(address, dist=1000, footprint_type='building', retain_invalid=False, timeout=None, memory=None, custom_settings=None)

Get footprints within some distance N, S, E, W of an address.

Parameters
  • address (string) – the address to geocode to a lat-lng point

  • dist (numeric) – distance in meters

  • footprint_type (string) – type of footprint to be downloaded. OSM tag key e.g. ‘building’, ‘landuse’, ‘place’, etc.

  • retain_invalid (bool) – if False discard any footprints with an invalid geometry

  • timeout (None) – deprecated, use ox.config(timeout=value) instead to configure this setting via the settings module

  • memory (None) – deprecated, use ox.config(memory=value) instead to configure this setting via the settings module

  • custom_settings (None) – deprecated, use ox.config(custom_settings=value) instead to configure this setting via the settings module

Returns

Return type

geopandas.GeoDataFrame

osmnx.footprints.footprints_from_place(place, footprint_type='building', retain_invalid=False, which_result=1, timeout=None, memory=None, custom_settings=None)

Get footprints within the boundaries of some place.

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 footprints using the footprints_from_address function, which geocodes the place name to a point and gets the footprints within some distance of that point.

Parameters
  • place (string) – the query to geocode to get geojson boundary polygon

  • footprint_type (string) – type of footprint to be downloaded. OSM tag key e.g. ‘building’, ‘landuse’, ‘place’, etc.

  • retain_invalid (bool) – if False discard any footprints with an invalid geometry

  • which_result (int) – max number of results to return and which to process upon receipt

  • timeout (None) – deprecated, use ox.config(timeout=value) instead to configure this setting via the settings module

  • memory (None) – deprecated, use ox.config(memory=value) instead to configure this setting via the settings module

  • custom_settings (None) – deprecated, use ox.config(custom_settings=value) instead to configure this setting via the settings module

Returns

Return type

geopandas.GeoDataFrame

osmnx.footprints.footprints_from_point(point, dist=1000, footprint_type='building', retain_invalid=False, timeout=None, memory=None, custom_settings=None)

Get footprints within some distance N, S, E, W of a lat-lng point.

Parameters
  • point (tuple) – a lat-lng point

  • dist (numeric) – distance in meters

  • footprint_type (string) – type of footprint to be downloaded. OSM tag key e.g. ‘building’, ‘landuse’, ‘place’, etc.

  • retain_invalid (bool) – if False discard any footprints with an invalid geometry

  • timeout (None) – deprecated, use ox.config(timeout=value) instead to configure this setting via the settings module

  • memory (None) – deprecated, use ox.config(memory=value) instead to configure this setting via the settings module

  • custom_settings (None) – deprecated, use ox.config(custom_settings=value) instead to configure this setting via the settings module

Returns

Return type

geopandas.GeoDataFrame

osmnx.footprints.footprints_from_polygon(polygon, footprint_type='building', retain_invalid=False, timeout=None, memory=None, custom_settings=None)

Get footprints within some polygon.

Parameters
  • polygon (shapely.geometry.Polygon or shapely.geometry.MultiPolygon) – the shape to get data within. coordinates should be in units of latitude-longitude degrees.

  • footprint_type (string) – type of footprint to be downloaded. OSM tag key e.g. ‘building’, ‘landuse’, ‘place’, etc.

  • retain_invalid (bool) – if False discard any footprints with an invalid geometry

  • timeout (None) – deprecated, use ox.config(timeout=value) instead to configure this setting via the settings module

  • memory (None) – deprecated, use ox.config(memory=value) instead to configure this setting via the settings module

  • custom_settings (None) – deprecated, use ox.config(custom_settings=value) instead to configure this setting via the settings module

Returns

Return type

geopandas.GeoDataFrame

osmnx.graph module

Graph creation functions.

osmnx.graph.graph_from_address(address, dist=1000, dist_type='bbox', network_type='all_private', simplify=True, retain_all=False, truncate_by_edge=False, return_coords=False, clean_periphery=True, custom_filter=None, timeout=None, memory=None, custom_settings=None, max_query_area_size=None)

Create a graph from OSM within some distance of some address.

Parameters
  • address (string) – the address to geocode and use as the central point around which to construct the graph

  • dist (int) – retain only those nodes within this many meters of the center of the graph

  • dist_type (string) – {‘network’, ‘bbox’} if ‘bbox’, retain only those nodes within a bounding box of the distance parameter. if ‘network’, retain only those nodes within some network distance from the center-most node.

  • network_type (string) – what type of street network to get if custom_filter is None. One of ‘walk’, ‘bike’, ‘drive’, ‘drive_service’, ‘all’, or ‘all_private’.

  • simplify (bool) – if True, simplify the graph topology

  • retain_all (bool) – if True, return the entire graph even if it is not connected

  • truncate_by_edge (bool) – if True, retain node if it’s outside bounding box but at least one of node’s neighbors are within bounding box

  • return_coords (bool) – optionally also return the geocoded coordinates of the address

  • clean_periphery (bool,) – if True, buffer 500m to get a graph larger than requested, then simplify, then truncate it to requested spatial boundaries

  • custom_filter (string) – a custom network filter to be used instead of the network_type presets, e.g., ‘[“power”~”line”]’ or ‘[“highway”~”motorway|trunk”]’. Also pass in a network_type that is in settings.bidirectional_network_types if you want graph to be fully bidirectional.

  • timeout (None) – deprecated, use ox.config(timeout=value) instead to configure this setting via the settings module

  • memory (None) – deprecated, use ox.config(memory=value) instead to configure this setting via the settings module

  • custom_settings (None) – deprecated, use ox.config(custom_settings=value) instead to configure this setting via the settings module

  • max_query_area_size (None) – deprecated, use ox.config(max_query_area_size=value) instead to configure this setting via the settings module

Returns

Return type

networkx.MultiDiGraph or optionally (networkx.MultiDiGraph, (lat, lng))

osmnx.graph.graph_from_bbox(north, south, east, west, network_type='all_private', simplify=True, retain_all=False, truncate_by_edge=False, clean_periphery=True, custom_filter=None, timeout=None, memory=None, custom_settings=None, max_query_area_size=None)

Create a graph from OSM within some bounding box.

Parameters
  • north (float) – northern latitude of bounding box

  • south (float) – southern latitude of bounding box

  • east (float) – eastern longitude of bounding box

  • west (float) – western longitude of bounding box

  • network_type (string) – what type of street network to get if custom_filter is None. One of ‘walk’, ‘bike’, ‘drive’, ‘drive_service’, ‘all’, or ‘all_private’.

  • simplify (bool) – if True, simplify the graph topology

  • retain_all (bool) – if True, return the entire graph even if it is not connected

  • truncate_by_edge (bool) – if True, retain node if it’s outside bounding box but at least one of node’s neighbors are within the bounding box

  • clean_periphery (bool) – if True, buffer 500m to get a graph larger than requested, then simplify, then truncate it to requested spatial boundaries

  • custom_filter (string) – a custom network filter to be used instead of the network_type presets, e.g., ‘[“power”~”line”]’ or ‘[“highway”~”motorway|trunk”]’. Also pass in a network_type that is in settings.bidirectional_network_types if you want graph to be fully bidirectional.

  • timeout (None) – deprecated, use ox.config(timeout=value) instead to configure this setting via the settings module

  • memory (None) – deprecated, use ox.config(memory=value) instead to configure this setting via the settings module

  • custom_settings (None) – deprecated, use ox.config(custom_settings=value) instead to configure this setting via the settings module

  • max_query_area_size (None) – deprecated, use ox.config(max_query_area_size=value) instead to configure this setting via the settings module

Returns

G

Return type

networkx.MultiDiGraph

osmnx.graph.graph_from_place(query, network_type='all_private', simplify=True, retain_all=False, truncate_by_edge=False, which_result=1, buffer_dist=None, clean_periphery=True, custom_filter=None, timeout=None, memory=None, custom_settings=None, max_query_area_size=None)

Create graph from OSM within the boundaries of some geocodable 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. Alternatively, you might try to vary the which_result parameter to use a different geocode result. For example, the first geocode result (ie, the default) might resolve to a point geometry, but the second geocode result for this query might resolve to a polygon, in which case you can use graph_from_place with which_result=2.

Parameters
  • query (string or dict or list) – the place(s) to geocode/download data for

  • network_type (string) – what type of street network to get if custom_filter is None. One of ‘walk’, ‘bike’, ‘drive’, ‘drive_service’, ‘all’, or ‘all_private’.

  • simplify (bool) – if True, simplify the graph topology

  • retain_all (bool) – if True, return the entire graph even if it is not connected

  • truncate_by_edge (bool) – if True, retain node if it’s outside polygon but at least one of node’s neighbors are within bbox

  • which_result (int) – max number of results to return and which to process upon receipt

  • buffer_dist (float) – distance to buffer around the place geometry, in meters

  • clean_periphery (bool) – if True, buffer 500m to get a graph larger than requested, then simplify, then truncate it to requested spatial boundaries

  • custom_filter (string) – a custom network filter to be used instead of the network_type presets, e.g., ‘[“power”~”line”]’ or ‘[“highway”~”motorway|trunk”]’. Also pass in a network_type that is in settings.bidirectional_network_types if you want graph to be fully bidirectional.

  • timeout (None) – deprecated, use ox.config(timeout=value) instead to configure this setting via the settings module

  • memory (None) – deprecated, use ox.config(memory=value) instead to configure this setting via the settings module

  • custom_settings (None) – deprecated, use ox.config(custom_settings=value) instead to configure this setting via the settings module

  • max_query_area_size (None) – deprecated, use ox.config(max_query_area_size=value) instead to configure this setting via the settings module

Returns

G

Return type

networkx.MultiDiGraph

osmnx.graph.graph_from_point(center_point, dist=1000, dist_type='bbox', network_type='all_private', simplify=True, retain_all=False, truncate_by_edge=False, clean_periphery=True, custom_filter=None, timeout=None, memory=None, custom_settings=None, max_query_area_size=None)

Create a graph from OSM within some distance of some (lat, lng) point.

Parameters
  • center_point (tuple) – the (lat, lng) center point around which to construct the graph

  • dist (int) – retain only those nodes within this many meters of the center of the graph, with distance determined according to dist_type argument

  • dist_type (string) – {‘network’, ‘bbox’} if ‘bbox’, retain only those nodes within a bounding box of the distance parameter. if ‘network’, retain only those nodes within some network distance from the center-most node.

  • network_type (string) – what type of street network to get if custom_filter is None. One of ‘walk’, ‘bike’, ‘drive’, ‘drive_service’, ‘all’, or ‘all_private’.

  • simplify (bool) – if True, simplify the graph topology

  • retain_all (bool) – if True, return the entire graph even if it is not connected

  • truncate_by_edge (bool) – if True, retain node if it’s outside bounding box but at least one of node’s neighbors are within bounding box

  • clean_periphery (bool,) – if True, buffer 500m to get a graph larger than requested, then simplify, then truncate it to requested spatial boundaries

  • custom_filter (string) – a custom network filter to be used instead of the network_type presets, e.g., ‘[“power”~”line”]’ or ‘[“highway”~”motorway|trunk”]’. Also pass in a network_type that is in settings.bidirectional_network_types if you want graph to be fully bidirectional.

  • timeout (None) – deprecated, use ox.config(timeout=value) instead to configure this setting via the settings module

  • memory (None) – deprecated, use ox.config(memory=value) instead to configure this setting via the settings module

  • custom_settings (None) – deprecated, use ox.config(custom_settings=value) instead to configure this setting via the settings module

  • max_query_area_size (None) – deprecated, use ox.config(max_query_area_size=value) instead to configure this setting via the settings module

Returns

G

Return type

networkx.MultiDiGraph

osmnx.graph.graph_from_polygon(polygon, network_type='all_private', simplify=True, retain_all=False, truncate_by_edge=False, clean_periphery=True, custom_filter=None, timeout=None, memory=None, custom_settings=None, max_query_area_size=None)

Create a graph from OSM within the boundaries of some shapely polygon.

Parameters
  • polygon (shapely.geometry.Polygon or shapely.geometry.MultiPolygon) – the shape to get network data within. coordinates should be in units of latitude-longitude degrees.

  • network_type (string) – what type of street network to get if custom_filter is None. One of ‘walk’, ‘bike’, ‘drive’, ‘drive_service’, ‘all’, or ‘all_private’.

  • simplify (bool) – if True, simplify the graph topology

  • retain_all (bool) – if True, return the entire graph even if it is not connected

  • truncate_by_edge (bool) – if True, retain node if it’s outside polygon but at least one of node’s neighbors are within polygon

  • clean_periphery (bool) – if True, buffer 500m to get a graph larger than requested, then simplify, then truncate it to requested spatial boundaries

  • custom_filter (string) – a custom network filter to be used instead of the network_type presets, e.g., ‘[“power”~”line”]’ or ‘[“highway”~”motorway|trunk”]’. Also pass in a network_type that is in settings.bidirectional_network_types if you want graph to be fully bidirectional.

  • timeout (None) – deprecated, use ox.config(timeout=value) instead to configure this setting via the settings module

  • memory (None) – deprecated, use ox.config(memory=value) instead to configure this setting via the settings module

  • custom_settings (None) – deprecated, use ox.config(custom_settings=value) instead to configure this setting via the settings module

  • max_query_area_size (None) – deprecated, use ox.config(max_query_area_size=value) instead to configure this setting via the settings module

Returns

G

Return type

networkx.MultiDiGraph

osmnx.graph.graph_from_xml(filepath, bidirectional=False, simplify=True, retain_all=False)

Create a graph from data in an OSM-formatted XML file.

Parameters
  • filepath (string) – path to file containing OSM XML data

  • bidirectional (bool) – if True, create bidirectional edges for one-way streets

  • simplify (bool) – if True, simplify the graph topology

  • retain_all (bool) – if True, return the entire graph even if it is not connected

Returns

G

Return type

networkx.MultiDiGraph

osmnx.io module

Serialize graphs to/from files on disk.

osmnx.io.load_graphml(filepath, node_type=<class 'int'>)

Load an OSMnx-saved GraphML file from disk.

Converts the node/edge attributes to appropriate data types.

Parameters
  • filepath (string) – path to the GraphML file

  • node_type (type) – convert node ids to this data type

Returns

G

Return type

networkx.MultiDiGraph

osmnx.io.save_graph_geopackage(G, filepath=None, encoding='utf-8')

Save graph nodes and edges to disk as layers in a GeoPackage file.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • filepath (string) – path to the GeoPackage file including extension. if None, use default data folder + graph.gpkg

  • encoding (string) – the character encoding for the saved file

Returns

Return type

None

osmnx.io.save_graph_shapefile(G, filepath=None, encoding='utf-8')

Save graph nodes and edges to disk as ESRI shapefiles.

The shapefile format is proprietary and outdated. Whenever possible, you should use the superior GeoPackage file format instead, for instance, via the save_graph_geopackage function.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • filepath (string) – path to the shapefiles folder (no file extension). if None, use default data folder + graph_shapefile

  • encoding (string) – the character encoding for the saved files

Returns

Return type

None

osmnx.io.save_graph_xml(data, filepath=None, node_tags=['highway'], node_attrs=['id', 'timestamp', 'uid', 'user', 'version', 'changeset', 'lat', 'lon'], edge_tags=['highway', 'lanes', 'maxspeed', 'name', 'oneway'], edge_attrs=['id', 'timestamp', 'uid', 'user', 'version', 'changeset'], oneway=False, merge_edges=True, edge_tag_aggs=None)

Save graph to disk as an OSM-formatted XML .osm file.

Note: for large networks this function can take a long time to run. Before using this function, make sure you configured OSMnx as described in the example below when you created the graph.

Example

>>> import osmnx as ox
>>> utn = ox.settings.useful_tags_node
>>> oxna = ox.settings.osm_xml_node_attrs
>>> oxnt = ox.settings.osm_xml_node_tags
>>> utw = ox.settings.useful_tags_way
>>> oxwa = ox.settings.osm_xml_way_attrs
>>> oxwt = ox.settings.osm_xml_way_tags
>>> utn = list(set(utn + oxna + oxnt))
>>> utw = list(set(utw + oxwa + oxwt))
>>> ox.config(all_oneway=True, useful_tags_node=utn, useful_tags_way=utw)
>>> G = ox.graph_from_place('Piedmont, CA, USA', network_type='drive')
>>> ox.save_graph_xml(G, filepath='./data/graph1.osm')
Parameters
  • data (networkx multi(di)graph OR a length 2 iterable of nodes/edges) – geopandas GeoDataFrames

  • filepath (string) – path to the .osm file including extension. if None, use default data folder + graph.osm

  • node_tags (list) – osm node tags to include in output OSM XML

  • node_attrs (list) – osm node attributes to include in output OSM XML

  • edge_tags (list) – osm way tags to include in output OSM XML

  • edge_attrs (list) – osm way attributes to include in output OSM XML

  • oneway (bool) – the default oneway value used to fill this tag where missing

  • merge_edges (bool) – if True merges graph edges such that each OSM way has one entry and one entry only in the OSM XML. Otherwise, every OSM way will have a separate entry for each node pair it contains.

  • edge_tag_aggs (list of length-2 string tuples) – useful only if merge_edges is True, this argument allows the user to specify edge attributes to aggregate such that the merged OSM way entry tags accurately represent the sum total of their component edge attributes. For example, if the user wants the OSM way to have a “length” attribute, the user must specify edge_tag_aggs=[(‘length’, ‘sum’)] in order to tell this method to aggregate the lengths of the individual component edges. Otherwise, the length attribute will simply reflect the length of the first edge associated with the way.

Returns

Return type

None

osmnx.io.save_graphml(G, filepath=None, gephi=False, encoding='utf-8')

Save graph to disk as GraphML file.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • filepath (string) – path to the GraphML file including extension. if None, use default data folder + graph.graphml

  • gephi (bool) – if True, give each edge a unique key to work around Gephi’s restrictive interpretation of the GraphML specification

  • encoding (string) – the character encoding for the saved file

Returns

Return type

None

osmnx.plot module

Plot spatial geometries, street networks, and routes.

osmnx.plot.get_colors(n, cmap='viridis', start=0.0, stop=1.0, alpha=1.0, return_hex=False)

Return n-length list of RGBa colors from the passed colormap name and alpha.

Parameters
  • n (int) – number of colors

  • cmap (string) – name of a colormap

  • start (float) – where to start in the colorspace

  • stop (float) – where to end in the colorspace

  • alpha (float) – opacity, the alpha channel for the RGBa colors

  • return_hex (bool) – if True, convert RGBa colors to a hexadecimal string

Returns

colors

Return type

list

osmnx.plot.get_edge_colors_by_attr(G, attr, num_bins=5, cmap='viridis', start=0, stop=1, na_color='none')

Get a list of edge colors by binning continuous attribute into quantiles.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • attr (string) – the name of the continuous-variable attribute

  • num_bins (int) – how many quantiles

  • cmap (string) – name of a colormap

  • start (float) – where to start in the colorspace

  • stop (float) – where to end in the colorspace

  • na_color (string) – what color to assign nodes with null attribute values

Returns

edge_colors

Return type

list

osmnx.plot.get_node_colors_by_attr(G, attr, num_bins=None, cmap='viridis', start=0, stop=1, na_color='none')

Get a list of node colors by binning continuous attribute into quantiles.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • attr (string) – the name of the attribute

  • num_bins (int) – how many quantiles (default None assigns each node to its own bin)

  • cmap (string) – name of a colormap

  • start (float) – where to start in the colorspace

  • stop (float) – where to end in the colorspace

  • na_color (string) – what color to assign nodes with null attribute values

Returns

node_colors

Return type

list

osmnx.plot.plot_figure_ground(G=None, address=None, point=None, dist=805, network_type='drive_service', street_widths=None, default_width=4, fig_length=None, edge_color='w', bgcolor='#333333', smooth_joints=True, filename=None, file_format=None, show=False, save=True, close=True, dpi=300, figsize=None, filepath=None)

Plot figure-ground diagram of a street network.

Defaults to one square mile.

Parameters
  • G (networkx.MultiDiGraph) – input graph, must be unprojected

  • address (string) – the address to geocode as the center point if G is not passed in

  • point (tuple) – the center point if address and G are not passed in

  • dist (numeric) – how many meters to extend north, south, east, and west from the center point

  • network_type (string) – what type of network to get

  • street_widths (dict) – where keys are street types and values are widths to plot in pixels

  • default_width (numeric) – the default street width in pixels for any street type not found in street_widths dict

  • fig_length (numeric) – deprecated, do not use

  • edge_color (string) – the color of the streets

  • bgcolor (string) – the color of the background

  • smooth_joints (bool) – if True, plot nodes same width as streets to smooth line joints and prevent cracks between them from showing

  • filename (string) – deprecated, do not use

  • file_format (string) – deprecated, do not use

  • show (bool) – if True, show the figure

  • save (bool) – if True, save the figure as an image file to disk

  • close (bool) – close the figure (only if show equals False) to prevent display

  • dpi (int) – the resolution of the image file if saving

  • figsize (tuple) – figure width, height (should be equal to each other)

  • filepath (string) – filename.ext to save image in settings.imgs_folder

Returns

fig, ax – matplotlib figure, axis

Return type

tuple

osmnx.plot.plot_footprints(gdf, fig=None, ax=None, figsize=None, color='#333333', bgcolor='w', set_bounds=True, bbox=None, save=False, show=True, close=False, filename=None, file_format=None, dpi=600, filepath=None)

Plot a GeoDataFrame of footprints.

Parameters
  • gdf (geopandas.GeoDataFrame) – GeoDataFrame of footprints

  • fig (figure) – matplotlib figure

  • ax (axis) – matplotlib axis

  • figsize (tuple) – (width, height) size of matplotlib figure

  • color (string) – the color of the footprints

  • bgcolor (string) – the background color of the plot

  • set_bounds (bool) – if True, set bounds from either passed-in bbox or the spatial extent of the gdf

  • bbox (tuple) – if True and if set_bounds is True, set the display bounds to this bbox

  • save (bool) – whether to save the figure to disk or not

  • show (bool) – whether to display the figure or not

  • close (bool) – close the figure (only if show equals False) to prevent display

  • filename (string) – deprecated, do not use

  • file_format (string) – deprecated, do not use

  • dpi (int) – the resolution of the image file if saving

  • filepath (string) – filename.ext to save image in settings.imgs_folder

Returns

fig, ax – matplotlib figure, axis

Return type

tuple

osmnx.plot.plot_graph(G, bbox=None, fig_height=None, fig_width=None, margin=0.02, axis_off=None, equal_aspect=None, bgcolor='w', show=True, save=False, close=True, file_format=None, filename=None, dpi=300, annotate=None, node_color='#66ccff', node_size=15, node_alpha=1, node_edgecolor='none', node_zorder=1, edge_color='#999999', edge_linewidth=1, edge_alpha=1, use_geom=None, figsize=None, filepath=None)

Plot a networkx spatial graph.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • bbox (tuple) – bounding box as north,south,east,west - if None will calculate from spatial extents of data. if passing a bbox, you probably also want to pass margin=0 to constrain it.

  • fig_height (int) – deprecated, do not use

  • fig_width (int) – deprecated, do not use

  • margin (float) – relative margin around the figure

  • axis_off (bool) – deprecated, do not use

  • equal_aspect (bool) – deprecated, do not use

  • bgcolor (string) – the background color of the figure and axis

  • show (bool) – if True, show the figure

  • save (bool) – if True, save the figure as an image file to disk

  • close (bool) – close the figure (only if show equals False) to prevent display

  • file_format (string) – deprecated, do not use

  • filename (string) – deprecated, do not use

  • dpi (int) – the resolution of the image file if saving

  • annotate (bool) – deprecated, do not use

  • node_color (string) – the color of the nodes. color is passed to matplotlib

  • node_size (int) – the size of the nodes

  • node_alpha (float) – the opacity of the nodes. if you passed RGBA values to node_color, then set this to None to use the alpha channel in node_color

  • node_edgecolor (string) – the color of the node’s marker’s border

  • node_zorder (int) – zorder to plot nodes, edges are always 2, so make node_zorder 1 to plot nodes beneath them or 3 to plot nodes atop them

  • edge_color (string) – the color of the edges’ lines. color is passed to matplotlib.

  • edge_linewidth (float) – the width of the edges’ lines

  • edge_alpha (float) – the opacity of the edges’ lines. if you passed RGBA values to edge_color, then set this to None to use the alpha channel in edge_color

  • use_geom (bool) – deprecated, do not use

  • figsize (tuple) – figure (width, height)

  • filepath (string) – filename.ext to save image in settings.imgs_folder

Returns

fig, ax – matplotlib figure, axis

Return type

tuple

osmnx.plot.plot_graph_route(G, route, bbox=None, fig_height=None, fig_width=None, margin=0.02, bgcolor='w', axis_off=None, show=True, save=False, close=True, file_format=None, filename=None, dpi=300, annotate=None, node_color='#999999', node_size=15, node_alpha=1, node_edgecolor='none', node_zorder=1, edge_color='#999999', edge_linewidth=1, edge_alpha=1, use_geom=None, origin_point=None, destination_point=None, route_color='r', route_linewidth=4, route_alpha=0.5, orig_dest_node_alpha=None, orig_dest_node_size=None, orig_dest_node_color=None, orig_dest_point_color=None, figsize=None, filepath=None, orig_dest_size=None)

Plot a route along a networkx spatial graph.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • route (list) – the route as a list of nodes

  • bbox (tuple) – bounding box as north,south,east,west - if None will calculate from spatial extents of data. if passing a bbox, you probably also want to pass margin=0 to constrain it.

  • fig_height (int) – deprecated, do not use

  • fig_width (int) – deprecated, do not use

  • margin (float) – relative margin around the figure

  • axis_off (bool) – deprecated, do not use

  • bgcolor (string) – the background color of the figure and axis

  • show (bool) – if True, show the figure

  • save (bool) – if True, save the figure as an image file to disk

  • close (bool) – close the figure (only if show equals False) to prevent display

  • file_format (string) – deprecated, do not use

  • filename (string) – deprecated, do not use

  • dpi (int) – the resolution of the image file if saving

  • annotate (bool) – deprecated, do not use

  • node_color (string) – the color of the nodes

  • node_size (int) – the size of the nodes

  • node_alpha (float) – the opacity of the nodes

  • node_edgecolor (string) – the color of the node’s marker’s border

  • node_zorder (int) – zorder to plot nodes, edges are always 2, so make node_zorder 1 to plot nodes beneath them or 3 to plot nodes atop them

  • edge_color (string) – the color of the edges’ lines

  • edge_linewidth (float) – the width of the edges’ lines

  • edge_alpha (float) – the opacity of the edges’ lines

  • use_geom (bool) – deprecated, do not use

  • origin_point (tuple) – deprecated, do not use

  • destination_point (tuple) – deprecated, do not use

  • route_color (string) – the color of the route

  • route_linewidth (int) – the width of the route line

  • route_alpha (float) – the opacity of the route line

  • orig_dest_node_alpha (float) – deprecated, do not use

  • orig_dest_node_size (int) – deprecated, do not use

  • orig_dest_node_color (string) – deprecated, do not use

  • orig_dest_point_color (string) – deprecated, do not use

  • figsize (tuple) – figure (width, height)

  • filepath (string) – filename.ext to save image in settings.imgs_folder

  • orig_dest_size (int) – the size of the origin and destination nodes

Returns

fig, ax – matplotlib figure, axis

Return type

tuple

osmnx.plot.plot_graph_routes(G, routes, bbox=None, fig_height=None, fig_width=None, margin=0.02, bgcolor='w', axis_off=None, show=True, save=False, close=True, file_format=None, filename=None, dpi=300, annotate=None, node_color='#999999', node_size=15, node_alpha=1, node_edgecolor='none', node_zorder=1, edge_color='#999999', edge_linewidth=1, edge_alpha=1, use_geom=None, orig_dest_points=None, route_color='r', route_linewidth=4, route_alpha=0.5, orig_dest_node_alpha=None, orig_dest_node_size=None, orig_dest_node_color=None, orig_dest_point_color=None, figsize=None, filepath=None, orig_dest_size=None)

Plot several routes along a networkx spatial graph.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • routes (list) – the routes as a list of lists of nodes

  • bbox (tuple) – bounding box as north,south,east,west - if None will calculate from spatial extents of data. if passing a bbox, you probably also want to pass margin=0 to constrain it.

  • fig_height (int) – deprecated, do not use

  • fig_width (int) – deprecated, do not use

  • margin (float) – relative margin around the figure

  • axis_off (bool) – if True turn off the matplotlib axis

  • bgcolor (string) – the background color of the figure and axis

  • show (bool) – if True, show the figure

  • save (bool) – if True, save the figure as an image file to disk

  • close (bool) – close the figure (only if show equals False) to prevent display

  • file_format (string) – deprecated, do not use

  • filename (string) – deprecated, do not use

  • dpi (int) – the resolution of the image file if saving

  • annotate (bool) – deprecated, do not use

  • node_color (string) – the color of the nodes

  • node_size (int) – the size of the nodes

  • node_alpha (float) – the opacity of the nodes

  • node_edgecolor (string) – the color of the node’s marker’s border

  • node_zorder (int) – zorder to plot nodes, edges are always 2, so make node_zorder 1 to plot nodes beneath them or 3 to plot nodes atop them

  • edge_color (string) – the color of the edges’ lines

  • edge_linewidth (float) – the width of the edges’ lines

  • edge_alpha (float) – the opacity of the edges’ lines

  • use_geom (bool) – deprecated, do not use

  • orig_dest_points (list of tuples) – deprecated, do not use

  • route_color (string) – route color (note: will be renamed route_colors and take list in next release)

  • route_linewidth (int) – the width of the route line

  • route_alpha (float) – the opacity of the route line

  • orig_dest_node_alpha (float) – deprecated, do not use

  • orig_dest_node_size (int) – deprecated, do not use

  • orig_dest_node_color (string) – deprecated, do not use

  • orig_dest_point_color (string) – deprecated, do not use

  • figsize (tuple) – figure (width, height)

  • filepath (string) – filename.ext to save image in settings.imgs_folder

  • orig_dest_size (int) – the size of the origin and destination nodes

Returns

fig, ax – matplotlib figure, axis

Return type

tuple

osmnx.plot.plot_shape(gdf, fc='#cbe0f0', ec='#999999', linewidth=1, alpha=1, figsize=6, 6, margin=0.02, axis_off=True)

Plot a GeoDataFrame of place boundary geometries.

Parameters
  • gdf (geopandas.GeoDataFrame) – the gdf containing the geometries to plot

  • fc (string or list) – the facecolor (or list of facecolors) for the polygons

  • ec (string or list) – the edgecolor (or list of edgecolors) for the polygons

  • linewidth (numeric) – the width of the polygon edge lines

  • alpha (numeric) – the opacity

  • figsize (tuple) – the size of the plotting figure

  • margin (numeric) – the size of the figure margins

  • axis_off (bool) – if True, disable the matplotlib axes display

Returns

fig, ax – matplotlib figure, axis

Return type

tuple

osmnx.pois module

Download points of interests (POIs) from OpenStreetMap.

osmnx.pois.pois_from_address(address, tags, dist=1000, timeout=None, memory=None, custom_settings=None)

Get point of interests (POIs) within some distance N, S, E, W of address.

Parameters
  • address (string) – the address to geocode to a lat-lng point

  • tags (dict) – Dict of tags used for finding POIs from the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one tag given. The dict keys should be OSM tags, (e.g., amenity, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.

  • dist (numeric) – distance in meters

  • timeout (None) – deprecated, use ox.config(timeout=value) instead to configure this setting via the settings module

  • memory (None) – deprecated, use ox.config(memory=value) instead to configure this setting via the settings module

  • custom_settings (None) – deprecated, use ox.config(custom_settings=value) instead to configure this setting via the settings module

Returns

gdf

Return type

geopandas.GeoDataFrame

osmnx.pois.pois_from_place(place, tags, which_result=1, timeout=None, memory=None, custom_settings=None)

Get points of interest (POIs) within the boundaries of some place.

Parameters
  • place (string) – the query to geocode to get boundary polygon

  • tags (dict) – Dict of tags used for finding POIs from the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one tag given. The dict keys should be OSM tags, (e.g., amenity, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.

  • which_result (int) – max number of geocoding results to return and which to process

  • timeout (None) – deprecated, use ox.config(timeout=value) instead to configure this setting via the settings module

  • memory (None) – deprecated, use ox.config(memory=value) instead to configure this setting via the settings module

  • custom_settings (None) – deprecated, use ox.config(custom_settings=value) instead to configure this setting via the settings module

Returns

gdf

Return type

geopandas.GeoDataFrame

osmnx.pois.pois_from_point(point, tags, dist=1000, timeout=None, memory=None, custom_settings=None)

Get point of interests (POIs) within some distance N, S, E, W of a point.

Parameters
  • point (tuple) – a (lat, lng) point

  • tags (dict) – Dict of tags used for finding POIs from the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one tag given. The dict keys should be OSM tags, (e.g., amenity, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.

  • dist (numeric) – distance in meters

  • timeout (None) – deprecated, use ox.config(timeout=value) instead to configure this setting via the settings module

  • memory (None) – deprecated, use ox.config(memory=value) instead to configure this setting via the settings module

  • custom_settings (None) – deprecated, use ox.config(custom_settings=value) instead to configure this setting via the settings module

Returns

gdf

Return type

geopandas.GeoDataFrame

osmnx.pois.pois_from_polygon(polygon, tags, timeout=None, memory=None, custom_settings=None)

Get point of interests (POIs) within some polygon.

Parameters
  • polygon (shapely.geometry.Polygon) – geographic boundaries to fetch POIs within

  • tags (dict) – Dict of tags used for finding POIs from the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one tag given. The dict keys should be OSM tags, (e.g., amenity, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.

  • timeout (None) – deprecated, use ox.config(timeout=value) instead to configure this setting via the settings module

  • memory (None) – deprecated, use ox.config(memory=value) instead to configure this setting via the settings module

  • custom_settings (None) – deprecated, use ox.config(custom_settings=value) instead to configure this setting via the settings module

Returns

gdf

Return type

geopandas.GeoDataFrame

osmnx.projection module

Project spatial geometries and street networks.

osmnx.projection.project_gdf(gdf, to_crs=None, to_latlong=False)

Project a GeoDataFrame from its current CRS to another.

If to_crs is None, project to the UTM CRS for the UTM zone in which the GeoDataFrame’s centroid lies. Otherwise project to the CRS defined by to_crs. The simple UTM zone calculation in this function works well for most latitudes, but may not work for some extreme northern locations like Svalbard or far northern Norway.

Parameters
  • gdf (geopandas.GeoDataFrame) – the GeoDataFrame to be projected

  • to_crs (dict or string or pyproj.CRS) – if None, project to UTM zone in which gdf’s centroid lies, otherwise project to this CRS

  • to_latlong (bool) – if True, project to settings.default_crs and ignore to_crs

Returns

gdf_proj – the projected GeoDataFrame

Return type

geopandas.GeoDataFrame

osmnx.projection.project_geometry(geometry, crs=None, to_crs=None, to_latlong=False)

Project a shapely geometry from its current CRS to another.

If to_crs is None, project to the UTM CRS for the UTM zone in which the geometry’s centroid lies. Otherwise project to the CRS defined by to_crs.

Parameters
  • geometry (shapely.geometry.Polygon or shapely.geometry.MultiPolygon) – the geometry to project

  • crs (dict or string or pyproj.CRS) – the starting CRS of the passed-in geometry. if None, it will be set to settings.default_crs

  • to_crs (dict or string or pyproj.CRS) – if None, project to UTM zone in which geometry’s centroid lies, otherwise project to this CRS

  • to_latlong (bool) – if True, project to settings.default_crs and ignore to_crs

Returns

geometry_proj, crs – the projected geometry and its new CRS

Return type

tuple

osmnx.projection.project_graph(G, to_crs=None)

Project graph from its current CRS to another.

If to_crs is None, project the graph to the UTM CRS for the UTM zone in which the graph’s centroid lies. Otherwise, project the graph to the CRS defined by to_crs.

Parameters
  • G (networkx.MultiDiGraph) – the graph to be projected

  • to_crs (dict or string or pyproj.CRS) – if None, project graph to UTM zone in which graph centroid lies, otherwise project graph to this CRS

Returns

G_proj – the projected graph

Return type

networkx.MultiDiGraph

osmnx.settings module

Global settings, can be configured by user with utils.config().

osmnx.simplification module

Simplify, correct, and consolidate network topology.

osmnx.simplification.consolidate_intersections(G, tolerance=10, rebuild_graph=True, dead_ends=False, update_edge_lengths=True)

Consolidate intersections comprising clusters of nearby nodes.

Merging nodes and return either their centroids or a rebuilt graph with consolidated intersections and reconnected edge geometries.

The tolerance argument should be adjusted to approximately match street design standards in the specific street network, and you should always use a projected graph to work in meaningful and consistent units like meters.

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. These 4 nodes represent a single intersection in the real world. This function consolidates them up by buffering them to an arbitrary distance, merging overlapping buffers, and taking their centroid. For best results, the tolerance argument should be adjusted to approximately match street design standards in the specific street network.

Parameters
  • G (networkx.MultiDiGraph) – a projected graph

  • tolerance (float) – nodes within this distance (in graph’s geometry’s units) will be dissolved into a single intersection

  • rebuild_graph (bool) – if True, use consolidate_intersections_rebuild_graph to consolidate the intersections and rebuild the graph, then return as networkx.MultiDiGraph. if False, just return the consolidated intersection points as a geopandas.GeoSeries (faster than rebuilding graph)

  • dead_ends (bool) – if False, discard dead-end nodes to return only street-intersection points

  • update_edge_lengths (bool) – just passed to consolidate_intersections_rebuild_graph. if True, update the length attribute of edges reconnected to a new merged node; if False, just retain the original edge length.

Returns

if rebuild_graph=True, returns MultiDiGraph with consolidated intersections and reconnected edge geometries. if rebuild_graph=False, returns GeoSeries of shapely Points representing the centroids of street intersections

Return type

networkx.MultiDiGraph or geopandas.GeoSeries

osmnx.simplification.simplify_graph(G, strict=True, remove_rings=True)

Simplify a graph’s topology by removing interstitial nodes.

Simplify graph topology by removing all nodes that are not intersections or dead-ends. Create an edge directly between the end points that encapsulate them, but retain the geometry of the original edges, saved as attribute in new edge.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • strict (bool) – if False, allow nodes to be end points even if they fail all other rules but have incident edges with different OSM IDs. Lets you keep nodes at elbow two-way intersections, but sometimes individual blocks have multiple OSM IDs within them too.

  • remove_rings (bool) – if True, remove isolated self-contained rings that have no endpoints

Returns

G – topologically simplified graph

Return type

networkx.MultiDiGraph

osmnx.speed module

Calculate graph edge speeds and travel times.

osmnx.speed.add_edge_speeds(G, hwy_speeds=None, fallback=None, precision=1)

Add edge speeds (km per hour) to graph as new speed_kph edge attributes.

Imputes free-flow travel speeds for all edges based on mean maxspeed value of edges, per highway type. For highway types in graph that have no maxspeed value on any edge, function assigns the mean of all maxspeed values in graph.

This mean-imputation can obviously be imprecise, and the caller can override it by passing in hwy_speeds and/or fallback arguments that correspond to local speed limit standards.

If edge maxspeed attribute has “mph” in it, value will automatically be converted from miles per hour to km per hour. Any other speed units should be manually converted to km per hour prior to running this function, otherwise there could be unexpected results. If “mph” does not appear in the edge’s maxspeed attribute string, then function assumes kph, per OSM guidelines: https://wiki.openstreetmap.org/wiki/Map_Features/Units

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • hwy_speeds (dict) – dict keys = OSM highway types and values = typical speeds (km per hour) to assign to edges of that highway type for any edges missing speed data. Any edges with highway type not in hwy_speeds will be assigned the mean preexisting speed value of all edges of that highway type.

  • fallback (numeric) – default speed value (km per hour) to assign to edges whose highway type did not appear in hwy_speeds and had no preexisting speed values on any edge

  • precision (int) – decimal precision to round speed_kph

Returns

G – graph with speed_kph attributes on all edges

Return type

networkx.MultiDiGraph

osmnx.speed.add_edge_travel_times(G, precision=1)

Add edge travel time (seconds) to graph as new travel_time edge attributes.

Calculates free-flow travel time along each edge, based on length and speed_kph attributes. Note: run add_edge_speeds first to generate the speed_kph attribute. All edges must have length and speed_kph attributes and all their values must be non-null.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • precision (int) – decimal precision to round travel_time

Returns

G – graph with travel_time attributes on all edges

Return type

networkx.MultiDiGraph

osmnx.stats module

Calculate graph-theoretic network measures.

osmnx.stats.basic_stats(G, area=None, clean_intersects=False, tolerance=15, circuity_dist='gc')

Calculate basic descriptive metric and topological stats for a graph.

For an unprojected lat-lng graph, tolerance and graph units should be in degrees, and circuity_dist should be ‘gc’. For a projected graph, tolerance and graph units should be in meters (or similar) and circuity_dist should be ‘euclidean’.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • area (numeric) – the area covered by the street network, in square meters (typically land area); if none, will skip all density-based metrics

  • clean_intersects (bool) – if True, calculate consolidated intersections count (and density, if area is provided) via consolidate_intersections function

  • tolerance (numeric) – tolerance value passed along if clean_intersects=True, see consolidate_intersections function documentation for details and usage

  • circuity_dist (string) – ‘gc’ or ‘euclidean’, how to calculate straight-line distances for circuity measurement; use former for lat-lng networks and latter for projected networks

Returns

stats – dictionary of network measures containing the following elements (some keys may not be present, based on the arguments passed into the function):

  • n = number of nodes in the graph

  • m = number of edges in the graph

  • k_avg = average node degree of the graph

  • intersection_count = number of intersections in graph, that is,

    nodes with >1 street emanating from them

  • streets_per_node_avg = how many streets (edges in the undirected

    representation of the graph) emanate from each node (ie, intersection or dead-end) on average (mean)

  • streets_per_node_counts = dict, with keys of number of streets

    emanating from the node, and values of number of nodes with this count

  • streets_per_node_proportion = dict, same as previous, but as a

    proportion of the total, rather than counts

  • edge_length_total = sum of all edge lengths in the graph, in meters

  • edge_length_avg = mean edge length in the graph, in meters

  • street_length_total = sum of all edges in the undirected

    representation of the graph

  • street_length_avg = mean edge length in the undirected

    representation of the graph, in meters

  • street_segments_count = number of edges in the undirected

    representation of the graph

  • node_density_km = n divided by area in square kilometers

  • intersection_density_km = intersection_count divided by area in

    square kilometers

  • edge_density_km = edge_length_total divided by area in square

    kilometers

  • street_density_km = street_length_total divided by area in square

    kilometers

  • circuity_avg = edge_length_total divided by the sum of the great

    circle distances between the nodes of each edge

  • self_loop_proportion = proportion of edges that have a single node

    as its two endpoints (ie, the edge links nodes u and v, and u==v)

  • clean_intersection_count = number of intersections in street

    network, merging complex ones into single points

  • clean_intersection_density_km = clean_intersection_count divided by

    area in square kilometers

Return type

dict

osmnx.stats.extended_stats(G, connectivity=False, anc=False, ecc=False, bc=False, cc=False)

Calculate extended topological stats and metrics for a graph.

Many of these algorithms have an inherently high time complexity. Global topological analysis of large complex networks is extremely time consuming and may exhaust computer memory. Consider using function arguments to not run metrics that require computation of a full matrix of paths if they will not be needed.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • connectivity (bool) – if True, calculate node and edge connectivity

  • anc (bool) – if True, calculate average node connectivity

  • ecc (bool) – if True, calculate shortest paths, eccentricity, and topological metrics that use eccentricity

  • bc (bool) – if True, calculate node betweenness centrality

  • cc (bool) – if True, calculate node closeness centrality

Returns

stats – dictionary of network measures containing the following elements (some only calculated/returned optionally, based on passed parameters):

  • avg_neighbor_degree

  • avg_neighbor_degree_avg

  • avg_weighted_neighbor_degree

  • avg_weighted_neighbor_degree_avg

  • degree_centrality

  • degree_centrality_avg

  • clustering_coefficient

  • clustering_coefficient_avg

  • clustering_coefficient_weighted

  • clustering_coefficient_weighted_avg

  • pagerank

  • pagerank_max_node

  • pagerank_max

  • pagerank_min_node

  • pagerank_min

  • node_connectivity

  • node_connectivity_avg

  • edge_connectivity

  • eccentricity

  • diameter

  • radius

  • center

  • periphery

  • closeness_centrality

  • closeness_centrality_avg

  • betweenness_centrality

  • betweenness_centrality_avg

Return type

dict

osmnx.truncate module

Truncate graph by distance, bounding box, or polygon.

osmnx.truncate.truncate_graph_bbox(G, north, south, east, west, truncate_by_edge=False, retain_all=False, quadrat_width=0.05, min_num=3)

Remove every node in graph that falls outside a bounding box.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • north (float) – northern latitude of bounding box

  • south (float) – southern latitude of bounding box

  • east (float) – eastern longitude of bounding box

  • west (float) – western longitude of bounding box

  • truncate_by_edge (bool) – if True retain node if it’s outside bbox but at least one of node’s neighbors are within bbox

  • retain_all (bool) – if True, return the entire graph even if it is not connected

  • quadrat_width (numeric) – passed on to intersect_index_quadrats: the linear length (in degrees) of the quadrats with which to cut up the geometry (default = 0.05, approx 4km at NYC’s latitude)

  • min_num (int) – passed on to intersect_index_quadrats: the minimum number of linear quadrat lines (e.g., min_num=3 would produce a quadrat grid of 4 squares)

Returns

G – the truncated graph

Return type

networkx.MultiDiGraph

osmnx.truncate.truncate_graph_dist(G, source_node, max_dist=1000, weight='length', retain_all=False)

Remove every node farther than some network distance from source_node.

This function can be slow for large graphs, as it must calculate shortest path distances between source_node and every other graph node.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • source_node (int) – the node in the graph from which to measure network distances to other nodes

  • max_dist (int) – remove every node in the graph greater than this distance from the source_node (along the network)

  • weight (string) – how to weight the graph when measuring distance (default ‘length’ is how many meters long the edge is)

  • retain_all (bool) – if True, return the entire graph even if it is not connected

Returns

G – the truncated graph

Return type

networkx.MultiDiGraph

osmnx.truncate.truncate_graph_polygon(G, polygon, retain_all=False, truncate_by_edge=False, quadrat_width=0.05, min_num=3)

Remove every node in graph that falls outside a shapely (Multi)Polygon.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • polygon (shapely.geometry.Polygon or shapely.geometry.MultiPolygon) – only retain nodes in graph that lie within this geometry

  • retain_all (bool) – if True, return the entire graph even if it is not connected

  • truncate_by_edge (bool) – if True retain node if it’s outside polygon but at least one of node’s neighbors are within polygon

  • quadrat_width (numeric) – passed on to intersect_index_quadrats: the linear length (in degrees) of the quadrats with which to cut up the geometry (default = 0.05, approx 4km at NYC’s latitude)

  • min_num (int) – passed on to intersect_index_quadrats: the minimum number of linear quadrat lines (e.g., min_num=3 would produce a quadrat grid of 4 squares)

Returns

G – the truncated graph

Return type

networkx.MultiDiGraph

osmnx.utils module

General utility functions.

osmnx.utils.citation()

Print the OSMnx package’s citation information.

Boeing, G. 2017. OSMnx: New Methods for Acquiring, Constructing, Analyzing, and Visualizing Complex Street Networks. Computers, Environment and Urban Systems, 65(126-139). https://doi.org/10.1016/j.compenvurbsys.2017.05.004

Returns

Return type

None

osmnx.utils.config(data_folder='data', logs_folder='logs', imgs_folder='images', cache_folder='cache', use_cache=False, log_file=False, log_console=False, log_level=20, log_name='osmnx', log_filename='osmnx', useful_tags_node=['ref', 'highway'], useful_tags_way=['bridge', 'tunnel', 'oneway', 'lanes', 'ref', 'name', 'highway', 'maxspeed', 'service', 'access', 'area', 'landuse', 'width', 'est_width', 'junction'], osm_xml_node_attrs=['id', 'timestamp', 'uid', 'user', 'version', 'changeset', 'lat', 'lon'], osm_xml_node_tags=['highway'], osm_xml_way_attrs=['id', 'timestamp', 'uid', 'user', 'version', 'changeset'], osm_xml_way_tags=['highway', 'lanes', 'maxspeed', 'name', 'oneway'], overpass_settings='[out:json][timeout:{timeout}]{maxsize}', timeout=180, memory=None, max_query_area_size=2500000000, default_access='["access"!~"private"]', default_crs='epsg:4326', default_user_agent='OSMnx Python package (https://github.com/gboeing/osmnx)', default_referer='OSMnx Python package (https://github.com/gboeing/osmnx)', default_accept_language='en', nominatim_endpoint='https://nominatim.openstreetmap.org/', nominatim_key=None, overpass_endpoint='http://overpass-api.de/api', all_oneway=False)

Configure OSMnx by setting the default global settings’ values.

Any parameters not passed by the caller are set to their original default values.

Parameters
  • data_folder (string) – where to save/load data files by default

  • logs_folder (string) – where to save log files

  • imgs_folder (string) – where to save figures by default

  • cache_folder (string) – where to save HTTP response cache

  • use_cache (bool) – if True, cache HTTP responses locally instead of calling API repetitively for the same request

  • log_file (bool) – if True, save log output to a file in logs_folder

  • log_console (bool) – if True, print log output to the console (terminal window)

  • log_level (int) – one of the logger.level constants

  • log_name (string) – name of the logger

  • log_filename (string) – name of the log file

  • useful_tags_node (list) – OSM “node” tags to add as graph node attributes, when present

  • useful_tags_way (list) – OSM “way” tags to add as graph edge attributes, when present

  • osm_xml_node_attrs (list) – node attributes for saving .osm XML files with save_graph_xml function

  • osm_xml_node_tags (list) – node tags for saving .osm XML files with save_graph_xml function

  • osm_xml_way_attrs (list) – edge attributes for saving .osm XML files with save_graph_xml function

  • osm_xml_way_tags (list) – edge tags for for saving .osm XML files with save_graph_xml function

  • overpass_settings (string) – Settings string for overpass queries. For example, to query historical OSM data as of a certain date: ‘[out:json][timeout:90][date:”2019-10-28T19:20:00Z”]’. Use with caution.

  • timeout (int) – the timeout interval for the HTTP request and for API to use while running the query

  • memory (int) – Overpass server memory allocation size for the query, in bytes. If None, server will use its default allocation size. Use with caution.

  • max_query_area_size (int) – maximum area for any part of the geometry in meters: any polygon bigger than this will get divided up for multiple queries to API (default 50km x 50km)

  • default_access (string) – default filter for OSM “access” key

  • default_crs (string) – default coordinate reference system to set when creating graphs

  • default_user_agent (string) – HTTP header user-agent

  • default_referer (string) – HTTP header referer

  • default_accept_language (string) – HTTP header accept-language

  • nominatim_endpoint (string) – the API endpoint to use for nominatim queries

  • nominatim_key (string) – your API key, if you are using an endpoint that requires one

  • overpass_endpoint (string) – the API endpoint to use for overpass queries

  • all_oneway (boolean) – if True, forces all ways to be loaded as oneway ways, preserving the original order of nodes stored in the OSM way XML. Only use if specifically saving to .osm XML file with save_graph_xml function.

Returns

Return type

None

osmnx.utils.log(message, level=None, name=None, filename=None)

Write a message to the logger.

This logs to file and/or prints to the console, depending on the current configuration of settings.log_file and settings.log_console.

Parameters
  • message (string) – the message to log

  • level (int) – one of the logger.level constants

  • name (string) – name of the logger

  • filename (string) – name of the log file

Returns

Return type

None

osmnx.utils.ts(style='datetime', template=None)

Get current timestamp as string.

Parameters
  • style (string) – format the timestamp with this built-in template. must be one of {‘datetime’, ‘date’, ‘time’}

  • template (string) – if not None, format the timestamp with this template instead of one of the built-in styles

Returns

ts – the string timestamp

Return type

string

osmnx.utils_geo module

Geospatial utility functions.

osmnx.utils_geo.bbox_from_point(point, dist=1000, project_utm=False, return_crs=False)

Create a bounding box from a point.

Create a bounding box some distance in each direction (north, south, east, and west) from some (lat, lng) point.

Parameters
  • point (tuple) – the (lat, lng) point to create the bounding box around

  • dist (int) – how many meters the north, south, east, and west sides of the box should each be from the point

  • project_utm (bool) – if True return bbox as UTM coordinates

  • return_crs (bool) – if True and project_utm=True, return the projected CRS

Returns

(north, south, east, west) if return_crs=False or (north, south, east, west, crs_proj) if return_crs=True

Return type

tuple

osmnx.utils_geo.bbox_to_poly(north, south, east, west)

Convert bounding box coordinates to shapely Polygon.

Parameters
  • north (float) – northern coordinate

  • south (float) – southern coordinate

  • east (float) – eastern coordinate

  • west (float) – western coordinate

Returns

Return type

shapely.geometry.Polygon

osmnx.utils_geo.geocode(query)

Geocode a query string to (lat, lng) with the Nominatim geocoder.

Parameters

query (string) – the query string to geocode

Returns

point – the (lat, lng) coordinates returned by the geocoder

Return type

tuple

osmnx.utils_geo.redistribute_vertices(geom, dist)

Redistribute the vertices on a projected LineString or MultiLineString.

The distance argument is only approximate since the total distance of the linestring may not be a multiple of the preferred distance. This function works on only (Multi)LineString geometry types.

Parameters
  • geom (shapely.geometry.LineString or shapely.geometry.MultiLineString) – a Shapely geometry (should be projected)

  • dist (float) – spacing length along edges. Units are same as the geom: degrees for unprojected geometries and meters for projected geometries. The smaller the dist value, the more points are created.

Returns

the redistributed vertices as a list if geom is a LineString or MultiLineString if geom is a MultiLineString

Return type

list or shapely.geometry.MultiLineString

osmnx.utils_geo.round_geometry_coords(shape, precision)

Round the coordinates of a shapely geometry to some decimal precision.

Parameters
  • shape (shapely.geometry.geometry, either Point, MultiPoint, LineString,) – MultiLineString, Polygon, or MultiPolygon the geometry to round the coordinates of

  • precision (int) – decimal precision to round coordinates to

Returns

Return type

shapely.geometry.geometry

osmnx.utils_graph module

Graph utility functions.

osmnx.utils_graph.add_edge_lengths(G, precision=3)

Add length (meters) attribute to each edge.

Calculate via great circle distance between nodes u and v.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • precision (int) – decimal precision to round lengths

Returns

G – graph with edge length attributes

Return type

networkx.MultiDiGraph

osmnx.utils_graph.count_streets_per_node(G, nodes=None)

Count how many street segments emanate from each node in this graph.

If nodes is passed, then only count the nodes in the graph with those IDs.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • nodes (iterable) – the set of node IDs to get counts for

Returns

streets_per_node – counts of how many streets emanate from each node with keys=node id and values=count

Return type

dict

osmnx.utils_graph.get_largest_component(G, strongly=False)

Get subgraph of MultiDiGraph’s largest weakly/strongly connected component.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • strongly (bool) – if True, return the largest strongly instead of weakly connected component

Returns

G – the largest connected component subgraph from the original graph

Return type

networkx.MultiDiGraph

osmnx.utils_graph.get_route_edge_attributes(G, route, attribute=None, minimize_key='length', retrieve_default=None)

Get a list of attribute values for each edge in a path.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • route (list) – list of nodes in the path

  • attribute (string) – the name of the attribute to get the value of for each edge. If not specified, the complete data dict is returned for each edge.

  • minimize_key (string) – if there are parallel edges between two nodes, select the one with the lowest value of minimize_key

  • retrieve_default (Callable[Tuple[Any, Any], Any]) – Function called with the edge nodes as parameters to retrieve a default value, if the edge does not contain the given attribute. Per default, a KeyError is raised

Returns

attribute_values – list of edge attribute values

Return type

list

osmnx.utils_graph.get_undirected(G)

Convert MultiDiGraph to MultiGraph.

Maintains parallel edges if their geometries differ.

Parameters

G (networkx.MultiDiGraph) – input graph

Returns

H

Return type

networkx.MultiGraph

osmnx.utils_graph.graph_from_gdfs(gdf_nodes, gdf_edges, graph_attrs=None)

Convert node and edge GeoDataFrames to a MultiDiGraph.

This function is the inverse of graph_to_gdfs.

Parameters
  • gdf_nodes (geopandas.GeoDataFrame) – GeoDataFrame of graph nodes

  • gdf_edges (geopandas.GeoDataFrame) – GeoDataFrame of graph edges

  • graph_attrs (dict) – the new G.graph attribute dict; if None, add crs as the only graph-level attribute

Returns

G

Return type

networkx.MultiDiGraph

osmnx.utils_graph.graph_to_gdfs(G, nodes=True, edges=True, node_geometry=True, fill_edge_geometry=True)

Convert a graph to node and/or edge GeoDataFrames.

This function is the inverse of graph_from_gdfs.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • nodes (bool) – if True, convert graph nodes to a GeoDataFrame and return it

  • edges (bool) – if True, convert graph edges to a GeoDataFrame and return it

  • node_geometry (bool) – if True, create a geometry column from node x and y data

  • fill_edge_geometry (bool) – if True, fill in missing edge geometry fields using nodes u and v

Returns

gdf_nodes or gdf_edges or tuple of (gdf_nodes, gdf_edges)

Return type

geopandas.GeoDataFrame or tuple

osmnx.utils_graph.induce_subgraph(G, node_subset)

Induce a subgraph of G.

Parameters
  • G (networkx.MultiDiGraph) – input graph

  • node_subset (list-like) – the subset of nodes to induce a subgraph of G

Returns

H – the subgraph of G induced by node_subset

Return type

networkx.MultiDiGraph

osmnx.utils_graph.remove_isolated_nodes(G)

Remove from a graph all nodes that have no incident edges.

Parameters

G (networkx.MultiDiGraph) – graph from which to remove nodes

Returns

G – graph with all isolated nodes removed

Return type

networkx.MultiDiGraph