OvertureMaestro Basic Usage¶

OvertureMaestro 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.

Run this notebook in Google Colab:

Remember to install the overturemaestro library before running the notebook:

%pip install overturemaestro[cli]

In [1]:

Copied!

import overturemaestro as om
import overturemaestro as om

Get the data for a region to GeoDataFrame¶

Without release version¶

If release version is omitted - OvertureMaestro automatically searches for the newest available version and applies it.

In [2]:

Copied!

london_bbox = (-0.120077, 51.498164, -0.090809, 51.508849)
london_bbox = (-0.120077, 51.498164, -0.090809, 51.508849)

In [3]:

Copied!





buildings_gdf = om.convert_bounding_box_to_geodataframe(
    theme="buildings", type="building", bbox=london_bbox
)
buildings_gdf
buildings_gdf = om.convert_bounding_box_to_geodataframe(
    theme="buildings", type="building", bbox=london_bbox
)
buildings_gdf

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/addresses_address.parquet

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/base_bathymetry.parquet

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/base_infrastructure.parquet

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/base_land.parquet

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/base_land_cover.parquet

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/base_land_use.parquet

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/base_water.parquet

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/buildings_building.parquet

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/buildings_building_part.parquet

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/divisions_division.parquet

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/divisions_division_area.parquet

Saved index file 
/home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/divisions_division_boundary.parquet

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/places_place.parquet

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/transportation_connector.parquet

Saved index file /home/runner/.cache/OvertureMaestro/release_indexes/2026-04-15.0/transportation_segment.parquet

Finished operation in 0:00:46

Out[3]:

	names	sources	level	height	min_height	is_underground	num_floors	num_floors_underground	min_floor	subtype	...	roof_material	roof_shape	roof_direction	roof_orientation	roof_color	roof_height	geometry	has_parts	version	bbox
