Package 'osmnxr'

Description

Builds a tiny ⁠n x n⁠ regular street grid as an osm_graph, with no network access. Edges are bidirectional and weighted by their planar length. Useful for examples, tests and learning the API offline.

Usage

example_osm_graph(n = 4, spacing = 100)

Arguments

Value

An osm_graph in an arbitrary projected CRS.

Examples

g <- example_osm_graph()
g
ox_basic_stats(g)

Description

Test whether an object is an osm_graph

Usage

is_osm_graph(x)

Arguments

Value

A logical scalar.

Description

Low-level constructor wrapping tidy sf nodes and edges into the central osm_graph object used across the package. Most users obtain an osm_graph from ox_graph_from_place() and friends rather than calling this directly.

Usage

new_osm_graph(nodes, edges, meta = list())

Arguments

Value

An object of class osm_graph.

Description

Assigns a free-flow speed (km/h) to every edge based on its highway class, adding a speed_kph column. Unknown classes get fallback.

Usage

ox_add_edge_speeds(g, speeds = NULL, fallback = 40)

Arguments

Value

The osm_graph with a speed_kph edge column.

Examples

g <- example_osm_graph()
g <- ox_add_edge_speeds(g, speeds = c(residential = 25))
head(g$edges$speed_kph)

Description

Adds a travel_time edge column (in seconds) from edge length (metres) and speed_kph. Speeds are added with ox_add_edge_speeds() first if missing. The resulting column can be used as a routing weight for time-based shortest paths and isochrones.

Usage

ox_add_edge_travel_times(g)

Arguments

Value

The osm_graph with speed_kph and travel_time edge columns.

Examples

g <- example_osm_graph()
g <- ox_add_edge_travel_times(g)
from <- ox_nearest_nodes(g, 0, 0)
to <- ox_nearest_nodes(g, 300, 300)
ox_shortest_path(g, from, to, weight = "travel_time")

Description

Returns a data.frame in the column layout expected by the dodgr routing package (from_id, from_lon, from_lat, to_id, to_lon, to_lat, d), suitable for dodgr::dodgr_dists() and friends.

Usage

ox_as_dodgr(g, weight = "length")

Arguments

Value

A data.frame dodgr graph.

Examples

g <- example_osm_graph()
head(ox_as_dodgr(g))

Description

Extract sf nodes and edges from an osm_graph

Usage

ox_as_sf(g)

Arguments

Value

A named list with sf elements nodes and edges.

Examples

g <- example_osm_graph()
parts <- ox_as_sf(g)
parts$edges

Description

Returns the graph as a sfnetworks::sfnetwork() object, ready for the sfnetworks/tidygraph spatial-network workflow.

Usage

ox_as_sfnetwork(g, directed = TRUE)

Arguments

Value

An sfnetwork.

Examples

g <- example_osm_graph()
ox_as_sfnetwork(g)

Description

Returns the graph as a tidygraph::tbl_graph(), dropping geometry (node coordinates are kept as x/y columns).

Usage

ox_as_tidygraph(g, directed = TRUE)

Arguments

Value

A tbl_graph.

Examples

g <- example_osm_graph()
ox_as_tidygraph(g)

Description

Summary measures for an osm_graph: node and edge counts, total and mean edge length, mean out-degree, self-loop count and average circuity. Computation is performed by the bundled Rust core.

Usage

ox_basic_stats(g, weight = "length")

Arguments

Value

A one-row tibble of statistics.

Examples

g <- example_osm_graph()
ox_basic_stats(g)

Description

Initial compass bearing (degrees clockwise from north) of each edge, from its first to its last coordinate. Geographic coordinates are used; projected graphs are transformed to EPSG:4326 first.

Usage

ox_bearings(g)

Arguments

Value

A numeric vector of bearings, one per edge.

Examples

g <- example_osm_graph()
head(ox_bearings(g))

Description

