pyrosm.find_extracts

Contents

pyrosm.find_extracts#

pyrosm.find_extracts(area, contains_only=False, update=False, directory=None, headers=None, timeout=60, opener=None, must_cover=None, progress=None)#

List the OSM extracts that overlap area, best download first, without downloading.

Compares Geofabrik extracts, BBBike city extracts and Movisda administrative areas and 1°/10° grid tiles. Extracts that contain the whole area (or must_cover when given) come first, then those that only overlap it; within each group the smallest download comes first. Extracts whose size cannot be read come last in their group, smallest extent first. With its default strategy="single", get_data_by_area() downloads the first extract that contains the area (or must_cover).

When Movisda’s indexes cannot be fetched and no copy is cached, its administrative areas are left out and its grid tiles come from the copy vendored with pyrosm, each with a warning.

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

  • contains_only (bool) – When True, list only the extracts that contain the whole area (or must_cover).

  • update (bool) – When True, refresh the provider indexes (Geofabrik’s index, BBBike’s list of cities and Movisda’s indexes) and the download sizes. When an index cannot be fetched, its cached copy, or else the copy vendored with pyrosm, is used with a warning.

  • directory (str, optional) – Directory for the cached provider indexes and download sizes. None (default) uses the pyrosm temp directory, as get_data_by_area() does.

  • headers (dict, optional) – Extra HTTP headers for the index and size requests, e.g. a User-Agent.

  • timeout (float | tuple) – Seconds to wait for a server, for the connect and each read, or a (connect, read) pair. Default 60.

  • opener (object, optional) – An object with open(request, timeout=...), e.g. from urllib.request.build_opener(), that makes the requests instead of pyrosm.

  • must_cover (shapely geometry | GeoDataFrame | GeoSeries, optional) – What an extract must contain, in place of the whole area, e.g. the transit stops that routing needs. Any geometry type; points and lines must be contained exactly. Extracts that only reach it (not the area) are listed too. 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.

  • progress (bool | callable | None) – None (default) follows pyrosm.enable_logging(), which is True unless set. True shows a bar “Finding the extracts” on stderr once the search has run 2 seconds, from 0 to 100 % while the extract indexes are downloaded on first use and the sizes are read, False shows nothing, and a callable is called as progress(done, 100) with the percentage done.

Returns:

One row per extract with the columns provider ("Geofabrik", "BBBike" or "Movisda"), id, name, url, bytes (the download size, <NA> when it cannot be read), contains (whether the extract contains the whole area, or must_cover when given) and geometry (the extract’s extent, EPSG:4326).

Return type:

GeoDataFrame

Raises:

ValueError – If the area is empty, or has no width or no height, or must_cover is empty, or progress is not True, False, None or a callable.

Contents