id
d711565b-a326-4490-8fd5-04c13114a17a	{'primary': 'South Wing', 'common': None, 'rul...	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	16.703644	NaN	False	NaN	NaN	NaN	medical	...	None	None	NaN	None	None	NaN	POLYGON ((-0.11986 51.49762, -0.11978 51.49762...	False	2	{'xmin': -0.12040751427412033, 'xmax': -0.1189...
0186e9ca-c3c3-4af6-81bd-272143e8cd98	{'primary': 'St Thomas House', 'common': None,...	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	13.369651	NaN	False	5.0	NaN	NaN	None	...	None	None	NaN	None	None	NaN	POLYGON ((-0.11879 51.49815, -0.11897 51.49817...	False	2	{'xmin': -0.11905670166015625, 'xmax': -0.1187...
1547a80c-fe11-41a5-b8e8-eb278dced91c	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	NaN	NaN	False	NaN	NaN	NaN	None	...	None	None	NaN	None	None	NaN	POLYGON ((-0.11678 51.49838, -0.11681 51.49839...	False	1	{'xmin': -0.11684241145849228, 'xmax': -0.1166...
011a1f4a-13f8-4ae9-a0bf-3ca3238ed41a	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	NaN	NaN	False	NaN	NaN	NaN	None	...	None	None	NaN	None	None	NaN	POLYGON ((-0.11692 51.49842, -0.11695 51.49844...	False	1	{'xmin': -0.11698610335588455, 'xmax': -0.1168...
a4e59ecb-683a-4ab1-805a-6e9ee8852f1b	{'primary': 'Evelina London Children's Hospita...	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	NaN	NaN	False	7.0	NaN	NaN	medical	...	None	None	NaN	None	None	NaN	POLYGON ((-0.119 51.49848, -0.11906 51.49848, ...	False	1	{'xmin': -0.11908791214227676, 'xmax': -0.1177...
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
e8d67f82-a895-4dc7-85fb-5ab3ccb36484	None	[{'property': '', 'dataset': 'Microsoft ML Bui...	NaN	3.081395	NaN	False	NaN	NaN	NaN	None	...	None	None	NaN	None	None	NaN	POLYGON ((-0.09307 51.49842, -0.09308 51.49839...	False	3	{'xmin': -0.0930837020277977, 'xmax': -0.09301...
c4894a1c-51d9-4ee3-9a32-91e74072e8a2	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	9.084686	NaN	False	NaN	NaN	NaN	residential	...	None	None	NaN	None	None	NaN	POLYGON ((-0.09283 51.49843, -0.09326 51.49799...	False	2	{'xmin': -0.09326370060443878, 'xmax': -0.0926...
2fabf75b-0efd-457f-b3a1-fec207eec1c9	None	[{'property': '', 'dataset': 'Microsoft ML Bui...	NaN	3.597508	NaN	False	NaN	NaN	NaN	None	...	None	None	NaN	None	None	NaN	POLYGON ((-0.0933 51.49819, -0.09322 51.49816,...	False	3	{'xmin': -0.09329730272293091, 'xmax': -0.0931...
fcd06242-49cc-4e23-ac2c-10583ba2eb83	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	9.935987	NaN	False	NaN	NaN	NaN	residential	...	None	None	NaN	None	None	NaN	POLYGON ((-0.09215 51.49839, -0.09222 51.49841...	False	2	{'xmin': -0.09283170104026794, 'xmax': -0.0921...
3d234bec-5713-4f31-b019-bc3dc7c19701	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	9.785714	NaN	False	NaN	NaN	NaN	residential	...	None	None	NaN	None	None	NaN	POLYGON ((-0.09158 51.4982, -0.09164 51.49822,...	False	2	{'xmin': -0.09225880354642868, 'xmax': -0.0915...

1880 rows × 23 columns

With release version¶

Release version can also be passed explicitly.

In [4]:

Copied!

overture_maps_release = om.get_newest_release_version()
overture_maps_release = om.get_newest_release_version()

In [5]:

Copied!





roads_gdf = om.convert_bounding_box_to_geodataframe(
    release=overture_maps_release, theme="transportation", type="segment", bbox=london_bbox
)
roads_gdf
roads_gdf = om.convert_bounding_box_to_geodataframe(
    release=overture_maps_release, theme="transportation", type="segment", bbox=london_bbox
)
roads_gdf

Finished operation in 0:00:04

Out[5]:

	names	subtype	class	subclass	subclass_rules	connectors	road_surface	road_flags	rail_flags	width_rules	level_rules	access_restrictions	speed_limits	prohibited_transitions	routes	destinations	sources	geometry	version	bbox
id
4f7eb0b1-26be-4828-8d13-1f29f3d36a7e	{'primary': 'Bakerloo Line', 'common': None, '...	rail	subway	None	None	[{'connector_id': '223e4bf4-5a37-4d1f-b0cf-2cc...	None	None	[{'values': ['is_tunnel'], 'between': None}]	None	[{'value': -2, 'between': [0.0, 0.132963145]},...	None	None	None	None	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	LINESTRING (-0.10226 51.49662, -0.10423 51.498...	1	{'xmin': -0.1766735017299652, 'xmax': -0.10226...
78f66906-0c2f-4bab-8211-12a5527355f2	{'primary': 'Piccadilly Line', 'common': None,...	rail	subway	None	None	[{'connector_id': '3b5dfd7c-b61b-434b-b6ed-a96...	None	None	[{'values': ['is_tunnel'], 'between': [0.0, 0....	None	[{'value': -3, 'between': [0.0, 0.065934973]},...	None	None	None	None	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	LINESTRING (-0.10689 51.56217, -0.10702 51.561...	2	{'xmin': -0.27884864807128906, 'xmax': -0.1068...
83d76bee-23fa-4e4e-b291-5176ceb471fb	{'primary': 'Bakerloo Line', 'common': None, '...	rail	subway	None	None	[{'connector_id': '4c370660-c65f-457b-af35-a99...	None	None	[{'values': ['is_covered'], 'between': [0.0077...	None	[{'value': -1, 'between': [0.0, 0.063482533]},...	None	None	None	None	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	LINESTRING (-0.20994 51.53331, -0.20978 51.533...	1	{'xmin': -0.20994412899017334, 'xmax': -0.1133...
482e0c1a-27d9-4f67-9ea8-aa6371f3abf2	{'primary': 'Jubilee Line', 'common': None, 'r...	rail	subway	None	None	[{'connector_id': '25585634-bd75-436e-aeed-096...	None	None	[{'values': ['is_tunnel'], 'between': [0.0, 0....	None	[{'value': -1, 'between': [0.0, 0.015969457]},...	None	None	None	None	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	LINESTRING (-0.11856 51.50197, -0.12056 51.501...	2	{'xmin': -0.1912105232477188, 'xmax': -0.11856...
8116c135-638c-4684-95f3-8cacabfdd16d	{'primary': 'Central Line - Eastbound', 'commo...	rail	subway	None	None	[{'connector_id': '6a48c4da-5549-4628-9293-d00...	None	None	[{'values': ['is_tunnel'], 'between': None}]	None	[{'value': -2, 'between': [0.0, 0.17053762]}, ...	None	None	None	None	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	LINESTRING (-0.22435 51.50983, -0.22435 51.509...	1	{'xmin': -0.22442862391471863, 'xmax': -0.0568...
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
5848616e-9d9a-4594-8c8e-c5087fcaa34a	{'primary': 'Rosslare (IRL) - Dunkerque (F)', ...	water	None	None	None	[{'connector_id': '9a04db2e-dac7-4b4d-9cc3-d0a...	None	None	None	None	None	None	None	None	None	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	LINESTRING (-6.33657 52.25383, -6.34047 52.256...	4	{'xmin': -6.341562747955322, 'xmax': 2.1850199...
d6de63bc-ac6b-4408-a04f-b8619afc3289	{'primary': 'Northern Line (Bank Branch)', 'co...	rail	subway	None	None	[{'connector_id': 'fd22b21b-7997-46ab-8cfa-fad...	None	None	[{'values': ['is_tunnel'], 'between': None}]	None	[{'value': -2, 'between': [0.0, 0.161438062]},...	None	None	None	None	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	LINESTRING (-0.10737 51.487, -0.10711 51.48723...	2	{'xmin': -0.12841111421585083, 'xmax': -0.0866...
29c55e63-6b02-4b23-9582-df4c7e30c8b7	{'primary': 'Northern Line (Bank Branch)', 'co...	rail	subway	None	None	[{'connector_id': '2dd9d728-49f8-4e7a-8660-9dc...	None	None	[{'values': ['is_tunnel'], 'between': None}]	None	[{'value': -3, 'between': [0.0, 0.611149846]},...	None	None	None	None	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	LINESTRING (-0.1392 51.53537, -0.13906 51.5351...	3	{'xmin': -0.13920150697231293, 'xmax': -0.0869...
99291ceb-62a6-4998-bebf-16fc2977e6ee	{'primary': 'Circle and District Lines', 'comm...	rail	subway	None	None	[{'connector_id': '9fe1be8b-6f5f-42b2-8a30-77b...	None	None	[{'values': ['is_tunnel'], 'between': [0.0, 0....	None	[{'value': -1, 'between': [0.0, 0.020692723]},...	None	None	None	None	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	LINESTRING (-0.18519 51.49496, -0.1847 51.4948...	3	{'xmin': -0.18518942594528198, 'xmax': -0.0753...
a732c777-9de6-4b9e-8a48-ed0d12eac48a	{'primary': 'Circle and District Lines', 'comm...	rail	subway	None	None	[{'connector_id': '6954bb9a-4278-4ac4-bbb9-be4...	None	None	[{'values': ['is_tunnel'], 'between': [0.0, 0....	None	[{'value': -2, 'between': [0.0, 0.03947903]}, ...	None	None	None	None	None	[{'property': '', 'dataset': 'OpenStreetMap', ...	LINESTRING (-0.07532 51.51338, -0.07534 51.513...	5	{'xmin': -0.1801884025335312, 'xmax': -0.07531...

3102 rows × 20 columns

With PyArrow filtering¶

OvertureMaestro enables passing optional PyArrow filter used during data acquisition.

In [6]:

Copied!





water_gdf = om.convert_bounding_box_to_geodataframe(
    theme="base", type="water", bbox=london_bbox, pyarrow_filter=[("subtype", "=", "river")]
)
water_gdf
water_gdf = om.convert_bounding_box_to_geodataframe(
    theme="base", type="water", bbox=london_bbox, pyarrow_filter=[("subtype", "=", "river")]
)
water_gdf

Finished operation in 0:00:02

Out[6]:

	names	subtype	class	sources	source_tags	level	wikidata	is_intermittent	is_salt	geometry	version	bbox
id
708921b4-9742-3488-abfc-2b2bfa524506	{'primary': 'River Thames', 'common': [('af', ...	river	river	[{'property': '', 'dataset': 'OpenStreetMap', ...	[(CEMT, Va), (admin_level, 8), (boat, yes), (b...	NaN	None	None	None	LINESTRING (-0.12949 51.48589, -0.12944 51.485...	0	{'xmin': -0.12949131429195404, 'xmax': -0.1114...
8d95a358-abad-33fe-807b-d62a31ba92c5	{'primary': 'River Thames', 'common': [('af', ...	river	river	[{'property': '', 'dataset': 'OpenStreetMap', ...	[(CEMT, Va), (admin_level, 6), (boat, yes), (b...	NaN	None	None	None	LINESTRING (-0.09573 51.50928, -0.0953 51.5091...	0	{'xmin': -0.09572990238666534, 'xmax': -0.0923...
1135b1d2-1852-36ec-b1ad-10c4921641a4	{'primary': 'River Thames', 'common': [('af', ...	river	river	[{'property': '', 'dataset': 'OpenStreetMap', ...	[(CEMT, Va), (admin_level, 6), (boat, yes), (b...	NaN	None	None	None	LINESTRING (-0.09236 51.50845, -0.09193 51.508...	0	{'xmin': -0.09236110001802444, 'xmax': -0.0890...
9bb08229-8106-3f90-8414-e6c83618e89c	None	river	river	[{'property': '', 'dataset': 'OpenStreetMap', ...	[(natural, water), (tidal, yes), (type, multip...	NaN	None	None	None	POLYGON ((-0.12 51.50062, -0.12003 51.50062, -...	1	{'xmin': -0.3220961093902588, 'xmax': -0.08711...

Colours inspired by https://snazzymaps.com/style/144886

In [7]:

Copied!





ax = buildings_gdf.plot(color="#f7cda9", zorder=3)
roads_gdf.plot(ax=ax, color="#cc7578", zorder=1)
water_gdf.plot(ax=ax, color="#97b5bf", zorder=2)
ax.set_xlim([london_bbox[0], london_bbox[2]])
ax.set_ylim([london_bbox[1], london_bbox[3]])
ax.set_axis_off()
ax = buildings_gdf.plot(color="#f7cda9", zorder=3)
roads_gdf.plot(ax=ax, color="#cc7578", zorder=1)
water_gdf.plot(ax=ax, color="#97b5bf", zorder=2)
ax.set_xlim([london_bbox[0], london_bbox[2]])
ax.set_ylim([london_bbox[1], london_bbox[3]])
ax.set_axis_off()

No description has been provided for this image

Result file sorting¶

By default, OvertureMaestro sorts the result file by geometry using Hilbert curve to make it smaller. It adds some time to the overall execution, but can reduce the file size. The files are already heavily compressed using ZSTD algorithm with max compression level (22) and sorting can improve spatial operations speed.

Sorting can be disabled by the user.

In [8]:

Copied!





unsorted_pq = om.convert_geometry_to_parquet(
    theme="buildings",
    type="building",
    geometry_filter=om.geocode_to_geometry("Paris"),
    sort_result=False,
    ignore_cache=True,
)
unsorted_pq = om.convert_geometry_to_parquet(
    theme="buildings",
    type="building",
    geometry_filter=om.geocode_to_geometry("Paris"),
    sort_result=False,
    ignore_cache=True,
)

Finished operation in 0:00:08

In [9]:

Copied!





sorted_pq = om.convert_geometry_to_parquet(
    theme="buildings",
    type="building",
    geometry_filter=om.geocode_to_geometry("Paris"),
    sort_result=True,
    ignore_cache=True,
)
sorted_pq = om.convert_geometry_to_parquet(
    theme="buildings",
    type="building",
    geometry_filter=om.geocode_to_geometry("Paris"),
    sort_result=True,
    ignore_cache=True,
)

Finished operation in 0:00:08

In [10]:

Copied!





import geopandas as gpd
from matplotlib import pyplot as plt

fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(20, 10))

gpd.read_parquet(unsorted_pq).reset_index().reset_index().plot(column="index", ax=ax1, cmap="jet")
gpd.read_parquet(sorted_pq).reset_index().reset_index().plot(column="index", ax=ax2, cmap="jet")

unsorted_size = unsorted_pq.stat().st_size
sorted_size = sorted_pq.stat().st_size

ax1.set_title(f"Unsorted: {unsorted_size} bytes")
ax2.set_title(
    f"Sorted: {sorted_size} bytes ({100 - (100 * sorted_size) / unsorted_size:.2f}% reduction)"
)

plt.show()
import geopandas as gpd
from matplotlib import pyplot as plt

fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(20, 10))

gpd.read_parquet(unsorted_pq).reset_index().reset_index().plot(column="index", ax=ax1, cmap="jet")
gpd.read_parquet(sorted_pq).reset_index().reset_index().plot(column="index", ax=ax2, cmap="jet")

unsorted_size = unsorted_pq.stat().st_size
sorted_size = sorted_pq.stat().st_size

ax1.set_title(f"Unsorted: {unsorted_size} bytes")
ax2.set_title(
    f"Sorted: {sorted_size} bytes ({100 - (100 * sorted_size) / unsorted_size:.2f}% reduction)"
)

plt.show()

Metadata functions¶

OvertureMaestro exposes some metadata functions for the user.

Get all available release versions¶

List of available releases is downloaded from the accompanying GitHub repository with precalculated indexes.

In [11]:

Copied!

om.get_available_release_versions()
om.get_available_release_versions()

Out[11]:

['2026-04-15.0', '2026-03-18.0', '2026-02-18.0']

Get newest available releave version¶

In [12]:

Copied!

om.get_newest_release_version()
om.get_newest_release_version()

Out[12]:

'2026-04-15.0'

List all available theme/type pairs¶

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.

If release index isn't cached locally, it will be loaded from the accompanying GitHub repository.

In [13]:

Copied!

om.get_available_theme_type_pairs(overture_maps_release)
om.get_available_theme_type_pairs(overture_maps_release)

Out[13]:

[('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')]

Release version can also be infered implicitly - it will automatically load newest release version.

In [14]:

Copied!

om.get_available_theme_type_pairs()
om.get_available_theme_type_pairs()

Out[14]:

[('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')]