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.

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

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
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
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
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
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
08b194ad14812fff02006b5f7b4749e1	POLYGON ((-0.11623 51.49831, -0.11634 51.49819...	{'xmin': -0.11633940041065216, 'xmax': -0.1161...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	None	None	NaN	None	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
08b194ad30680fff0200af33c196cb96	POLYGON ((-0.09076 51.50688, -0.0908 51.50679,...	{'xmin': -0.09085220098495483, 'xmax': -0.0905...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	commercial	office	NaN	None	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
08b194ad30695fff02005d36dab55ea5	POLYGON ((-0.09138 51.50715, -0.09143 51.50706...	{'xmin': -0.09142860025167465, 'xmax': -0.0910...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	residential	apartments	NaN	None	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
08b194ad30686fff02000c3dc7eb8972	POLYGON ((-0.09097 51.50718, -0.09101 51.50709...	{'xmin': -0.09105861186981201, 'xmax': -0.0905...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	commercial	commercial	NaN	None	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
08b194ad32b6bfff0200c926a36ac497	POLYGON ((-0.09207 51.50842, -0.09203 51.50841...	{'xmin': -0.09206900000572205, 'xmax': -0.0919...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	2.0	None	None	NaN	None	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN
08b194ad306b6fff02006042711058eb	POLYGON ((-0.09169 51.50824, -0.09173 51.50816...	{'xmin': -0.09173200279474258, 'xmax': -0.0916...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	2.0	None	None	NaN	None	False	...	NaN	NaN	None	None	None	None	NaN	None	None	NaN

1862 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:07

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
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
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
084194adffffffff047fff2976eb9e18	LINESTRING (-0.18519 51.49496, -0.1847 51.4948...	{'xmin': -0.18518942594528198, 'xmax': -0.0753...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	rail	None	{'primary': 'Circle and District Lines', 'comm...	[08f194ada5890586047bff900aef1b11, 08f194ad165...	[{'connector_id': '08f194ada5890586047bff900ae...	None	None	None	None	None	None	None	None	None	None	None
084194adffffffff046fb689e755c681	LINESTRING (-0.07534 51.51346, -0.0755 51.5128...	{'xmin': -0.1801884025335312, 'xmax': -0.07522...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	rail	None	{'primary': 'Circle and District Lines', 'comm...	[08f194ad30156315046fbe53358ca30b, 08f194ad300...	[{'connector_id': '08f194ad30156315046fbe53358...	None	None	None	None	None	None	None	None	None	None	None
089194ad14d7ffff047f373a11370670	LINESTRING (-0.12 51.50069, -0.12012 51.5007, ...	{'xmin': -0.12371241301298141, 'xmax': -0.1199...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	road	footway	None	[08f194ad14d61c02047bff82a58a1117, 08f194ad14d...	[{'connector_id': '08f194ad14d61c02047bff82a58...	None	sidewalk	[{'value': 'sidewalk', 'between': None}]	[{'access_type': 'allowed', 'when': {'during':...	[{'value': 1, 'between': [0.0, 0.969046109]}]	None	None	[{'value': 'paved', 'between': None}]	[{'values': ['is_bridge'], 'between': [0.0, 0....	None	None
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
086194ad37ffffff046b7f6a4e072d20	LINESTRING (-0.07889 51.50727, -0.084 51.50705...	{'xmin': -0.09679721295833588, 'xmax': -0.0788...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	water	None	None	[08f194ad3076cb4a047fffc8541c9484, 08f194ad306...	[{'connector_id': '08f194ad3076cb4a047fffc8541...	None	None	None	None	None	None	None	None	None	None	None
086194ad37ffffff046bfcd3b02fef16	LINESTRING (-0.0968 51.50877, -0.09455 51.5089...	{'xmin': -0.09679721295833588, 'xmax': -0.0735...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	water	None	None	[08f194ad32a2aab6046f7f0cdcf055af, 08f194ad302...	[{'connector_id': '08f194ad32a2aab6046f7f0cdcf...	None	None	None	None	None	None	None	None	None	None	None
082194ffffffffff047f4f9d64e32154	LINESTRING (-0.10492 51.50439, -0.10161 51.504...	{'xmin': -0.1049221009016037, 'xmax': 0.011308...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	rail	None	{'primary': 'Jubilee Line', 'common': None, 'r...	[08f194ad32220ce6046f3dcf7b36f1f5, 08f194ad33d...	[{'connector_id': '08f194ad32220ce6046f3dcf7b3...	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
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

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

Out[6]:

	geometry	bbox	version	sources	level	subtype	class	names	source_tags	wikidata	is_salt	is_intermittent
id
08b194ada0a25fff0004ce6fac635a0f	POLYGON ((-0.12002 51.50068, -0.11999 51.50078...	{'xmin': -0.3220961093902588, 'xmax': -0.08711...	0	[{'property': '', 'dataset': 'OpenStreetMap', ...	NaN	river	river	None	[(natural, water), (water, river)]	None	None	None
08b194ad14890fff0004b63856a213bf	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
08b194ad32b5cfff0004b972c7b92208	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
08b194ad306b4fff0004bc75d37bcb29	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

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

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

Copied!

om.get_available_release_versions()
om.get_available_release_versions()

Out[8]:

['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 [9]:

Copied!

om.get_newest_release_version()
om.get_newest_release_version()

Out[9]:

'2024-12-18.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 [10]:

Copied!

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

Out[10]:

[('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.

In [11]:

Copied!

om.get_available_theme_type_pairs()
om.get_available_theme_type_pairs()

Out[11]:

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