GeofabrikDownloader.download_subregion_data

GeofabrikDownloader.download_subregion_data(subregion_names, osm_file_format, download_dir=None, deep=False, ret_download_path=False, **kwargs)

Download OSM data (in a specific file format) of all subregions (if available) for one (or multiple) geographic (sub)region(s).

If no subregion data is available for the region(s) specified by subregion_names, then the data of subregion_names would be downloaded only.

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()

• deep (bool) – whether to try to search for subregions of subregion(s), 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 pydriosm.GeofabrikDownloader.download_osm_data()

Returns:

the path(s) to the downloaded file(s) when ret_download_path=True

Return type:

list | str

Examples:

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

>>> gfd = GeofabrikDownloader()

>>> subrgn_names = ['rutland', 'west yorkshire']
>>> file_format = ".pbf"
>>> dwnld_dir = "tests\osm_data"

>>> gfd.download_subregion_data(subrgn_names, file_format, dwnld_dir, verbose=True)
To download .osm.pbf data of the following geographic (sub)region(s):
    Rutland
    West Yorkshire
? [No]|Yes: yes
Downloading "rutland-latest.osm.pbf"
    to "tests\osm_data\rutland\" ... Done.
Downloading "west-yorkshire-latest.osm.pbf"
    to "tests\osm_data\west-yorkshire\" ... Done.

>>> len(gfd.data_paths)
2
>>> for fp in gfd.data_paths: print(os.path.relpath(fp))
tests\osm_data\rutland\rutland-latest.osm.pbf
tests\osm_data\west-yorkshire\west-yorkshire-latest.osm.pbf

>>> # Delete "tests\osm_data\rutland-latest.osm.pbf"
>>> rutland_dir = os.path.dirname(gfd.data_paths[0])
>>> delete_dir(rutland_dir, confirmation_required=False, verbose=True)
Deleting "tests\osm_data\rutland\" ... Done.

>>> # Try to download data given another list which also includes 'West Yorkshire'
>>> subrgn_names = ['west midlands', 'west yorkshire']

>>> # Set `ret_download_path=True`
>>> dwnld_file_pathnames = gfd.download_subregion_data(
...     subrgn_names, file_format, dwnld_dir, verbose=True, ret_download_path=True)
"west-midlands-latest.osm.pbf" is already available
    at "tests\osm_data\west-midlands\".
To download .osm.pbf data of the following geographic (sub)region(s):
    West Midlands
? [No]|Yes: yes
Downloading "west-midlands-latest.osm.pbf"
    to "tests\osm_data\west-midlands\" ... Done.

>>> len(gfd.data_paths)  # The pathname of the newly downloaded file is added
3
>>> len(dwnld_file_pathnames)
2
>>> for fp in dwnld_file_pathnames: print(os.path.relpath(fp))
tests\osm_data\west-midlands\west-midlands-latest.osm.pbf
tests\osm_data\west-yorkshire\west-yorkshire-latest.osm.pbf

>>> # Update (or re-download) the existing data file by setting `update=True`
>>> gfd.download_subregion_data(
...     subrgn_names, file_format, download_dir=dwnld_dir, update=True, verbose=True)
"west-midlands-latest.osm.pbf" is already available
    at "tests\osm_data\west-midlands\".
"west-yorkshire-latest.osm.pbf" is already available
    at "tests\osm_data\west-yorkshire\".
To update the .osm.pbf data of the following geographic (sub)region(s):
    West Midlands
    West Yorkshire
? [No]|Yes: yes
Updating "west-midlands-latest.osm.pbf"
    at "tests\osm_data\west-midlands\" ... Done.
Updating "west-yorkshire-latest.osm.pbf"
    at "tests\osm_data\west-yorkshire\" ... Done.

>>> # To download the PBF data of all available subregions of England
>>> subrgn_name = 'England'

>>> dwnld_file_pathnames = gfd.download_subregion_data(
...     subrgn_name, file_format, download_dir=dwnld_dir, update=True, verbose=True,
...     ret_download_path=True)
"west-midlands-latest.osm.pbf" is already available
    at "tests\osm_data\west-midlands\".
"west-yorkshire-latest.osm.pbf" is already available
    at "tests\osm_data\west-yorkshire\".
To download/update the .osm.pbf data of the following geographic (sub)region(s):
    Bedfordshire
    Berkshire
    Bristol
    ...
    West Midlands
    ...
    West Yorkshire
    Wiltshire
    Worcestershire
? [No]|Yes: yes
Downloading "bedfordshire-latest.osm.pbf"
    to "tests\osm_data\bedfordshire\" ... Done.
Downloading "berkshire-latest.osm.pbf"
    to "tests\osm_data\berkshire\" ... Done.
Downloading "bristol-latest.osm.pbf"
    to "tests\osm_data\bristol\" ... Done.
...
    ...
Updating "west-midlands-latest.osm.pbf"
    at "tests\osm_data\west-midlands\" ... Done.
...
    ...
Updating "west-yorkshire-latest.osm.pbf"
    at "tests\osm_data\west-yorkshire\" ... Done.
Downloading "wiltshire-latest.osm.pbf"
    to "tests\osm_data\wiltshire\" ... Done.
Downloading "worcestershire-latest.osm.pbf"
    to "tests\osm_data\worcestershire\" ... Done.

>>> len(dwnld_file_pathnames)
47
>>> os.path.commonpath(dwnld_file_pathnames) == gfd.download_dir
True

>>> # Delete the download directory and 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.