Skip to content

Overture Maps — Introduction#

earthlens.overture downloads vector features from the Overture Maps Foundation — an open, permissively-licensed basemap published as cloud GeoParquet. It wraps the official overturemaps SDK, which reads the data directly off the public, anonymous s3://overturemaps-us-west-2 bucket (no credentials), and returns a pyramids FeatureCollection (a GeoDataFrame) written to disk.

What it covers#

Overture organises the world into six themes, each a parent partition of the GeoParquet store. earthlens curates all of them:

Theme Feature types Geometry Scale Typical licenses
buildings building, building_part Polygon ~2.3 B footprints CDLA-Permissive-2.0, ODbL-1.0
places place Point ~57 M POIs CDLA-Permissive-2.0, ODbL-1.0
transportation segment, connector LineString / Point ~86 M km of roads CDLA-Permissive-2.0, ODbL-1.0
divisions division, division_area, division_boundary Point / Polygon / LineString admin boundaries CDLA-Permissive-2.0, ODbL-1.0
base land, land_use, land_cover, water, infrastructure, bathymetry mixed (polygon-dominant) land/water/infra basemap CDLA-Permissive-2.0, ODbL-1.0
addresses address Point point addresses CDLA-Permissive-2.0, ODbL-1.0

See Available datasets for the full theme/type reference.

Output kind#

Overture is a vector backend: the result is a table of geolocated features, not a gridded array. Two consequences follow:

  • Overture.OUTPUT_KIND == "vector", so the EarthLens facade rejects an aggregate= argument — there is no meaningful gridded reduction of a feature table.
  • Overture is a static per-release snapshot with no temporal axis, so start / end are accepted but ignored. Time is expressed only by the release (yyyy-mm-dd.x); the SDK auto-targets the newest release when you do not pin one.

The output is written as GeoParquet by default (which preserves Overture's deeply-nested schema — names, categories, sources, … — losslessly), with GeoPackage and GeoJSON as alternatives.

The headline feature — per-row licensing#

Overture rows carry per-feature provenance in a sources column, and different sources carry different licenses: the permissive bulk is CDLA-Permissive-2.0, but OpenStreetMap-derived rows carry ODbL-1.0, a share-alike license with attribution obligations. No other earthlens backend surfaces this, and for a downstream commercial user it is critical. earthlens.overture therefore:

  • adds a per-row license_id column to every result, and
  • emits a LicenseWarning when any ODbL-1.0 rows are present.

See the dedicated Licensing page for the derivation rule and the obligations.

How it maps onto the facade#

from earthlens.earthlens import EarthLens

paths = EarthLens(
    data_source="overture",
    variables={"places": []},          # {theme: [type, ...]}; [] = the theme's primary type
    lat_lim=[40.757, 40.759],          # bounded bbox is required
    lon_lim=[-73.987, -73.984],
    path="out",
).download()

download() returns the list of written file paths (one per requested feature type).

Install#

pip install earthlens[overture]

The only extra dependency is the overturemaps SDK (geopandas and pyarrow are already pulled in). No credentials, no account.

See Usage for the full request shape and every keyword argument, and Available datasets for the theme/type reference.