API reference

The OSM class is the main entry point: construct it once from a PBF file, then call a feature method to read a layer into a GeoDataFrame, export a network to a graph, or write data back to PBF. Module-level helpers download PBF extracts and simplify graphs.

OSM reader

Constructor

OSM(filepath[, bounding_box, keep_metadata, ...])

OpenStreetMap PBF reader object.

Reading OSM features

OSM.get_network([network_type, ...])	Parses street networks from OSM for walking, driving, and cycling.
OSM.get_buildings([custom_filter, ...])	Parses buildings from OSM: the building ways and relations, and with keep_nodes the buildings mapped as single nodes.
OSM.get_pois([custom_filter, ...])	Parse Point of Interest (POI) from OSM.
OSM.get_landuse([custom_filter, ...])	Parses landuse from OSM.
OSM.get_natural([custom_filter, ...])	Parses natural from OSM.
OSM.get_boundaries([boundary_type, name, ...])	Parses boundaries from OSM.
OSM.get_data_by_custom_criteria([...])	Parse OSM data based on custom criteria.

Exporting to a graph

OSM.get_graph([network_type, graph_type, ...])	Read the street network of network_type as a routable graph: the graph of OSM.to_graph(*osm.get_network(network_type, nodes=True), graph_type).
OSM.to_graph(nodes, edges[, graph_type, ...])	Export OSM network to routable graph.

Saving, cropping and merging PBF files

OSM.to_pbf([output_path, keep_relations, ...])	Crop the source PBF by this object's bounding_box and write a valid, re-readable *.osm.pbf to disk.
OSM.write_pbf(data, output_path[, ...])	Write the OSM data this object holds back to a valid, re-readable *.osm.pbf, applying attribute/tag edits from a (modified) GeoDataFrame.
merge_pbf(inputs[, output_path, ...])	Merge overlapping *.osm.pbf extracts into one PBF, optionally cropped to a bounding box or a polygon.

Cache and downloads

OSM.list_cache([filepath])	List the out-of-core engine's cached layer files -- the GeoParquet files that engine="out_of_core" reads write under <tempdir>/pyrosm/cache.
OSM.list_downloads()	List the PBF files downloaded by get_data in the default download directory (<tempdir>/pyrosm).
OSM.clear_cache([filepath])	Remove the out-of-core engine's result cache -- the GeoParquet files that engine="out_of_core" reads write under <tempdir>/pyrosm/cache.
OSM.clear_downloads([filepath])	Remove PBF files downloaded or cropped into the default download directory (<tempdir>/pyrosm), with the partial files that interrupted downloads leave and the records kept beside crops.

Downloading data

get_data(dataset[, update, directory, ...])	Get the path to a PBF data file, and download the data if needed.
find_extracts(area[, contains_only, update, ...])	List the OSM extracts that overlap area, best download first, without downloading.
get_data_by_area(area[, crop, update, ...])	Download the OSM data for area: the smallest single extract that contains it, or a smaller set of extracts merged into one file.
get_data_by_bbox(bbox[, crop, download, ...])	Download (and by default crop) the OSM data covering a bounding box.
geocode(query[, polygon, base_url, ...])	Geocode a place name to a Shapely polygon via Nominatim.
get_data_by_geocoding(query[, crop, ...])	Download (and by default crop) the OSM data for a geocoded place name.

Logging

enable_logging([level, to_file, progress])

Show pyrosm's log messages, and set how every operation shows its progress.

Exceptions

ExtractNotFoundError	No Geofabrik, BBBike or Movisda extract contains the requested area.
ExtractDownloadError(message[, failed, url, ...])	No extract that contains the requested area could be downloaded.
DownloadError(message[, failed, url, ...])	A file could not be downloaded, after retrying network errors and HTTP status 408, 425, 429 and 5xx.
InvalidOSMFileError	The file is not a readable OSM PBF file, for example because it is truncated or another format; the message names the file.
PBFNotImplemented	The PBF file requires a feature pyrosm does not support, such as node locations stored on ways; the message names the file and the feature.
PBFException	Base class of the errors about the content of a PBF file.

Graph simplification

simplify_graph(nodes, directed_edges, *[, ...])

Topologically simplify pyrosm's directed graph-export edges.

Graph tables

graph_tables(nodes, edges[, direction, ...])

The nodes and edges of a graph as GeoDataFrames, as the graph exporters build it: the edges directed (see get_directed_edges()), unless retain_all only their largest connected part kept, and simplified when simplify, as when the connected part is kept before simplifying (as OSMnx does).

Recipes

validate(path)	Check a recipe file without running it and return it resolved.
run(path[, out_dir, force])	Run a recipe and write its outputs and provenance record; returns their paths.