GeofabrikDownloader.download_osm_data

GeofabrikDownloader.download_osm_data(subregion_names, osm_file_format, download_dir=None, update=False, confirmation_required=True, deep_retry=False, interval=None, verify_download_dir=True, verbose=False, ret_download_path=False, **kwargs)

Download OSM data (in a specific format) of one (or multiple) geographic (sub)region(s).

Parameters:

• subregion_names (str | list) – name of a geographic (sub)region (or names of multiple geographic (sub)regions) available on Geofabrik free download server

• osm_file_format (str) – file format/extension of the OSM data available on the download server

• download_dir (str | None) – directory for saving the downloaded file(s), defaults to None; when download_dir=None, it refers to the method cdd()

• update (bool) – whether to update the data if it already exists, defaults to False

• confirmation_required (bool) – whether asking for confirmation to proceed, defaults to True

• deep_retry (bool) – whether to further check availability of sub-subregions data, defaults to False

• interval (int | float | None) – interval (in sec) between downloading two subregions, defaults to None

• verify_download_dir (bool) – whether to verify the pathname of the current download directory, defaults to True

• verbose (bool | int) – whether to print relevant information in console, defaults to False

• ret_download_path (bool) – whether to return the path(s) to the downloaded file(s), defaults to False

• kwargs – optional parameters of pyhelpers.ops.download_file_from_url()

Returns:

absolute path(s) to downloaded file(s) when ret_download_path is True

Return type:

list | str

Examples:

>>> from pydriosm.downloader import GeofabrikDownloader
>>> from pyhelpers.dirs import delete_dir
>>> import os

*Example 1*:

>>> gfd = GeofabrikDownloader()

>>> # Download PBF data file of 'Greater London' and 'Rutland'
>>> subrgn_names = ['london', 'rutland']  # Case-insensitive
>>> file_format = ".pbf"

>>> gfd.download_osm_data(subrgn_names, file_format, verbose=True)
To download .osm.pbf data of the following geographic (sub)region(s):
    Greater London
    Rutland
? [No]|Yes: yes
Downloading "greater-london-latest.osm.pbf"
    to "osm_data\geofabrik\europe\great-britain\england\greater-london\" ... Done.
Downloading "rutland-latest.osm.pbf"
    to "osm_data\geofabrik\europe\great-britain\england\rutland\" ... Done.

>>> len(gfd.data_paths)
2
>>> for fp in gfd.data_paths: print(os.path.basename(fp))
greater-london-latest.osm.pbf
rutland-latest.osm.pbf

>>> # Since `download_dir` was not specified when instantiating the class,
>>> #   the data is now in the default download directory
>>> os.path.relpath(gfd.download_dir)
'osm_data\geofabrik'
>>> dwnld_dir = os.path.dirname(gfd.download_dir)

>>> # Download shapefiles of West Midlands (to a given directory "tests\osm_data")
>>> region_name = 'west midlands'  # Case-insensitive
>>> file_format = ".shp"
>>> new_dwnld_dir = "tests\osm_data"

>>> gfd.download_osm_data(region_name, file_format, new_dwnld_dir, verbose=True)
To download .shp.zip data of the following geographic (sub)region(s):
    West Midlands
? [No]|Yes: yes
Downloading "west-midlands-latest-free.shp.zip"
    to "tests\osm_data\west-midlands\" ... Done.
>>> len(gfd.data_paths)
3
>>> os.path.relpath(gfd.data_paths[-1])
'tests\osm_data\west-midlands\west-midlands-latest-free.shp.zip'

>>> # Now the `.download_dir` variable has changed to the given one
>>> os.path.relpath(gfd.download_dir) == new_dwnld_dir
True
>>> # while the `.cdd()` remains the default one
>>> os.path.relpath(gfd.cdd())
'osm_data\geofabrik'

>>> # Delete the above downloaded directories
>>> delete_dir([dwnld_dir, new_dwnld_dir], verbose=True)
To delete the following directories:
    "osm_data\" (Not empty)
    "tests\osm_data\" (Not empty)
? [No]|Yes: yes
Deleting "osm_data\" ... Done.
Deleting "tests\osm_data\" ... Done.

*Example 2*:

>>> # Create a new instance with a pre-specified download directory
>>> gfd = GeofabrikDownloader(download_dir="tests\osm_data")

>>> os.path.relpath(gfd.download_dir)
'tests\osm_data'

>>> # Download shapefiles of Great Britain (to the directory specified by instantiation)
>>> # (Note that .shp.zip data is not available for "Great Britain" for free download.)
>>> region_name = 'Great Britain'  # Case-insensitive
>>> file_format = ".shp"

>>> # By default, `deep_retry=False`
>>> gfd.download_osm_data(region_name, osm_file_format=file_format, verbose=True)
To download .shp.zip data of the following geographic (sub)region(s):
    Great Britain
? [No]|Yes: yes
No .shp.zip data is found for "Great Britain".
Try to download the data of its subregions instead
? [No]|Yes: yes
Downloading "england-latest-free.shp.zip"
    to "tests\osm_data\europe\great-britain\great-britain-shp-zip\" ... Done.
Downloading "scotland-latest-free.shp.zip"
    to "tests\osm_data\europe\great-britain\great-britain-shp-zip\" ... Done.
Downloading "wales-latest-free.shp.zip"
    to "tests\osm_data\europe\great-britain\great-britain-shp-zip\" ... Done.

>>> len(gfd.data_paths)
3

>>> # Now set `deep_retry=True`
>>> gfd.download_osm_data(region_name, file_format, verbose=True, deep_retry=True)
To download .shp.zip data of the following geographic (sub)region(s):
    Great Britain
? [No]|Yes: yes
No .shp.zip data is found for "Great Britain".
Try to download the data of its subregions instead
? [No]|Yes: yes
"scotland-latest-free.shp.zip" is already available at "tests\osm_data\europ...".
"wales-latest-free.shp.zip" is already available at "tests\osm_data\europe\...".
Downloading "bedfordshire-latest-free.shp.zip"
    to "tests\osm_data\europe\great-britain\great-britain-shp-zip\" ... Done.
...     ...
Downloading "west-yorkshire-latest-free.shp.zip"
    to "tests\osm_data\europe\great-britain\great-britain-shp-zip\" ... Done.
Downloading "wiltshire-latest-free.shp.zip"
    to "tests\osm_data\europe\great-britain\great-britain-shp-zip\" ... Done.
Downloading "worcestershire-latest-free.shp.zip"
    to "tests\osm_data\europe\great-britain\great-britain-shp-zip\" ... Done.

>>> # Check the file paths
>>> len(gfd.data_paths)
50
>>> # Check the current default `download_dir`
>>> os.path.relpath(gfd.download_dir)
'tests\osm_data'
>>> os.path.relpath(os.path.commonpath(gfd.data_paths))
'tests\osm_data\europe\great-britain\great-britain-shp-zip'

>>> # Delete all the downloaded files
>>> delete_dir(gfd.download_dir, verbose=True)
To delete the directory "tests\osm_data\" (Not empty)
? [No]|Yes: yes
Deleting "tests\osm_data\" ... Done.