pyrosm.get_data_by_area

pyrosm.get_data_by_area#

pyrosm.get_data_by_area(area, crop=True, update=False, directory=None, output_path=None, headers=None, timeout=60, opener=None, strategy='single', must_cover=None, workers=None, progress=None)#

Download the OSM data for area: the smallest single extract that contains it, or a smaller set of extracts merged into one file.

Compares Geofabrik extracts, BBBike city extracts and Movisda administrative areas and 1°/10° grid tiles, keeps those that contain the whole area (or must_cover when given), and downloads the one with the smallest file (the first row of find_extracts(area, contains_only=True, must_cover=must_cover), which shows the choice without downloading). With strategy="smallest_total" it may instead download several extracts that together cover the area and merge them into one file (see strategy). A download that fails with a network error or HTTP status 408, 425, 429 or 5xx is tried up to three times, waiting 1 s, 2 s or the server’s Retry-After in between; when it still fails, the choice is made again without it. By default the file is then cropped to the area’s bounding box, or with crop="polygon" to the area itself.

Movisda cuts its extracts exactly at their edges, so features crossing the edge of a Movisda extract are clipped or missing there: open ways such as streets are cut at the edge and kept. A grid tile can leave out a whole closed way that crosses its edge, such as a building or a land-use area, including its part inside the area. To keep a grid tile’s edges at least N metres outside the area, pass the area buffered by N metres (in a local metric CRS) as must_cover. In a merged set the Movisda extract goes last, so where another extract holds a complete copy of such a feature, that copy is kept.

Parameters:

  • area (shapely geometry | GeoDataFrame | GeoSeries | list | tuple | numpy.ndarray) – The area of interest in lon/lat: a (Multi)Polygon, a GeoDataFrame/GeoSeries (its geometries are combined) or [minx, miny, maxx, maxy].

  • crop (bool or "polygon") – When True (default), crop the extract to the area’s bounding box and return the cropped file, named bbox_<minx>_<miny>_<maxx>_<maxy>.osm.pbf. With "polygon", crop it to the area itself, which must be a (Multi)Polygon: a node is kept when it lies inside the area or on its boundary, and a way that has a kept node is kept whole. The file is named area_<hash of the area>.osm.pbf. A cropped file of these names is used again instead of cropping anew while it and the extracts it was cropped from are unchanged. When False, return the full extract.

  • update (bool) – When True, re-download the extract, refresh the provider indexes and sizes, and crop again.

  • directory (str, optional) – Directory for the downloads, the provider indexes and the cropped file. None (default) uses a pyrosm temp directory.

  • output_path (str, optional) – Path for the file pyrosm writes (overrides the automatic name), cropped anew on every call: the cropped file, or with crop=False a copy of the extract (a hard link where the file system allows one) or the merged file of a "smallest_total" set.

  • headers – Network options for the index, size and download requests, as for find_extracts().

  • timeout – Network options for the index, size and download requests, as for find_extracts().

  • opener – Network options for the index, size and download requests, as for find_extracts().

  • strategy (str) – "single" (default): the smallest extract that contains the area. "smallest_total": when extracts that together cover the area are smaller in total than that extract (or its size is unknown), download those and merge them with pyrosm.merge_pbf(). The set is found greedily (lowest size per area newly covered), so it is small but not guaranteed to be the smallest possible. Geofabrik, BBBike and Movisda administrative extracts may be combined, at most one of them from Movisda, which goes last in the merge; Movisda grid tiles are never combined. With crop=False the merged file is named merged_<hash of the URLs>.osm.pbf.

  • must_cover (shapely geometry | GeoDataFrame | GeoSeries, optional) – What the download must cover, in place of the whole area, e.g. the transit stops that routing needs, so sea or unserved edges of the area do not force a larger extract. Points and lines are covered exactly, polygons except for less than 1 m². To also require the streets around each stop, pass the stops buffered in a local metric CRS, e.g. stops.to_crs(stops.estimate_utm_crs()).buffer(300), or a hull of them to require the streets between stops as well. A GeoDataFrame or GeoSeries in another CRS is reprojected to lon/lat. The crop still follows area, so parts of must_cover outside it are cropped away.

  • workers (int | str) – Number of threads that crop (and merge) the downloaded file. By default (None, as "auto") the count is chosen as an out-of-core read does for the file’s size; 1 runs sequentially. More workers are used only for a file with at least 2 * workers data blocks, and the written file is the same for every value. With crop=False and a single extract nothing is cropped, so it has no effect. With PYROSM_DECODE_BACKEND=processes they are worker processes, one by default; on macOS and Windows each starts by importing the script, so a script that passes workers="auto" or workers > 1 then needs the if __name__ == "__main__": guard; without it, or for a script read from stdin, the work runs in one process with a warning.

  • progress (bool | callable | None) – None (default) follows pyrosm.enable_logging(), which is True unless set. True shows the download as a bar on stderr, a widget in Jupyter when ipywidgets is installed (pip install "pyrosm[notebook]"); without a terminal, only a line naming the file is printed. False shows nothing. A callable is called as progress(written, total) after each chunk of each download, with the bytes written so far and the file size, None when the server does not give it. The search for the extracts and the crop or merge show their progress the same way; a callable is then called with the percentage of the search (see find_extracts()) or of the crop or merge done (see pyrosm.merge_pbf()).

Returns:

The file path and the extract it came from; usable as a path.

Return type:

AreaExtract

Raises:

  • ValueError – If the area is empty, or has no width or no height, or must_cover is empty, or crop is a string other than "polygon", or crop="polygon" and the area is not a (Multi)Polygon, or workers is neither an integer of at least 1 nor "auto".

  • pyrosm.exceptions.ExtractNotFoundError – If no extract (or set of extracts) contains the whole area, or must_cover when given (a ValueError subclass).

  • pyrosm.exceptions.ExtractDownloadError – If every extract that contains the area failed to download; its errors hold the DownloadError of each extract tried.