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.
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.
london_bbox = (-0.120077, 51.498164, -0.090809, 51.508849)
buildings_gdf = om.convert_bounding_box_to_geodataframe(
theme="buildings", type="building", bbox=london_bbox
)
buildings_gdf
Finished operation in 0:00:03
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.
overture_maps_release = "2024-08-20.0"
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
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.
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
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
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()
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 significantly reduce the file size.
Sorting can be disabled by the user.
unsorted_pq = om.convert_bounding_box_to_parquet(
theme="buildings", type="building", bbox=london_bbox, sort_result=False
)
Finished operation in 0:00:02
sorted_pq = om.convert_bounding_box_to_parquet(
theme="buildings", type="building", bbox=london_bbox, sort_result=True
)
Finished operation in 0:00:00
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.
om.get_available_release_versions()
['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¶
om.get_newest_release_version()
'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.
om.get_available_theme_type_pairs(overture_maps_release)
[('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.