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% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2/2 • 0:00:01 < 0:00:00 • 0 it/s

⠋ Saving final geoparquet file • 0:00:00

  Sorting result file by geometry 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 136/136 • 0:00:01 < 0:00:00 • 0 it/s

Finished operation in 0:00:04
files/2025-07-23.0/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-07-23.0/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% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2/2 • 0:00:01 < 0:00:00 • 0 it/s

⠋ Saving final geoparquet file • 0:00:00

  Sorting result file by geometry 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 136/136 • 0:00:01 < 0:00:00 • 0 it/s

Finished operation in 0:00:04
files/2025-07-23.0/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% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2/2 • 0:00:01 < 0:00:00 • 0 it/s

⠋ Saving final geoparquet file • 0:00:00

  Sorting result file by geometry 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 136/136 • 0:00:01 < 0:00:00 • 0 it/s

Finished operation in 0:00:04
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.         │
│ --compression                                    TEXT            Compression algorithm to use for the parquet file. Remember to change compression level     │
│                                                                  together with this parameter using --compression-level option.                              │
│                                                                  [default: zstd]                                                                             │
│ --compression-level                              INTEGER         Compression level to use for the parquet file. Remember to change compression algorithm     │
│                                                                  together with this parameter using --compression option.                                    │
│                                                                  [default: 3]                                                                                │
│ --row-group-size                                 INTEGER         Approximate number of rows per row group in the final parquet file. [default: 100000]       │
│ --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()

No description has been provided for this image

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-07-23.0 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 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 31/31 • 0:00:01 < 0:00:00 • 0 it/s

Finished operation in 0:00:04
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:02 < 0:00:00 • 0 it/s

⠋ Saving final geoparquet file • 0:00:00

  Sorting result file by geometry 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 672/672 • 0:00:01 < 0:00:00 • 0 it/s

Finished operation in 0:00:04
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 = a018e6d4-a42b-4db2-8f1e-cc0650534ff4
              geometry = LINESTRING (17.0106646 51.094985, 17.011047 51.0952638, 17.0115944 51.0956636, 17.0118262 51.0958225, 17.0119989 51.0959338)
                  bbox = {'xmin': 17.010664, 'xmax': 17.012, 'ymin': 51.09498, 'ymax': 51.09594}
               version = 1
               sources = [{'property': , 'dataset': OpenStreetMap, 'record_id': w478508755@8, 'update_time': 2025-03-20T14:34:36Z, 'confidence': NULL, 'between': NULL}]
               subtype = rail
                 class = unknown
                 names = 
            connectors = [{'connector_id': b42da3d4-0efd-43a7-aa63-7b9b6e7f478b, 'at': 0.0}, {'connector_id': 80e79163-71e7-4401-81f6-eaacc1c9165e, 'at': 0.290612196}, {'connector_id': a77af780-8ee1-4c04-b198-f4e542ce96f2, 'at': 1.0}]
                routes = 
        subclass_rules = 
   access_restrictions = 
           level_rules = 
          destinations = 
prohibited_transitions = 
          road_surface = 
            road_flags = 
          speed_limits = 
           width_rules = 
              subclass = 
            rail_flags = [{'values': [is_abandoned], 'between': NULL}]

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% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1 • 0:00:02 < 0:00:00 • 0 it/s

⠋ Saving final geoparquet file • 0:00:00

  Sorting result file by geometry 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 12/12 • 0:00:01 < 0:00:00 • 0 it/s

Finished operation in 0:00:04
files/wroclaw_museums_example.parquet

In [31]:

Copied!

! ./duckdb :memory: "SELECT names['primary'], ROUND(confidence, 4) confidence FROM 'files/wroclaw_museums_example.parquet'";
! ./duckdb :memory: "SELECT names['primary'], ROUND(confidence, 4) confidence FROM 'files/wroclaw_museums_example.parquet'";

┌────────────────────────────────────────────────────────────┬────────────┐
│                     "names"['primary']                     │ confidence │
│                          varchar                           │   double   │
├────────────────────────────────────────────────────────────┼────────────┤
│ City Hall Wroclaw                                          │     0.9785 │
│ Niewidzialny Dom we Wrocławiu | Invisible House in Wroclaw │     0.9884 │
│ Muzeum Militariow                                          │     0.9785 │
│ Muzeum Pana Tadeusza                                       │     0.9884 │
│ Muzeum Mineralogiczne im. Kazimierza Maślankiewicza        │     0.9175 │
│ Robert Szwed Delfa                                         │     0.9065 │
│ Muzeum Iluzji                                              │     0.9884 │
│ Museum of the University of Wrocław                        │     0.9785 │
│ Muzeum Archidiecezjalne                                    │     0.9785 │
│ National Museum in Wrocław                                 │     0.9504 │
│ Museum of Architecture                                     │     0.9884 │
│ Ethnographic Museum                                        │     0.9785 │
├────────────────────────────────────────────────────────────┴────────────┤
│ 12 rows                                                       2 columns │
└─────────────────────────────────────────────────────────────────────────┘