OvertureMaestro Command Line Interface¶
OvertureMaestro contains a CLI for users convenience. It is not installed by default when installed using pip install overturemaestro.
To include the CLI, OvertureMaestro has to be installed with additional group called cli: pip install overturemaestro[cli].
CLI is based on the typer library and exposes almost all of the features implemented in the Python API.
After installation, the OvertureMaestro (or overturemaestro) command will be available in the shell.
Each command error returns a verbose description what went wrong.
Run this notebook in Google Colab:
Remember to install the overturemaestro library before running the notebook:
%pip install overturemaestro[cli]
In [1]:
Copied!
# Extend the default console width from 80 characters
import os
os.environ["COLUMNS"] = "160"
# Extend the default console width from 80 characters
import os
os.environ["COLUMNS"] = "160"
Basic usage¶
By default, the overturemaestro requires just the path to the PBF file. Without it, there will be an error.
In [2]:
Copied!
! OvertureMaestro
! OvertureMaestro
Usage: OvertureMaestro [OPTIONS] theme type Try 'OvertureMaestro -h' for help. ╭─ Error ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ OvertureMaestro requires theme, type and a geometry filter (one of --geom-filter-bbox --geom-filter-file, --geom-filter-geocode, --geom-filter-geojson, │ │ --geom-filter-index-geohash, --geom-filter-index-h3, --geom-filter-index-s2, --geom-filter-wkt) to download the data. │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Let's download a small extract of buildings in Monaco
In [3]:
Copied!
! OvertureMaestro buildings building --geom-filter-bbox 7.416486,43.730886,7.421931,43.733507
! OvertureMaestro buildings building --geom-filter-bbox 7.416486,43.730886,7.421931,43.733507
Downloading parquet files (buildings/building) 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1 • 0:00:01 < 0:00:00 • 0 it/s
⠋ Saving final geoparquet file • 0:00:00
⠹ Sorting result file by geometry • 0:00:00 Finished operation in 0:00:02 files/2025-03-19.1/theme=buildings/type=building/784274db_nofilter_sorted.parquet
Second execution of this command will immediately return a path to the previously generated file.
In [4]:
Copied!
! OvertureMaestro buildings building --geom-filter-bbox 7.416486,43.730886,7.421931,43.733507
! OvertureMaestro buildings building --geom-filter-bbox 7.416486,43.730886,7.421931,43.733507
Finished operation in 0:00:00 files/2025-03-19.1/theme=buildings/type=building/784274db_nofilter_sorted.parquet
To force the regeneration of the GeoParquet file, add the --ignore-cache flag (or --no-cache) to the command.
In [5]:
Copied!
! OvertureMaestro buildings building --geom-filter-bbox 7.416486,43.730886,7.421931,43.733507 --ignore-cache
! OvertureMaestro buildings building --geom-filter-bbox 7.416486,43.730886,7.421931,43.733507 --ignore-cache
Downloading parquet files (buildings/building) 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1 • 0:00:01 < 0:00:00 • 0 it/s
⠋ Saving final geoparquet file • 0:00:00
⠹ Sorting result file by geometry • 0:00:00
Finished operation in 0:00:01 files/2025-03-19.1/theme=buildings/type=building/784274db_nofilter_sorted.parquet
You can also set the output file path using -o (or --output) option.
In [6]:
Copied!
! OvertureMaestro buildings building --geom-filter-bbox 7.416486,43.730886,7.421931,43.733507 -o monaco_buildings.parquet
! OvertureMaestro buildings building --geom-filter-bbox 7.416486,43.730886,7.421931,43.733507 -o monaco_buildings.parquet
Downloading parquet files (buildings/building) 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1 • 0:00:01 < 0:00:00 • 0 it/s
⠋ Saving final geoparquet file • 0:00:00
⠹ Sorting result file by geometry • 0:00:00
Finished operation in 0:00:01 monaco_buildings.parquet
You can quickly inspect the data using pixel-map tool that displays the geo data in the terminal.
In [7]:
Copied!
! pixel-map monaco_buildings.parquet --width 82 --height 23 --renderer ascii-bw
! pixel-map monaco_buildings.parquet --width 82 --height 23 --renderer ascii-bw
┏━━━━━━━━━━━━━━━━━━━━━━━━━━ monaco_buildings.parquet ━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ ┃ ┃ , @L yr ][ __, ,_ ,, _s@@[ `┃ ┃ `QP_/Q@ P" J@ j[]UE jL,Z[ ^@y QS[JDDR __ ┃ ┃ __RDP"\, @@ JBJ[@ JE,J@JL8B """__,uq@Q[L"` ┃ ┃ ]QQP,Jj @QQL @ @]L P^"" _,u @DDRPP^^""" _yL ┃ ┃ ^@)PjG@" `98@F,ZL8JB s@QQDP^[,yLqq@@QQQQ@ ]QQh_ ┃ ┃ jFj\@` @by_ ` ^RQL^0L`[yp0P^"\p[J@QQQQQQ@L "0QD ┃ ┃ ,"9`_@QF9Q@ ,_ "^= "` ` @@ "__"""""`,@D`__ ┃ ┃ aQQP "^F @@F ,@QQ@pu * JQ[`@PFD8G8L]@ `Y" ┃ ┃ ,q_"" @@r "` _"9QQQP" "^ 38QQQQQLJ@L yD~ ┃ ┃ ^0QQh_@Q[_@B 0@@y"` Jqy `""` "P^" ┃ ┃ `"]`"9QQD` P^` ┃ ┃ y@@L_F` `@P _ _ ┃ ┃ _@Qup"" _, p@QQpu__^]F" ` ┃ ┃ .@QDD` " = ` _@Q@"`"9Qpq/^h@ ┃ ┃ """ = `9Q@y_ _dQP ` -uu,,_____,__ ┃ ┃ ,q~ __ "0@bdQP` jR0qGQ"^^PPP^ ┃ ┃ yP" _y ,/`` @@` /[jR0qpy ┃ ┃ 9" ` <P" @F" ` ┃ ┃ ┃ ┗━━━━━━━━━━━ BBOX: 7.41481,43.73052,7.42429,43.73394 | MAP W:80 H:20 ━━━━━━━━━━━┛
Help command¶
To get the full description of all arguments of the OvertureMaestro command, you can use the --help (or -h) parameter.
In [8]:
Copied!
! OvertureMaestro --help
! OvertureMaestro --help
Usage: OvertureMaestro [OPTIONS] theme type OvertureMaestro CLI. Wraps public functions and prints final path to the saved geoparquet file at the end. ╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ theme_value theme Data theme value │ │ type_value type Feature type within theme │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --release-version,--release TEXT OvertureMaps dataset release version. If not provided, will automatically select the newest │ │ available version. │ │ --geom-filter-bbox BBOX Geometry to use as a filter in the bounding box format - 4 floating point numbers separated │ │ by commas. Cannot be used together with other geom-filter-... parameters. │ │ --geom-filter-file PATH Geometry to use as a filter in the file format - any that can be opened by GeoPandas. Will │ │ return the unary union of the geometries in the file. Cannot be used together with other │ │ geom-filter-... parameters. │ │ --geom-filter-geocode TEXT Geometry to use as a filter in the string to geocode format - it will be geocoded to the │ │ geometry using Nominatim API (GeoPy library). Cannot be used together with other │ │ geom-filter-... parameters. │ │ --geom-filter-geojson TEXT (GEOJSON) Geometry to use as a filter in the GeoJSON format. Cannot be used together with other │ │ geom-filter-... parameters. │ │ --geom-filter-index-geohash TEXT (GEOHASH) Geometry to use as a filter in the Geohash index format. Separate multiple values with a │ │ comma. Cannot be used together with other geom-filter-... parameters. │ │ --geom-filter-index-h3 TEXT (H3) Geometry to use as a filter in the H3 index format. Separate multiple values with a comma. │ │ Cannot be used together with other geom-filter-... parameters. │ │ --geom-filter-index-s2 TEXT (S2) Geometry to use as a filter in the S2 index format. Separate multiple values with a comma. │ │ Cannot be used together with other geom-filter-... parameters. │ │ --geom-filter-wkt TEXT (WKT) Geometry to use as a filter in the WKT format. Cannot be used together with other │ │ geom-filter-... parameters. │ │ --filter,--pyarrow-filter FILTER Filters to apply on a pyarrow dataset. Required format: <column(s)> <operator> <value>. │ │ Nested column names should be passed separated by a dot. Can pass multiple filters. │ │ --output -o PATH Path where to save final geoparquet file. If not provided, it will be generated │ │ automatically based on the input pbf file name. │ │ --ignore-cache,--no-cache Whether to ignore previously precalculated geoparquet files or not. │ │ --sort --no-sort Whether to sort the final geoparquet file by geometry or not. [default: sort] │ │ --working-directory,--work-dir PATH Directory where to save the parsed parquet and geoparquet files. Will be created if doesn't │ │ exist. │ │ [default: files] │ │ --silent Whether to disable progress reporting. │ │ --transient Whether to make more transient (concise) progress reporting. │ │ --show-release-versions Show available OvertureMaps release versions and exit. │ │ --show-theme-type-pairs Show available OvertureMaps theme type pairs for the release and exit. │ │ --version -v Show the application's version and exit. │ │ --install-completion Install completion for the current shell. │ │ --show-completion Show completion for the current shell, to copy it or customize the installation. │ │ --help -h Show this message and exit. │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Geometry filters¶
OvertureMaestro will automatically download required data based on multiple geometry filters:
- Text to geocode using Nominatim
- WKT geometry
- GeoJSON geometry
- Geometry file path
- H3 spatial index
- Geohash spatial index
- S2 spatial index
OvertureMaestro will raise an error if provided geometry has parts without area (such as Points, LineStrings or empty geometry).
Let's see the example based on Monaco region.
First, we will visualise multiple filters on the map.
In [9]:
Copied!
import geopandas as gpd
from overturemaestro.cli import (
BboxGeometryParser,
GeocodeGeometryParser,
GeohashGeometryParser,
GeoJsonGeometryParser,
H3GeometryParser,
S2GeometryParser,
WktGeometryParser,
)
import geopandas as gpd
from overturemaestro.cli import (
BboxGeometryParser,
GeocodeGeometryParser,
GeohashGeometryParser,
GeoJsonGeometryParser,
H3GeometryParser,
S2GeometryParser,
WktGeometryParser,
)
In [10]:
Copied!
bbox_string = "7.416486,43.730886,7.421931,43.733507"
geocode_string = "Monaco-Ville, Monaco"
geojson_string = """{"type":"Feature","geometry":{"coordinates":[[[7.416,43.734],[7.416,43.731],[7.421,43.731],[7.421,43.734],[7.416,43.734]]],"type":"Polygon"}}"""
wkt_string = "POLYGON ((7.414 43.735, 7.414 43.732, 7.419 43.732, 7.419 43.735, 7.414 43.735))"
h3_string = "893969a4037ffff"
geohash_string = "spv2bcs"
s2_string = "12cdc28dc"
bbox_string = "7.416486,43.730886,7.421931,43.733507"
geocode_string = "Monaco-Ville, Monaco"
geojson_string = """{"type":"Feature","geometry":{"coordinates":[[[7.416,43.734],[7.416,43.731],[7.421,43.731],[7.421,43.734],[7.416,43.734]]],"type":"Polygon"}}"""
wkt_string = "POLYGON ((7.414 43.735, 7.414 43.732, 7.419 43.732, 7.419 43.735, 7.414 43.735))"
h3_string = "893969a4037ffff"
geohash_string = "spv2bcs"
s2_string = "12cdc28dc"
In [11]:
Copied!
geometry_types = ["BBox", "Geocode", "GeoJSON", "WKT", "H3", "GeoHash", "S2"]
geometries = [
BboxGeometryParser().convert(bbox_string),
GeocodeGeometryParser().convert(geocode_string),
GeoJsonGeometryParser().convert(geojson_string),
WktGeometryParser().convert(wkt_string),
H3GeometryParser().convert(h3_string),
GeohashGeometryParser().convert(geohash_string),
S2GeometryParser().convert(s2_string),
]
gpd.GeoDataFrame(
data=dict(type=geometry_types),
geometry=geometries,
crs=4326,
).explore(column="type", tiles="CartoDB positron")
geometry_types = ["BBox", "Geocode", "GeoJSON", "WKT", "H3", "GeoHash", "S2"]
geometries = [
BboxGeometryParser().convert(bbox_string),
GeocodeGeometryParser().convert(geocode_string),
GeoJsonGeometryParser().convert(geojson_string),
WktGeometryParser().convert(wkt_string),
H3GeometryParser().convert(h3_string),
GeohashGeometryParser().convert(geohash_string),
S2GeometryParser().convert(s2_string),
]
gpd.GeoDataFrame(
data=dict(type=geometry_types),
geometry=geometries,
crs=4326,
).explore(column="type", tiles="CartoDB positron")
Out[11]:
Make this Notebook Trusted to load map: File -> Trust Notebook
Now we will execute each filter and let OvertureMaestro find required region on its own.
During first execution, OvertureMaestro will cache three PBF files sources locally. This operation takes some time.
The --silent flag will disable the progress output to the terminal.
In [12]:
Copied!
! OvertureMaestro buildings building --geom-filter-bbox 7.416486,43.730886,7.421931,43.733507 --silent --output files/bbox_example.parquet
! OvertureMaestro buildings building --geom-filter-bbox 7.416486,43.730886,7.421931,43.733507 --silent --output files/bbox_example.parquet
files/bbox_example.parquet
Geocoding¶
In [13]:
Copied!
! OvertureMaestro buildings building --geom-filter-geocode 'Monaco-Ville, Monaco' --silent --output files/geocode_example.parquet
! OvertureMaestro buildings building --geom-filter-geocode 'Monaco-Ville, Monaco' --silent --output files/geocode_example.parquet
files/geocode_example.parquet
GeoJSON¶
In [14]:
Copied!
! OvertureMaestro buildings building \
--geom-filter-geojson '{"type":"Feature","geometry":{"coordinates":[[[7.416,43.734],[7.416,43.731],[7.421,43.731],[7.421,43.734],[7.416,43.734]]],"type":"Polygon"}}' \
--silent --output files/geojson_example.parquet
! OvertureMaestro buildings building \
--geom-filter-geojson '{"type":"Feature","geometry":{"coordinates":[[[7.416,43.734],[7.416,43.731],[7.421,43.731],[7.421,43.734],[7.416,43.734]]],"type":"Polygon"}}' \
--silent --output files/geojson_example.parquet
files/geojson_example.parquet
Geohash¶
In [15]:
Copied!
! OvertureMaestro buildings building --geom-filter-index-geohash spv2bcs --silent --output files/geohash_example.parquet
! OvertureMaestro buildings building --geom-filter-index-geohash spv2bcs --silent --output files/geohash_example.parquet
files/geohash_example.parquet
H3¶
In [16]:
Copied!
! OvertureMaestro buildings building --geom-filter-index-h3 893969a4037ffff --silent --output files/h3_example.parquet
! OvertureMaestro buildings building --geom-filter-index-h3 893969a4037ffff --silent --output files/h3_example.parquet
files/h3_example.parquet
S2¶
In [17]:
Copied!
! OvertureMaestro buildings building --geom-filter-index-s2 12cdc28dc --silent --output files/s2_example.parquet
! OvertureMaestro buildings building --geom-filter-index-s2 12cdc28dc --silent --output files/s2_example.parquet
files/s2_example.parquet
WKT¶
In [18]:
Copied!
! OvertureMaestro buildings building --geom-filter-wkt 'POLYGON ((7.414 43.735, 7.414 43.732, 7.419 43.732, 7.419 43.735, 7.414 43.735))' \
--silent --output files/wkt_example.parquet
! OvertureMaestro buildings building --geom-filter-wkt 'POLYGON ((7.414 43.735, 7.414 43.732, 7.419 43.732, 7.419 43.735, 7.414 43.735))' \
--silent --output files/wkt_example.parquet
files/wkt_example.parquet
Plot all results for comparison
In [19]:
Copied!
import matplotlib.patches as mpatches
import matplotlib.pyplot as plt
fig, axs = plt.subplots(2, 4, sharex=True, sharey=True, figsize=(10, 5))
for idx, (geometry_type, geometry) in enumerate(zip(geometry_types, geometries)):
ax = axs[idx // 4, idx % 4]
gdf = gpd.read_parquet(f"files/{geometry_type.lower()}_example.parquet")
gdf.plot(ax=ax, markersize=1, zorder=1, alpha=0.8)
gdf.boundary.plot(ax=ax, markersize=0, zorder=1, alpha=0.8)
gpd.GeoSeries([geometry], crs=4326).plot(
ax=ax,
color=(0, 0, 0, 0),
zorder=2,
hatch="///",
edgecolor="orange",
linewidth=1.5,
)
ax.set_title(geometry_type)
axs[1, 3].set_axis_off()
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"
)
fig.legend(handles=[blue_patch, orange_patch], bbox_to_anchor=(0.98, 0.35))
fig.tight_layout()
import matplotlib.patches as mpatches
import matplotlib.pyplot as plt
fig, axs = plt.subplots(2, 4, sharex=True, sharey=True, figsize=(10, 5))
for idx, (geometry_type, geometry) in enumerate(zip(geometry_types, geometries)):
ax = axs[idx // 4, idx % 4]
gdf = gpd.read_parquet(f"files/{geometry_type.lower()}_example.parquet")
gdf.plot(ax=ax, markersize=1, zorder=1, alpha=0.8)
gdf.boundary.plot(ax=ax, markersize=0, zorder=1, alpha=0.8)
gpd.GeoSeries([geometry], crs=4326).plot(
ax=ax,
color=(0, 0, 0, 0),
zorder=2,
hatch="///",
edgecolor="orange",
linewidth=1.5,
)
ax.set_title(geometry_type)
axs[1, 3].set_axis_off()
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"
)
fig.legend(handles=[blue_patch, orange_patch], bbox_to_anchor=(0.98, 0.35))
fig.tight_layout()
Theme and type¶
Overture Maps data uses themes and types to partition the dataset by function. User can retrieve this list for any available release version supported by OvertureMaestro.
Full definition is explained in the official schema documentation.
Displaying available extracts¶
CLI exposes a dedicated flag --show-extracts (or --show-osm-extracts) for display a list of available extracts.
You can read more about it in a dedicated OSM extracts example.
Without providing an OSM extract source (--osm-extract-source), all sources will be displayed at once.
In [20]:
Copied!
! OvertureMaestro --show-theme-type-pairs
! OvertureMaestro --show-theme-type-pairs
2025-03-19.1 release ┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓ ┃ Theme ┃ Type ┃ ┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩ │ addresses │ address │ │ base │ bathymetry │ │ base │ infrastructure │ │ base │ land │ │ base │ land_cover │ │ base │ land_use │ │ base │ water │ │ buildings │ building │ │ buildings │ building_part │ │ divisions │ division │ │ divisions │ division_area │ │ divisions │ division_boundary │ │ places │ place │ │ transportation │ connector │ │ transportation │ segment │ └────────────────┴───────────────────┘
Let's see the example based on the London region.
Buildings¶
In [21]:
Copied!
! OvertureMaestro buildings building --geom-filter-geocode "City of London" --silent --output files/london_buildings_example.parquet
! OvertureMaestro buildings building --geom-filter-geocode "City of London" --silent --output files/london_buildings_example.parquet
files/london_buildings_example.parquet
Places¶
In [22]:
Copied!
! OvertureMaestro places place --geom-filter-geocode "City of London" --silent --output files/london_places_example.parquet
! OvertureMaestro places place --geom-filter-geocode "City of London" --silent --output files/london_places_example.parquet
files/london_places_example.parquet
Water¶
In [23]:
Copied!
! OvertureMaestro base water --geom-filter-geocode "City of London" --silent --output files/london_water_example.parquet
! OvertureMaestro base water --geom-filter-geocode "City of London" --silent --output files/london_water_example.parquet
files/london_water_example.parquet
Roads¶
In [24]:
Copied!
! OvertureMaestro transportation segment --geom-filter-geocode "City of London" \
--filter "subtype == road" --silent --output files/london_roads_example.parquet
! OvertureMaestro transportation segment --geom-filter-geocode "City of London" \
--filter "subtype == road" --silent --output files/london_roads_example.parquet
files/london_roads_example.parquet
Plot all different types of features for comparison
In [25]:
Copied!
import matplotlib.pyplot as plt
from overturemaestro import geocode_to_geometry
geometry_filter = gpd.GeoSeries([geocode_to_geometry("City of London")], crs=4326)
bounds = geometry_filter.total_bounds
geometry_types = ["water", "roads", "buildings", "places"]
colors = ["#118AB2", "#073B4C", "#06D6A0", "#FFD166"]
fig, axs = plt.subplot_mosaic(
"""
aa
aa
bp
rw
""",
figsize=(10, 12),
layout="constrained",
)
main_ax = axs["a"]
main_ax.set_title("City of London")
for geometry_type, color in zip(geometry_types, colors):
filename = f"files/london_{geometry_type}_example.parquet"
gdf = gpd.read_parquet(filename, columns=["geometry"])
for ax in (main_ax, axs[geometry_type[0]]):
gdf.plot(ax=ax, markersize=1, zorder=1, alpha=0.8, color=color)
for geometry_type in geometry_types:
axs[geometry_type[0]].set_title(geometry_type.capitalize())
for key, ax in axs.items():
ax.set_xlim([bounds[0] - 0.001, bounds[2] + 0.001])
ax.set_ylim([bounds[1] - 0.001, bounds[3] + 0.001])
if key == "a":
continue
geometry_filter.plot(
ax=ax,
color=(0, 0, 0, 0),
zorder=2,
edgecolor="#EF476F",
linewidth=1.5,
)
ax.set_axis_off()
import matplotlib.pyplot as plt
from overturemaestro import geocode_to_geometry
geometry_filter = gpd.GeoSeries([geocode_to_geometry("City of London")], crs=4326)
bounds = geometry_filter.total_bounds
geometry_types = ["water", "roads", "buildings", "places"]
colors = ["#118AB2", "#073B4C", "#06D6A0", "#FFD166"]
fig, axs = plt.subplot_mosaic(
"""
aa
aa
bp
rw
""",
figsize=(10, 12),
layout="constrained",
)
main_ax = axs["a"]
main_ax.set_title("City of London")
for geometry_type, color in zip(geometry_types, colors):
filename = f"files/london_{geometry_type}_example.parquet"
gdf = gpd.read_parquet(filename, columns=["geometry"])
for ax in (main_ax, axs[geometry_type[0]]):
gdf.plot(ax=ax, markersize=1, zorder=1, alpha=0.8, color=color)
for geometry_type in geometry_types:
axs[geometry_type[0]].set_title(geometry_type.capitalize())
for key, ax in axs.items():
ax.set_xlim([bounds[0] - 0.001, bounds[2] + 0.001])
ax.set_ylim([bounds[1] - 0.001, bounds[3] + 0.001])
if key == "a":
continue
geometry_filter.plot(
ax=ax,
color=(0, 0, 0, 0),
zorder=2,
edgecolor="#EF476F",
linewidth=1.5,
)
ax.set_axis_off()
PyArrow filters¶
By default, OvertureMaestro loads all of the features intersecting given geometry.
Hovewer, there is also an option to pass filters (--filter or --pyarrow-filter) used by PyArrow during downloading step.
Filters are expected to be strings in this format: <column name(s)> <operator> <value>.
Examples: confidence > 0.95, subtype == road, categories,primary = museum.
Passed strings are parsed to pyarrow.Expression. Multiple filters can be passed to the CLI.
You can read abaout every dataset type schema and available fields here.
Note: Overture Maps schema can change between release versions.
Load only rivers¶
In [26]:
Copied!
! OvertureMaestro base water --filter "subtype = river" \
--geom-filter-bbox "17.010921,51.093406,17.054266,51.122229" \
--output files/wroclaw_rivers_example.parquet
! OvertureMaestro base water --filter "subtype = river" \
--geom-filter-bbox "17.010921,51.093406,17.054266,51.122229" \
--output files/wroclaw_rivers_example.parquet
Downloading parquet files (base/water) 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1 • 0:00:01 < 0:00:00 • 0 it/s
⠋ Saving final geoparquet file • 0:00:00
⠹ Sorting result file by geometry • 0:00:00 Finished operation in 0:00:02 files/wroclaw_rivers_example.parquet
In [27]:
Copied!
! pixel-map files/wroclaw_rivers_example.parquet --width 82 --height 23 --renderer ascii-bw
! pixel-map files/wroclaw_rivers_example.parquet --width 82 --height 23 --renderer ascii-bw
┏━━━━━━━━━━━━━━━━━━━━━━━ wroclaw_rivers_example.parquet ━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ ` ┃ ┃ `` ` ` ┃ ┃ `` ┃ ┃ ` ` ┃ ┃ ` ┃ ┃ j~_ ` ┃ ┃ /` `L ┃ ┃ _ ] _~_ ┃ ┃ "=__ **=yhn~`. ┃ ┃ ``"^" " 9u,_ ┃ ┃ "^q ┃ ┃ `k ┃ ┃ /`^==L__ ┃ ┃ -, "^ ┃ ┃ ] ` ┃ ┃ | ` ┃ ┃ ` ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗━━━━━━━━━━ BBOX: 16.97224,51.08913,17.11833,51.13499 | MAP W:80 H:20 ━━━━━━━━━━┛
Load railroads¶
In [28]:
Copied!
! OvertureMaestro transportation segment --filter "subtype = rail" \
--geom-filter-bbox "17.010921,51.093406,17.054266,51.122229" \
--output files/wroclaw_rail_example.parquet
! OvertureMaestro transportation segment --filter "subtype = rail" \
--geom-filter-bbox "17.010921,51.093406,17.054266,51.122229" \
--output files/wroclaw_rail_example.parquet
Downloading parquet files (transportation/segment) 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2/2 • 0:00:01 < 0:00:00 • 16.24 it/s
⠋ Saving final geoparquet file • 0:00:00
⠹ Sorting result file by geometry • 0:00:00 Finished operation in 0:00:02 files/wroclaw_rail_example.parquet
In [29]:
Copied!
! ./duckdb :memory: ".mode line" "FROM 'files/wroclaw_rail_example.parquet' LIMIT 1";
! ./duckdb :memory: ".mode line" "FROM 'files/wroclaw_rail_example.parquet' LIMIT 1";
id = 0861e2040fffffff047febfa054db083
geometry = LINESTRING (17.0216651 51.1044343, 17.0215328 51.104388, 17.0213076 51.1043109, 17.0211303 51.1042589, 17.0209719 51.1042176, 17.0203378 51.1040542, 17.0191783 51.1037566, 17.0184528 51.1035708, 17.0180165 51.1034674, 17.0169977 51.1032385, 17.016897 51.103215, 17.0164694 51.1031084, 17.0161007 51.1030097, 17.0153972 51.102831, 17.0139571 51.1024713, 17.0136665 51.1024001, 17.0135712 51.1023773, 17.0134359 51.1023489, 17.0133191 51.1023292, 17.0131509 51.1023058, 17.0129674 51.1022774, 17.0128847 51.1022635, 17.0127551 51.1022374, 17.0126275 51.1022088, 17.0118893 51.1020439, 17.0109598 51.1018332, 17.010645 51.1017503, 17.0103393 51.1016676, 17.0101522 51.1016227, 17.0100347 51.1015952, 17.0095833 51.101494, 17.0094295 51.1014608, 17.0092068 51.1014157, 17.0089627 51.1013695, 17.0085027 51.1012829, 17.0082888 51.1012419, 17.0081228 51.1012057, 17.0075259 51.1010724, 17.0070842 51.1009724, 17.0068934 51.100925, 17.0064199 51.1008129, 17.0057232 51.1006557, 17.0050285 51.1004995, 17.0034288 51.1001409, 17.0028665 51.1000136, 17.0021748 51.099848, 17.0018327 51.0997702, 17.0012552 51.0996385, 17.0008699 51.0995468, 17.0004829 51.0994506, 17.0001922 51.0993783, 17.0000252 51.0993357, 16.9998732 51.0993003, 16.9993009 51.0991757, 16.9981214 51.0989083, 16.9972391 51.0987083, 16.9970612 51.0986684, 16.9968364 51.0986185, 16.9966354 51.098573, 16.9964437 51.0985295, 16.9961419 51.0984615, 16.996029 51.0984349, 16.9956537 51.0983498, 16.9954529 51.0983071, 16.9952477 51.0982672, 16.9943613 51.0980815, 16.9939384 51.0979861, 16.9932773 51.097835, 16.9927852 51.0977236, 16.9920747 51.097563, 16.9918721 51.0975194, 16.9916666 51.0974776, 16.991545 51.0974561, 16.9914656 51.0974407, 16.990891 51.0973335, 16.9903875 51.0972392, 16.9902403 51.0972102, 16.9900769 51.0971735, 16.9899585 51.0971458, 16.9898147 51.0971084, 16.9896474 51.097062, 16.9894546 51.0970092, 16.9891728 51.0969321, 16.9886092 51.0967767, 16.9880098 51.0966119, 16.9871255 51.0963689, 16.9863712 51.096161, 16.9859324 51.0960406, 16.9853998 51.0958836, 16.9850476 51.095778, 16.9848996 51.0957351, 16.9846934 51.0956768, 16.9845033 51.0956261, 16.9839476 51.0954806, 16.9833496 51.0953229, 16.9828879 51.0952024, 16.982495 51.0950993, 16.9821936 51.0950194, 16.9820026 51.094972, 16.9818574 51.0949421, 16.9816398 51.0949002, 16.9806262 51.0947109, 16.9804934 51.0946849)
bbox = {'xmin': 16.980492, 'xmax': 17.021666, 'ymin': 51.094685, 'ymax': 51.104435}
version = 0
sources = [{'property': , 'dataset': OpenStreetMap, 'record_id': w179407834@20, 'update_time': 2024-10-28T00:13:58Z, 'confidence': NULL}]
subtype = rail
class =
names =
connectors = [{'connector_id': 08f1e20408c6464b047d7f1fdba81f90, 'at': 0.0}, {'connector_id': 08f1e20408c04613047d6f6493f87544, 'at': 0.116984272}, {'connector_id': 08f1e2040e585276047ffed4696c32ce, 'at': 1.0}]
routes =
subclass =
subclass_rules =
access_restrictions =
level_rules =
destinations =
prohibited_transitions =
road_surface =
road_flags =
speed_limits =
width_rules =
Load museums with a high confidence score¶
Here, the nested field categories.primary have to be accessed using comma delimited syntax.
In [30]:
Copied!
! OvertureMaestro places place --filter "categories,primary = museum" --filter "confidence > 0.9" \
--geom-filter-bbox "17.010921,51.093406,17.054266,51.122229" \
--output files/wroclaw_museums_example.parquet
! OvertureMaestro places place --filter "categories,primary = museum" --filter "confidence > 0.9" \
--geom-filter-bbox "17.010921,51.093406,17.054266,51.122229" \
--output files/wroclaw_museums_example.parquet
Downloading parquet files (places/place) 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2/2 • 0:00:01 < 0:00:00 • 0 it/s
⠋ Saving final geoparquet file • 0:00:00
⠹ Sorting result file by geometry • 0:00:00 Finished operation in 0:00:02 files/wroclaw_museums_example.parquet