QuackOSM Basic Usage¶
QuackOSM exposes some basic functions in the main Python module. Full documentation for them is available here.
This notebook will show how to use the library in a few simple scenarios.
To learn more about CLI usage, see this page. The help page for the CLI is available here.
To learn more details about PbfFileReader class, see this page, or documentation page.
Run this notebook in Google Colab:
Remember to install the quackosm library before running the notebook:
%pip install quackosm[cli]
In [1]:
Copied!
import quackosm as qosm
import quackosm as qosm
Reading existing PBF file to GeoDataFrame¶
In [2]:
Copied!
qosm.convert_pbf_to_geodataframe("https://download.geofabrik.de/europe/monaco-latest.osm.pbf")
qosm.convert_pbf_to_geodataframe("https://download.geofabrik.de/europe/monaco-latest.osm.pbf")
Out[2]:
| tags | geometry | |
|---|---|---|
| feature_id | ||
| node/1097207537 | {'leaf_type': 'broadleaved', 'natural': 'tree'} | POINT (7.42768 43.74229) |
| node/1097207541 | {'leaf_type': 'broadleaved', 'natural': 'tree'} | POINT (7.42782 43.74251) |
| node/1097219229 | {'natural': 'tree'} | POINT (7.41853 43.73709) |
| node/1097219236 | {'natural': 'tree'} | POINT (7.41905 43.7369) |
| node/1097219254 | {'natural': 'tree'} | POINT (7.41305 43.73264) |
| ... | ... | ... |
| node/6482464699 | {'amenity': 'vending_machine', 'indoor': 'yes'... | POINT (7.41687 43.73125) |
| node/6482464700 | {'amenity': 'atm', 'indoor': 'yes', 'level': '0'} | POINT (7.41701 43.73124) |
| node/6482464709 | {'highway': 'elevator', 'indoor': 'yes'} | POINT (7.41686 43.7313) |
| node/6482464710 | {'highway': 'elevator', 'indoor': 'yes'} | POINT (7.41684 43.73129) |
| node/6482464712 | {'amenity': 'parking_entrance'} | POINT (7.41788 43.73085) |
9290 rows × 2 columns
Transforming existing PBF file to GeoParquet¶
In [3]:
Copied!
qosm.convert_pbf_to_parquet("https://download.geofabrik.de/europe/monaco-latest.osm.pbf")
qosm.convert_pbf_to_parquet("https://download.geofabrik.de/europe/monaco-latest.osm.pbf")
Out[3]:
PosixPath('files/monaco-latest_nofilter_noclip_compact.parquet')
In [4]:
Copied!
qosm.convert_osm_extract_to_geodataframe("Vatican City")
qosm.convert_osm_extract_to_geodataframe("Vatican City")
Out[4]:
| tags | geometry | |
|---|---|---|
| feature_id | ||
| node/1398913876 | {'barrier': 'lift_gate', 'foot': 'yes'} | POINT (12.4457 41.9042) |
| node/1398913892 | {'barrier': 'gate'} | POINT (12.44479 41.9044) |
| node/1402282620 | {'addr:housenumber': '15', 'addr:street': 'Vic... | POINT (12.45357 41.89592) |
| node/1405099351 | {'historic': 'wayside_shrine', 'name': 'Ave Ma... | POINT (12.45243 41.89687) |
| node/1410071558 | {'bench': 'no', 'bin': 'no', 'bus': 'yes', 'hi... | POINT (12.45143 41.89973) |
| ... | ... | ... |
| relation/11839271 | {'building': 'yes', 'type': 'multipolygon'} | POLYGON ((12.44939 41.89759, 12.44953 41.89757... |
| relation/13399080 | {'highway': 'pedestrian', 'lit': 'yes', 'name'... | POLYGON ((12.45775 41.90339, 12.45776 41.90354... |
| relation/15843461 | {'artwork_type': 'architecture', 'surface': 'p... | POLYGON ((12.45807 41.90213, 12.45806 41.90207... |
| relation/15846626 | {'building': 'apartments', 'type': 'multipolyg... | POLYGON ((12.45946 41.90431, 12.4594 41.9039, ... |
| relation/1535934 | {'building': 'yes', 'type': 'multipolygon'} | POLYGON ((12.45942 41.89792, 12.45948 41.89793... |
8452 rows × 2 columns
Find an OSM PBF extract file using text and transform it to a GeoParquet¶
In [5]:
Copied!
qosm.convert_osm_extract_to_parquet("Vatican City")
qosm.convert_osm_extract_to_parquet("Vatican City")
Out[5]:
PosixPath('files/osmfr_europe_vatican_city_nofilter_noclip_compact.parquet')
Get OSM data for a given geometry as a GeoDataFrame¶
In [6]:
Copied!
area = qosm.geocode_to_geometry('Shibuya, Tokyo')
qosm.convert_geometry_to_geodataframe(area)
area = qosm.geocode_to_geometry('Shibuya, Tokyo')
qosm.convert_geometry_to_geodataframe(area)
Finished operation in 0:01:31
Out[6]:
| tags | geometry | |
|---|---|---|
| feature_id | ||
| node/1655899990 | {'amenity': 'social_facility', 'name': 'セントラルホ... | POINT (139.6901 35.65917) |
| node/1655900305 | {'amenity': 'social_facility', 'name': 'パール在宅介... | POINT (139.69866 35.65277) |
| node/1655900398 | {'KSJ2:ADS': '笹塚2-33-11', 'KSJ2:AdminArea': '東... | POINT (139.66416 35.67518) |
| node/1655901181 | {'man_made': 'tower', 'tower:type': 'communica... | POINT (139.70312 35.68439) |
| node/1655902442 | {'KSJ2:ADS': '上原1-18-6', 'KSJ2:AdminArea': '東京... | POINT (139.68283 35.66913) |
| ... | ... | ... |
| relation/18455776 | {'building': 'yes', 'name': 'アーバンパークグランデ代官山', ... | POLYGON ((139.69619 35.65196, 139.69622 35.651... |
| relation/18215888 | {'admin_level': '10', 'boundary': 'administrat... | POLYGON ((139.71339 35.65867, 139.71356 35.659... |
| relation/18423038 | {'admin_level': '10', 'boundary': 'administrat... | POLYGON ((139.70623 35.63806, 139.70642 35.638... |
| relation/18447134 | {'admin_level': '10', 'boundary': 'administrat... | POLYGON ((139.68961 35.65263, 139.68984 35.652... |
| relation/18450401 | {'admin_level': '10', 'boundary': 'administrat... | POLYGON ((139.67495 35.66411, 139.6748 35.6639... |
50042 rows × 2 columns
Save OSM data for a given geometry as a GeoParquet¶
In [7]:
Copied!
qosm.convert_geometry_to_parquet(area)
qosm.convert_geometry_to_parquet(area)
Out[7]:
PosixPath('files/3c3cbc50_nofilter_compact.parquet')
More advanced examples¶
Filter out data based on geometry from existing PBF file¶
In [8]:
Copied!
area = qosm.geocode_to_geometry("Monaco-Ville, Monaco")
gdf = qosm.convert_pbf_to_geodataframe(
"https://download.geofabrik.de/europe/monaco-latest.osm.pbf", geometry_filter=area
)
gdf
area = qosm.geocode_to_geometry("Monaco-Ville, Monaco")
gdf = qosm.convert_pbf_to_geodataframe(
"https://download.geofabrik.de/europe/monaco-latest.osm.pbf", geometry_filter=area
)
gdf
Finished operation in 0:00:15
Out[8]:
| tags | geometry | |
|---|---|---|
| feature_id | ||
| node/25181806 | {'crossing': 'uncontrolled', 'crossing_ref': '... | POINT (7.42238 43.72994) |
| node/25181829 | {'crossing': 'uncontrolled', 'crossing_ref': '... | POINT (7.4228 43.72985) |
| node/25191432 | {'access': 'yes', 'addr:country': 'MC', 'ameni... | POINT (7.42711 43.73128) |
| node/25193663 | {'crossing': 'marked', 'crossing:markings': 'y... | POINT (7.4201 43.73228) |
| node/256411950 | {'crossing': 'uncontrolled', 'crossing_ref': '... | POINT (7.42223 43.73004) |
| ... | ... | ... |
| relation/2221178 | {'ISO3166-2': 'MC-CO', 'admin_level': '10', 'b... | POLYGON ((7.41588 43.7314, 7.41592 43.73136, 7... |
| relation/2236035 | {'amenity': 'childcare', 'building': 'yes', 'n... | POLYGON ((7.42345 43.73153, 7.42345 43.73152, ... |
| relation/10691624 | {'admin_level': '2', 'border_type': 'territori... | POLYGON ((7.41852 43.72476, 7.41901 43.72512, ... |
| relation/11384697 | {'addr:country': 'MC', 'building': 'yes', 'lay... | POLYGON ((7.42749 43.73125, 7.42672 43.73063, ... |
| relation/16261416 | {'natural': 'water', 'type': 'multipolygon', '... | POLYGON ((7.41783 43.73139, 7.41788 43.73139, ... |
923 rows × 2 columns
Plot downloaded data
In [9]:
Copied!
import matplotlib.pyplot as plt
import matplotlib.patches as mpatches
import geopandas as gpd
fig = plt.figure(figsize=(10, 10))
ax = fig.subplots()
gdf.plot(ax=ax, markersize=1, zorder=1, alpha=0.4)
gdf.boundary.plot(ax=ax, markersize=0, zorder=1, alpha=0.8)
gpd.GeoSeries([area], crs=4326).plot(
ax=ax,
color=(0, 0, 0, 0),
zorder=2,
hatch="///",
edgecolor="orange",
linewidth=1.5,
)
blue_patch = mpatches.Patch(color="C0", alpha=0.8, label="OSM features")
orange_patch = mpatches.Patch(
facecolor=(0, 0, 0, 0), edgecolor="orange", hatch="///", linewidth=1.5, label="Geometry filter"
)
ax.legend(handles=[blue_patch, orange_patch], loc="lower right")
plt.show()
import matplotlib.pyplot as plt
import matplotlib.patches as mpatches
import geopandas as gpd
fig = plt.figure(figsize=(10, 10))
ax = fig.subplots()
gdf.plot(ax=ax, markersize=1, zorder=1, alpha=0.4)
gdf.boundary.plot(ax=ax, markersize=0, zorder=1, alpha=0.8)
gpd.GeoSeries([area], crs=4326).plot(
ax=ax,
color=(0, 0, 0, 0),
zorder=2,
hatch="///",
edgecolor="orange",
linewidth=1.5,
)
blue_patch = mpatches.Patch(color="C0", alpha=0.8, label="OSM features")
orange_patch = mpatches.Patch(
facecolor=(0, 0, 0, 0), edgecolor="orange", hatch="///", linewidth=1.5, label="Geometry filter"
)
ax.legend(handles=[blue_patch, orange_patch], loc="lower right")
plt.show()
In [10]:
Copied!
area = qosm.geocode_to_geometry("Barcelona")
gdf = qosm.convert_geometry_to_geodataframe(
area, tags_filter={"amenity": "bicycle_rental"}
)
gdf
area = qosm.geocode_to_geometry("Barcelona")
gdf = qosm.convert_geometry_to_geodataframe(
area, tags_filter={"amenity": "bicycle_rental"}
)
gdf
Finished operation in 0:01:41
Out[10]:
| amenity | geometry | |
|---|---|---|
| feature_id | ||
| node/1297428829 | bicycle_rental | POINT (2.21923 41.41089) |
| node/2187272329 | bicycle_rental | POINT (2.19584 41.40301) |
| node/2197837744 | bicycle_rental | POINT (2.19761 41.40216) |
| node/4133230989 | bicycle_rental | POINT (2.16619 41.40542) |
| node/4145205916 | bicycle_rental | POINT (2.19271 41.40738) |
| ... | ... | ... |
| node/5262549998 | bicycle_rental | POINT (2.17076 41.39515) |
| node/5262549999 | bicycle_rental | POINT (2.19576 41.38686) |
| node/8868255399 | bicycle_rental | POINT (2.20842 41.41925) |
| node/9245802232 | bicycle_rental | POINT (2.17415 41.42217) |
| node/10308611629 | bicycle_rental | POINT (2.1626 41.38752) |
514 rows × 2 columns
Show downloaded data on a map
In [11]:
Copied!
m = gdf.explore(color="orangered", tiles="CartoDB positron")
gpd.GeoSeries([area], crs=4326).boundary.explore(m=m)
m = gdf.explore(color="orangered", tiles="CartoDB positron")
gpd.GeoSeries([area], crs=4326).boundary.explore(m=m)
Out[11]:
Make this Notebook Trusted to load map: File -> Trust Notebook
Save the result GeoParquet with WKT geometry¶
In [12]:
Copied!
qosm.convert_pbf_to_parquet(
"https://download.geofabrik.de/europe/monaco-latest.osm.pbf", save_as_wkt=True
)
qosm.convert_pbf_to_parquet(
"https://download.geofabrik.de/europe/monaco-latest.osm.pbf", save_as_wkt=True
)
Out[12]:
PosixPath('files/monaco-latest_nofilter_noclip_compact_wkt.parquet')
Specify result file path¶
In [13]:
Copied!
qosm.convert_geometry_to_parquet(
area, result_file_path='barcelona_osm_output.parquet'
)
qosm.convert_geometry_to_parquet(
area, result_file_path='barcelona_osm_output.parquet'
)
Out[13]:
PosixPath('barcelona_osm_output.parquet')
Force recalculation of the result¶
By default, running the same command twice will result in reusing the saved GeoParquet file. You can force QuackOSM to recalculate the data.