# Getting Started¶

## Get Started in 4 Steps¶

Install OSMnx by following the Installation guide.

Read “Introducing OSMnx” below on this page.

Work through the OSMnx Examples Gallery for step-by-step tutorials and sample code.

Consult the 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 and functionality.

## 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 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. Refer to the FAQ below for server usage limitations.

### 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.

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.

### 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. See the official reference paper at the Further Reading page for complete modeling details.

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. Refer to the `graph`

module’s documentation for more details. 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. It also simplifies the graph topology as discussed below.

### 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.

### 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 MultiGraph if you prefer an undirected representation of the network, or to a DiGraph if you prefer a directed representation without any parallel edges. It 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.

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.

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.

### 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.

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.

### 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.

### 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.

### 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 User Reference. More feature development details are in the Changelog. Consult the Further Reading resources for additional technical details and research.

## Frequently Asked Questions¶

*How do I install OSMnx?* Follow the 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 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.