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

Finished operation in 0:00:05

Out[3]:

	geometry	bbox	version	sources	level	subtype	class	height	names	has_parts	...	min_height	min_floor	facade_color	facade_material	roof_material	roof_shape	roof_direction	roof_orientation	roof_color	roof_height
id
08b194ad148b2fff020098113fb83631	POLYGON ((-0.11978 51.49762, -0.11962 51.49762...	{'xmin': -0.12040751427412033, 'xmax': -0.1189...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	medical	hospital	16.703644	{'primary': 'South Wing', 'common': None, 'rul...	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
08b194ad14886fff020032179920a3f7	POLYGON ((-0.11897 51.49817, -0.11898 51.49814...	{'xmin': -0.11905670166015625, 'xmax': -0.1187...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	None	None	13.369651	{'primary': 'St Thomas House', 'common': None,...	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
08b194ad148a5fff020056581d09863d	POLYGON ((-0.11681 51.49839, -0.11684 51.49835...	{'xmin': -0.11684241145849228, 'xmax': -0.1166...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	None	None	NaN	None	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
08b194ad148a5fff020042ea64aea3cf	POLYGON ((-0.11695 51.49844, -0.11699 51.4984,...	{'xmin': -0.11698610335588455, 'xmax': -0.1168...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	None	None	NaN	None	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
08b194ad148b1fff0200f681507439a9	POLYGON ((-0.11906 51.49848, -0.11905 51.4984,...	{'xmin': -0.11908791214227676, 'xmax': -0.1177...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	medical	hospital	NaN	{'primary': 'Evelina London Children's Hospita...	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
08b194ad33cedfff02006d2f24158ede	POLYGON ((-0.09308 51.49839, -0.09303 51.49838...	{'xmin': -0.09308367967605591, 'xmax': -0.0930...	0	[{'property': '', 'dataset': 'Microsoft ML Bui...	NaN	None	None	3.081395	None	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
08b194ad33cedfff0200da6884239805	POLYGON ((-0.09326 51.49799, -0.09313 51.49789...	{'xmin': -0.09326370060443878, 'xmax': -0.0926...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	residential	terrace	9.084686	None	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
08b194ad33cedfff020023b576793edc	POLYGON ((-0.09322 51.49816, -0.09316 51.49823...	{'xmin': -0.09329734742641449, 'xmax': -0.0931...	0	[{'property': '', 'dataset': 'Microsoft ML Bui...	NaN	None	None	3.597508	None	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
08b194ad33c5afff02005bf97f15ef17	POLYGON ((-0.09222 51.49841, -0.09242 51.49821...	{'xmin': -0.09283170104026794, 'xmax': -0.0921...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	residential	terrace	9.935987	None	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
08b194ad33c58fff020045b4d3cd0be8	POLYGON ((-0.09164 51.49822, -0.09224 51.4976,...	{'xmin': -0.09225880354642868, 'xmax': -0.0915...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	residential	terrace	9.785714	None	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN

1861 rows × 23 columns

With release version¶

Release version can also be passed explicitly.

In [4]:

Copied!

overture_maps_release = "2024-08-20.0"
overture_maps_release = "2024-08-20.0"

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:10

Out[5]:

	geometry	bbox	version	sources	subtype	class	names	connector_ids	connectors	routes	subclass	subclass_rules	access_restrictions	level_rules	destinations	prohibited_transitions	road_surface	road_flags	speed_limits	width_rules
id
085194ad3fffffff046f75a1b0889168	LINESTRING (-0.14701 51.50703, -0.14505 51.506...	{'xmin': -0.1470058113336563, 'xmax': -0.11819...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	rail	None	{'primary': 'Jubilee Line', 'common': None, 'r...	[08f195da4972ccb1046b7363965b6176, 08f195da490...	[{'connector_id': '08f195da4972ccb1046b7363965...	None	None	None	None	None	None	None	None	None	None	None
085194ad3fffffff046f778d82830f4b	LINESTRING (-0.11856 51.50197, -0.12083 51.501...	{'xmin': -0.14705200493335724, 'xmax': -0.1185...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	rail	None	{'primary': 'Jubilee Line', 'common': None, 'r...	[08f194ad326cdd26046fffba98e01ca3, 08f195da490...	[{'connector_id': '08f194ad326cdd26046fffba98e...	None	None	None	None	None	None	None	None	None	None	None
085194ad3fffffff047b7650d73bf5bb	LINESTRING (-0.1391 51.50612, -0.13796 51.5060...	{'xmin': -0.13909630477428436, 'xmax': -0.1169...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	rail	None	{'primary': 'Jubilee Line', 'common': None, 'r...	[08f195da49048548046fbf988d1c4569, 08f195da49a...	[{'connector_id': '08f195da49048548046fbf988d1...	None	None	None	None	None	None	None	None	None	None	None
085194ad3fffffff047fbf509cee35f4	LINESTRING (-0.13905 51.50639, -0.13826 51.506...	{'xmin': -0.13904720544815063, 'xmax': -0.1169...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	rail	None	{'primary': 'Jubilee Line', 'common': None, 'r...	[08f195da4904eb59047b7c9a78e057c7, 08f195da49a...	[{'connector_id': '08f195da4904eb59047b7c9a78e...	None	None	None	None	None	None	None	None	None	None	None
082194ffffffffff047bf122dba8fb9f	LINESTRING (-0.12253 51.53837, -0.12253 51.536...	{'xmin': -0.22232520580291748, 'xmax': -0.1199...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	rail	None	{'primary': 'Piccadilly Line', 'common': None,...	[08f195da4d93289d047b7f1fa226561e, 08f195da4db...	[{'connector_id': '08f195da4d93289d047b7f1fa22...	None	None	None	None	None	None	None	None	None	None	None
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
082194ffffffffff046b7f449df5cef3	LINESTRING (-0.14366 51.49584, -0.14358 51.496...	{'xmin': -0.14374691247940063, 'xmax': -0.0208...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	rail	None	{'primary': 'Victoria Line', 'common': None, '...	[08f194ad1682d270047f3fe656089657, 08f194ad169...	[{'connector_id': '08f194ad1682d270047f3fe6560...	None	None	None	None	None	None	None	None	None	None	None
082194ffffffffff046f7e866209d3d7	LINESTRING (-0.07204 51.58337, -0.07419 51.582...	{'xmin': -0.14353470504283905, 'xmax': -0.0720...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	rail	None	{'primary': 'Victoria Line', 'common': None, '...	[08f194e693634033047b7fd3d7be8483, 08f195da689...	[{'connector_id': '08f194e693634033047b7fd3d7b...	None	None	None	None	None	None	None	None	None	None	None
081197ffffffffff047dfab323e684b3	LINESTRING (3.18966 51.34097, 3.19028 51.34133...	{'xmin': -1.160074234008789, 'xmax': 3.2051448...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	water	None	{'primary': 'Zeebrugge - Teesport', 'common': ...	[08f194dc60a10da6047db38647ca5dda, 08f1946568a...	[{'connector_id': '08f194dc60a10da6047db38647c...	None	None	None	None	None	None	None	None	None	None	None
08019fffffffffff047be35289e98060	LINESTRING (-6.33657 52.25383, -6.34007 52.256...	{'xmin': -6.340971946716309, 'xmax': 2.1850199...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	water	None	{'primary': 'Rosslare - Dunkerque', 'common': ...	[08f1828a35741294047fa3efe7079650, 08f1948badd...	[{'connector_id': '08f1828a35741294047fa3efe70...	None	None	None	None	None	None	None	None	None	None	None
08019fffffffffff047dfb89a3c4b14d	LINESTRING (-6.33486 52.25478, -6.33887 52.256...	{'xmin': -6.338866233825684, 'xmax': 0.1142107...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	water	None	{'primary': 'Rosslare - Le Havre', 'common': N...	[08f1828a353926760467e332afce561d, 08f1865c81b...	[{'connector_id': '08f1828a353926760467e332afc...	None	None	None	None	None	None	None	None	None	None	None

2387 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:04

Out[6]:

	geometry	bbox	version	sources	level	subtype	class	names	source_tags	wikidata	is_salt	is_intermittent
id
08b194ad14890fff0004bb2f94f849d2	LINESTRING (-0.12949 51.48589, -0.12944 51.485...	{'xmin': -0.12949131429195404, 'xmax': -0.1114...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	river	river	{'primary': 'River Thames', 'common': [('af', ...	[(waterway, river)]	None	None	None
08b194ad32b5cfff0004bbf13ef18490	LINESTRING (-0.09573 51.50928, -0.0953 51.5091...	{'xmin': -0.09572990238666534, 'xmax': -0.0923...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	river	river	{'primary': 'River Thames', 'common': [('af', ...	[(waterway, river)]	None	None	None
08b194ad306b4fff0004b7f550a24be0	LINESTRING (-0.09236 51.50845, -0.09193 51.508...	{'xmin': -0.09236110001802444, 'xmax': -0.0890...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	river	river	{'primary': 'River Thames', 'common': [('af', ...	[(waterway, river)]	None	None	None
08b194ada0a25fff0004c5f21a1ea31b	POLYGON ((-0.12003 51.50062, -0.12002 51.50068...	{'xmin': -0.3220961093902588, 'xmax': -0.08711...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	river	river	None	[(natural, water), (water, river)]	None	None	None

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("City of London"),
    sort_result=False,
    ignore_cache=True,
)
unsorted_pq = om.convert_geometry_to_parquet(
    theme="buildings",
    type="building",
    geometry_filter=om.geocode_to_geometry("City of London"),
    sort_result=False,
    ignore_cache=True,
)

Finished operation in 0:00:04

In [9]:

Copied!





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

Finished operation in 0:00:05

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]:

['2025-03-19.1',
 '2025-03-19.0',
 '2025-02-19.0',
 '2025-01-22.0',
 '2024-12-18.0',
 '2024-11-13.0',
 '2024-10-23.0',
 '2024-09-18.0',
 '2024-08-20.0',
 '2024-07-22.0',
 '2024-06-13-beta.1',
 '2024-06-13-beta.0',
 '2024-05-16-beta.0',
 '2024-04-16-beta.0']

Get newest available releave version¶

In [12]:

Copied!

om.get_newest_release_version()
om.get_newest_release_version()

Out[12]:

'2025-03-19.1'

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', '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.