Computes betweenness and/or closeness centrality for every node, using the Rust core (Brandes' algorithm for betweenness; one Dijkstra per node for closeness).

Usage

ox_centrality(
  g,
  type = c("betweenness", "closeness"),
  weight = "length",
  normalized = TRUE
)

Arguments

Value

A tibble with column osmid plus one column per requested measure.

Examples

g <- example_osm_graph(n = 4)
ox_centrality(g, type = "betweenness")

Description

The ratio of total edge length to total straight-line (great-circle for geographic CRS, Euclidean for projected) distance between edge endpoints. A value of 1 means perfectly straight streets; higher values indicate more winding networks.

Usage

ox_circuity(g)

Arguments

Value

A numeric scalar (>= 1).

Examples

g <- example_osm_graph()
ox_circuity(g)

Description

Empties the in-memory cache of downloaded OpenStreetMap responses.

Usage

ox_clear_cache()

Value

Invisibly NULL.

Examples

ox_clear_cache()

Description

Merges groups of nodes lying within tolerance of one another into single nodes placed at the group centroid, then rewrites edges to the consolidated nodes and drops the resulting self-loops. Useful for collapsing the multiple OSM nodes that represent one complex junction (e.g. dual carriageways).

Usage

ox_consolidate_intersections(g, tolerance = 10)

Arguments

Details

Clustering uses sf::st_is_within_distance(); connected components are found by the Rust core. tolerance is in the units of the graph CRS, so project the graph first (e.g. to a metric CRS) for a meaningful distance.

Value

A consolidated osm_graph (with meta$consolidated = TRUE).

Examples

g <- example_osm_graph(n = 4, spacing = 100)
# nothing is within 10 units here, so the graph is unchanged
ox_consolidate_intersections(g, tolerance = 10)

Description

Computes the matrix of minimum-weight distances between every from node and every to node (Rust core; one Dijkstra per source).

Usage

ox_distance_matrix(g, from, to = from, weight = "length")

Arguments

Value

A numeric matrix (length(from) x length(to)) with osmid dimnames; Inf marks unreachable pairs.

Examples

g <- example_osm_graph(n = 3)
nodes <- g$nodes$osmid
ox_distance_matrix(g, from = nodes[1:2], to = nodes[3:4])

Description

Minimum-weight distance from from to every node in the graph.

Usage

ox_distances(g, from, weight = "length")

Arguments

Value

A tibble with columns osmid and distance (Inf for unreachable nodes).

Examples

g <- example_osm_graph()
ox_distances(g, ox_nearest_nodes(g, 0, 0))

Description

Loads a small, real street network shipped with the package (downloaded once from OpenStreetMap and simplified) so that examples and vignettes can show real analyses without network access.

Usage

ox_example(name = c("olinda", "manhattan", "rome"))

Arguments

Value

An osm_graph.

Examples

g <- ox_example("olinda")
g
ox_basic_stats(g)

Description

Queries OpenStreetMap (via Overpass) for elements matching tags — points of interest, amenities, buildings, transit stops, and so on — returning them as an sf of points (ways and relations are represented by their centroid).

Usage

ox_features_from_bbox(bbox, tags)

Arguments

Value

An sf of POINT features with osm_type, osm_id and one column per tag encountered.

Examples

bbox <- c(-34.91, -8.07, -34.87, -8.04)
ox_features_from_bbox(bbox, tags = list(amenity = "school"))

Description

Geocodes query with ox_geocode() and downloads matching features around it. See ox_features_from_bbox() for the tags format.

Usage

ox_features_from_place(query, tags, dist = 2000)

Arguments

Value

An sf of POINT features.

Examples

ox_features_from_place("Olinda, Brazil", tags = list(amenity = "hospital"))

Description

Resolve a free-form query to coordinates and metadata using the OpenStreetMap Nominatim service.

Usage

ox_geocode(query, limit = 1)

Arguments

Value

A tibble with columns display_name, lat, lon, osm_type, osm_id and class.

Examples

ox_geocode("Recife, Brazil")

Description

Like ox_geocode() but returns the place geometry (boundary polygon when available, otherwise a point) as an sf object.

Usage

ox_geocode_to_sf(query, limit = 1)

Arguments

Value

An sf object (one row per result) in EPSG:4326.

Examples

ox_geocode_to_sf("Recife, Brazil")

Description

Download a street network around an address

Usage

ox_graph_from_address(address, dist = 1000, network_type = "drive")

Arguments

Value

An osm_graph.

Examples

g <- ox_graph_from_address("Marco Zero, Recife", dist = 600)

Description

Download a street network within a bounding box

Usage

ox_graph_from_bbox(bbox, network_type = "drive")

Arguments

Details

Transient Overpass failures (HTTP 429/5xx, dropped connections) are retried automatically with exponential backoff; the Overpass endpoint, timeout and number of attempts are configurable via ox_settings().

Value

An osm_graph.

Examples

bbox <- c(-34.91, -8.07, -34.87, -8.04)
g <- ox_graph_from_bbox(bbox, network_type = "drive")

Description

Geocodes query with ox_geocode() and downloads the street network within the bounding box of the matched place.

Usage

ox_graph_from_place(query, network_type = "drive")

Arguments

Value

An osm_graph.

Examples

g <- ox_graph_from_place("Olinda, Brazil", network_type = "drive")

Description

Download a street network around a point

Usage

ox_graph_from_point(point, dist = 1000, network_type = "drive")

Arguments

Value

An osm_graph.

Examples

g <- ox_graph_from_point(c(-34.89, -8.05), dist = 800)

Description

For one or more origin nodes, finds the set of nodes reachable within each cutoff (by the chosen edge weight — distance or, with ox_add_edge_travel_times(), travel time) and returns a polygon per cutoff: the hull of the reachable nodes. With several origins, reachability is the minimum cost from any origin.

Usage

ox_isochrone(g, center, cutoffs, weight = "length", ratio = 0.4)

Arguments

Details

Reachable sets come from the Rust Dijkstra core; the hull is built with sf::st_concave_hull() when available (GEOS >= 3.11), falling back to a convex hull. For metric cutoffs, project the graph to a metric CRS first.

Value

An sf object with one polygon row per cutoff (columns cutoff, n_nodes, geometry), ordered from largest to smallest cutoff so smaller areas draw on top.

Examples

g <- example_osm_graph(n = 6, spacing = 100)
center <- ox_nearest_nodes(g, 250, 250)
iso <- ox_isochrone(g, center, cutoffs = c(100, 300))
iso

Description

Computes up to k loopless shortest paths from from to to using Yen's algorithm in the Rust core. Useful for route alternatives.

Usage

ox_k_shortest_paths(g, from, to, k = 3, weight = "length")

Arguments

Value

A tibble with one row per path: rank, cost and a list-column path of node osmids, ordered by increasing cost. Fewer than k rows are returned when fewer distinct paths exist.

Examples

g <- example_osm_graph()
from <- ox_nearest_nodes(g, 0, 0)
to <- ox_nearest_nodes(g, 200, 200)
ox_k_shortest_paths(g, from, to, k = 3)

Description

Reads a GraphML file written by ox_save_graphml() back into an osm_graph, restoring node coordinates, edge attributes and edge geometry (from the stored WKT).

Usage

ox_load_graphml(path)

Arguments

Value

An osm_graph.

Examples

g <- example_osm_graph()
f <- tempfile(fileext = ".graphml")
ox_save_graphml(g, f)
ox_load_graphml(f)

Description

Returns, for each supplied coordinate, the graph edge closest in planar distance.

Usage

ox_nearest_edges(g, x, y)

Arguments

Value

An sf subset of g$edges, one row per input point.

Examples

g <- example_osm_graph()
ox_nearest_edges(g, x = 50, y = 0)

Description

Returns the osmid of the graph node closest (in planar distance) to each supplied coordinate.

Usage

ox_nearest_nodes(g, x, y)

Arguments

Value

An integer/numeric vector of node osmids, one per input point.

Examples

g <- example_osm_graph()
ox_nearest_nodes(g, x = 0, y = 0)

Description

Shannon entropy (in nats) of the distribution of edge compass bearings, binned into equal sectors. Higher values indicate a more disordered (organic) network; lower values a more ordered (gridiron) one.

Usage

ox_orientation_entropy(x, num_bins = 36)

Arguments

Value

A numeric scalar (entropy in nats).

Examples

g <- example_osm_graph()
ox_orientation_entropy(g)

Description

Draws a figure-ground diagram: the streets in a single colour on a solid background, with no axes or margins. Cropping different places to the same extent makes their network form directly comparable, as in Boeing (2025).

Usage

ox_plot_figure_ground(g, bg = "black", col = "white", lwd = 1.2, title = NULL)

Arguments

Value

Invisibly, the osm_graph.

Examples

g <- example_osm_graph()
ox_plot_figure_ground(g)

Description

Draws a polar histogram (rose plot) of edge compass bearings, the standard visual summary of a street network's orientation order. Requires ggplot2.

Usage

ox_plot_orientation(
  x,
  num_bins = 36,
  fill = "#0d3b66",
  title = "Street orientation"
)

Arguments

Value

A ggplot object.

Examples

g <- example_osm_graph()
ox_plot_orientation(g)

Description

Writes the graph to a GraphML file compatible with OSMnx / NetworkX / Gephi. Edge geometry is preserved losslessly as a WKT attribute, so the graph round-trips through ox_load_graphml().

Usage

ox_save_graphml(g, path)

Arguments

Value

path, invisibly.

Examples

g <- example_osm_graph()
f <- tempfile(fileext = ".graphml")
ox_save_graphml(g, f)

Description

Configure the Overpass and Nominatim endpoints, HTTP behaviour and caching used by all ⁠ox_*⁠ download functions. Called with no arguments it returns the current settings as a list; called with named arguments it updates them and returns the previous values invisibly.

Usage

ox_settings(...)

Arguments

Details

timeout (seconds) applies both to the HTTP request and to the Overpass server-side query timeout. max_tries is the total number of attempts per request: transient failures — HTTP 429, 500, 502, 503, 504 and dropped connections, which busy Overpass/Nominatim servers routinely return — are retried with exponential backoff (honouring any Retry-After header) before an error is raised. cache toggles the in-session response cache (see ox_clear_cache()).

Value

A named list of settings (current values, or the previous values invisibly when updating).

Examples

ox_settings()
old <- ox_settings(timeout = 300)
ox_settings(timeout = old$timeout) # restore

Description

Computes the minimum-weight path from from to to using Dijkstra's algorithm in the Rust core.

Usage

ox_shortest_path(g, from, to, weight = "length")

Arguments

Value

A vector of node osmids describing the path (length 0 if the target is unreachable).

Examples

g <- example_osm_graph()
from <- ox_nearest_nodes(g, 0, 0)
to <- ox_nearest_nodes(g, 300, 300)
ox_shortest_path(g, from, to)

Description

Removes interstitial (degree-2) nodes that merely shape the geometry of a street, merging each maximal chain of such nodes into a single edge whose geometry follows the original points and whose length is the sum of the merged segments. Only true endpoints and intersections are kept as nodes.

Usage

ox_simplify(g)

Arguments

Details

The topology walk is performed by the Rust core; geometry is rebuilt with sf. Downloaded graphs are unsimplified by default; this is the standard cleanup step before analysis.

Value

A simplified osm_graph (with meta$simplified = TRUE).

Examples

g <- example_osm_graph()
ox_simplify(g) # already simplified: returned unchanged

Description

Writes the graph's edges (or nodes) to a GeoJSON file via sf::st_write(). Geometry is transformed to EPSG:4326, the GeoJSON standard CRS.

Usage

ox_to_geojson(g, path, layer = c("edges", "nodes"))

Arguments

Value

path, invisibly.

Examples

g <- example_osm_graph()
ox_to_geojson(g, tempfile(fileext = ".geojson"))

Description

Writes the edges to a GeoJSON file and returns a MapLibre GL JS style fragment (a list with sources and layers) that references it, ready to merge into a map style. Serialize with, e.g., jsonlite::toJSON(..., auto_unbox = TRUE).

Usage

ox_to_maplibre(
  g,
  path,
  source_id = "osmnxr",
  layer_id = "streets",
  url = basename(path)
)

Arguments

Value

A named list with sources and layers, invisibly written data to path.

Examples

g <- example_osm_graph()
style <- ox_to_maplibre(g, tempfile(fileext = ".geojson"))
names(style)

Description

Combines two or more graphs into a single osm_graph. Node and edge tables are stacked; nodes sharing an osmid are merged (the first occurrence wins) and edges duplicated across graphs are dropped. Attribute columns present in one graph but not another are filled with NA.

Usage

ox_union(..., dedupe_edges = TRUE)

Arguments

Details

Nodes with the same osmid are treated as the same location, which is what stitches the graphs together: overlapping downloads share their OSM node ids, and a hand-built network (say, a metro layer) connects to a street graph wherever its edges reference street-node osmids. Custom networks should therefore use node ids that do not collide with OSM's except where a connection is intended (negative ids are a safe choice).

Value

An osm_graph. meta$network_type concatenates the distinct input types (e.g. "drive+walk"), meta$simplified is TRUE only if every input was simplified, and meta$union_of records how many graphs were combined.

Examples

g1 <- example_osm_graph(n = 3)

# a second, disjoint network with its own node ids
g2 <- example_osm_graph(n = 3)
g2$nodes$osmid <- g2$nodes$osmid + 1000
g2$edges$u <- g2$edges$u + 1000
g2$edges$v <- g2$edges$v + 1000

u <- ox_union(g1, g2)
u

# unioning overlapping graphs dedupes shared nodes and edges
nrow(ox_union(g1, g1)$edges) == nrow(g1$edges)

Description

Draws the street-network edges (and optionally nodes) using base sf plotting.

Usage

## S3 method for class 'osm_graph'
plot(x, nodes = FALSE, col = "#0d3b66", lwd = 0.7, ...)

Arguments

Value

Invisibly, the osm_graph.