BBBikeReader.read_gpkg

BBBikeReader.read_gpkg(subregion_name, layer_names=None, feature_names=None, data_dir=None, update=False, download=False, verbose=False, raise_error=True, **kwargs)[source]

Reads GeoPackage (.gpkg.zip) data for a specific subregion.

This method retrieves, downloads (optional), and parses OSM data in GeoPackage format. It supports selective layer loading and feature extraction, with automatic concatenation of related layers (e.g. merging multiple layers into a single key).

Parameters:

  • subregion_name (str) – Name of the subregion (e.g. ‘West Midlands’ or ‘london’).

  • layer_names (str | list | None) – Specific OSM layer(s) to load (e.g., ‘points’, ‘roads’); defaults to None (loads all available layers).

  • feature_names (str | list | None) – Specific feature type(s) to extract from the loaded layers (e.g., ‘residential’, ‘motorway’); defaults to None.

  • data_dir (str | os.PathLike | None) – Directory where the data file is stored or will be downloaded to; defaults to None.

  • update (bool) – Whether to update the local file by re-downloading it; defaults to False.

  • download (bool) – Whether to download the file if it is missing locally; defaults to False.

  • verbose (bool) – Whether to print progress messages to the console; defaults to False.

  • raise_error (bool) – Whether to raise an exception if an error occurs during parsing; defaults to True.

  • kwargs (Any) – Additional optional arguments for pyhelpers.store.load_geopackage().

Returns:

A GeoDataFrame (if a single layer is resolved) or a dictionary of GeoDataFrames (keyed by layer names).

Return type:

geopandas.GeoDataFrame | dict | None

Examples:

>>> from pydriosm.reader import GeofabrikReader
>>> from pyhelpers.dirs import delete_dir
>>> reader = GeofabrikReader()
>>> # Read 'railways' layer for Rutland
>>> data_dir = "tests/osm_data"
>>> rutland_railways = reader.read_gpkg(
...     subregion_name='Rutland',
...     layer_names='railways',
...     data_dir=data_dir,
...     download=True,
...     verbose=True)
Downloading "rutland-latest-free.gpkg.zip" 100%|██████████| 3.30M/3.30M | 4.5...
  Saving "rutland-latest-free.gpkg.zip" to "./tests/osm_data/rutland/" ... Done.
Parsing the data ... Done.
>>> type(rutland_railways)
dict
>>> list(rutland_railways.keys())
['railways']
>>> delete_dir(data_dir, verbose=True)
To delete the directory "./tests/osm_data/" (Not empty)
? [No]|Yes: yes
Deleting "./tests/osm_data/" ... Done.