GeofabrikReader.read_osm_pbf

GeofabrikReader.read_osm_pbf(subregion_name, data_dir=None, chunk_size_limit=50, parse_raw_feat=False, transform_geom=False, transform_other_tags=False, update=False, download_confirmation_required=True, pickle_it=False, ret_pickle_path=False, rm_osm_pbf=False, verbose=False, **kwargs)

Read a PBF (.osm.pbf) data file of a geographic region.

Parameters

  • subregion_name (str) – name of a geographic region (case-insensitive) that is available on Geofabrik free download server

  • data_dir (str or None) – directory where the .osm.pbf data file is located/saved; if None, the default local directory

  • chunk_size_limit (int) – threshold (in MB) that triggers the use of chunk parser, defaults to 50; if the size of the .osm.pbf file (in MB) is greater than chunk_size_limit, it will be parsed in a chunk-wise way

  • parse_raw_feat (bool) – whether to parse each feature in the raw data, defaults to False

  • transform_geom (bool) – whether to transform a single coordinate (or a collection of coordinates) into a geometric object, defaults to False

  • transform_other_tags (bool) – whether to transform a 'other_tags' into a dictionary, defaults to False

  • update (bool) – whether to check to update pickle backup (if available), defaults to False

  • download_confirmation_required (bool) – whether to ask for confirmation before starting to download a file, defaults to True

  • pickle_it (bool) – whether to save the .pbf data as a .pickle file, defaults to False

  • ret_pickle_path (bool) – (when pickle_it=True) whether to return a path to the saved pickle file

  • rm_osm_pbf (bool) – whether to delete the downloaded .osm.pbf file, defaults to False

  • verbose (bool or int) – whether to print relevant information in console as the function runs, defaults to False

  • kwargs – optional parameters of parse_osm_pbf()

Returns

dictionary of the .osm.pbf data; when pickle_it=True, return a tuple of the dictionary and a path to the pickle file

Return type

dict or tuple or None

Examples:

>>> import os
>>> from pydriosm.reader import GeofabrikReader

>>> geofabrik_reader = GeofabrikReader()

>>> sr_name = 'Rutland'
>>> dat_dir = "tests"

>>> # If the PBF data of Rutland is not available at the specified data directory,
>>> # the function may ask whether to download the latest data
>>> rutland_pbf_raw = geofabrik_reader.read_osm_pbf(sr_name, dat_dir, verbose=True)
To download .osm.pbf data of the following geographic region(s):
    Rutland
? [No]|Yes: yes
Downloading "rutland-latest.osm.pbf" to "tests\" ... Done.

>>> list(rutland_pbf_raw.keys())
['points', 'lines', 'multilinestrings', 'multipolygons', 'other_relations']

>>> rutland_pbf_raw_points = rutland_pbf_raw['points']
>>> rutland_pbf_raw_points.head()
                                              points
0  {"type": "Feature", "geometry": {"type": "Poin...
1  {"type": "Feature", "geometry": {"type": "Poin...
2  {"type": "Feature", "geometry": {"type": "Poin...
3  {"type": "Feature", "geometry": {"type": "Poin...
4  {"type": "Feature", "geometry": {"type": "Poin...

>>> # Set `parse_raw_feat` to be True
>>> rutland_pbf_parsed = geofabrik_reader.read_osm_pbf(sr_name, dat_dir,
...                                                    parse_raw_feat=True,
...                                                    verbose=True)
Parsing "tests\rutland-latest.osm.pbf" ... Done.

>>> rutland_pbf_parsed_points = rutland_pbf_parsed['points']
>>> rutland_pbf_parsed_points.head()
         id               coordinates  ...                    other_tags
0    488432  [-0.5134241, 52.6555853]  ...               "odbl"=>"clean"
1    488658  [-0.5313354, 52.6737716]  ...                          None
2  13883868  [-0.7229332, 52.5889864]  ...                          None
3  14049101  [-0.7249922, 52.6748223]  ...  "traffic_calming"=>"cushion"
4  14558402  [-0.7266686, 52.6695051]  ...      "direction"=>"clockwise"
[5 rows x 12 columns]

>>> # Set both `parse_raw_feat` and `transform_geom` to be True
>>> rutland_pbf_parsed_1 = geofabrik_reader.read_osm_pbf(sr_name, dat_dir,
...                                                      parse_raw_feat=True,
...                                                      transform_geom=True,
...                                                      verbose=True)
Parsing "tests\rutland-latest.osm.pbf" ... Done.

>>> rutland_pbf_parsed_1_points = rutland_pbf_parsed_1['points']
>>> rutland_pbf_parsed_1_points[['coordinates', 'other_tags']].head()
                              coordinates                    other_tags
0           POINT (-0.5134241 52.6555853)               "odbl"=>"clean"
1           POINT (-0.5313354 52.6737716)                          None
2  POINT (-0.7229332000000001 52.5889864)                          None
3           POINT (-0.7249816 52.6748426)  "traffic_calming"=>"cushion"
4           POINT (-0.7266581 52.6695058)      "direction"=>"clockwise"

>>> # Set `parse_raw_feat` `transform_geom` and `transform_other_tags` to be True
>>> rutland_pbf_parsed_2 = geofabrik_reader.read_osm_pbf(sr_name, dat_dir,
...                                                      parse_raw_feat=True,
...                                                      transform_geom=True,
...                                                      transform_other_tags=True,
...                                                      verbose=True)
Parsing "tests\rutland-latest.osm.pbf" ... Done.

>>> rutland_pbf_parsed_2_points = rutland_pbf_parsed_2['points']
>>> rutland_pbf_parsed_2_points[['coordinates', 'other_tags']].head()
                              coordinates                      other_tags
0           POINT (-0.5134241 52.6555853)               {'odbl': 'clean'}
1           POINT (-0.5313354 52.6737716)                            None
2  POINT (-0.7229332000000001 52.5889864)                            None
3           POINT (-0.7249816 52.6748426)  {'traffic_calming': 'cushion'}
4           POINT (-0.7266581 52.6695058)      {'direction': 'clockwise'}

>>> # Delete the downloaded PBF data file
>>> os.remove(os.path.join(dat_dir, "rutland-latest.osm.pbf"))