Skip to Content
Importing DataSourcesOverture Maps

Importing Overture Maps data into Geobase

Use the project worker job overtureImportArea (or Studio Overture Import Map) to download selected Overture Maps  layers for an AOI into your Geobase project Postgres.

Useful when OpenStreetMap coverage is thin (for example buildings). The request shape is close to osmImportArea so apps can swap job paths.

  1. Open your project → Data Importer → Map imports → Overture Import Map.
  2. Draw one or more AOIs and name each area (table prefix).
  3. Select Overture types (see blurbs in the sidebar; theme guides  for detail).
  4. Import, then poll until success — or Cancel while pending/running.

Default types in the UI are often building and segment. Output tables use {prefix}_{suffix} with source = overture.

Prerequisites (API)

  1. Healthy Geobase project (GEOBASE_PROJECT_URL / project ref).
  2. Server-side GEOBASE_SERVICE_ROLE_KEY (never from browser code).
  3. AOI as GeoJSON Polygon or MultiPolygon, WGS84 (EPSG:4326), closed rings.
  4. Worker has GEOBASE_PROJECT_DB_URI for the project database (hosted stacks already do).

Endpoints

MethodPath
POST{origin}/worker/jobs/overtureImportArea
GET{origin}/worker/jobs/overtureImportArea/{job_id}
GET{origin}/worker/jobs/overtureImportArea/latest
DELETE{origin}/worker/jobs/overtureImportArea/{job_id} — cancel pending/running

Studio proxy: /api/projects/{ref}/jobs/overtureImportArea.

OpenAPI: {origin}/worker/doc and {origin}/worker/ui.

Layer selection

Resolution order:

  1. types — Overture feature types (preferred), e.g. ["building", "segment", "water"]
  2. topics — shortbread/kblock aliases, e.g. ["buildings", "streets"] or ["kblock"] → buildings only
  3. Default — ["building"] if both omitted

Common types → tables

typesMeaning (short)Output table
buildingStructure footprints{prefix}_buildings
segmentRoads / paths (lines){prefix}_streets
waterWater bodies / waterways{prefix}_water
placePOIs / named places{prefix}_places
landLand polygons{prefix}_land
land_useLand use areas{prefix}_land_use
addressAddress points{prefix}_addresses

Full worker allow-list and aliases: OpenAPI description, agent skills (@geobase-worker-overture-import), and geobase-skills . Upstream themes: Overture guides .

Output columns

area_id (bigint), geom (4326), tags (jsonb), source = overture.

Example request

curl -sS -X POST "${GEOBASE_PROJECT_URL}/worker/jobs/overtureImportArea" \
  -H "apikey: ${GEOBASE_SERVICE_ROLE_KEY}" \
  -H "Authorization: Bearer ${GEOBASE_SERVICE_ROLE_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "areaName": "demo_aoi",
    "tablePrefix": "demo_aoi",
    "types": ["building", "segment"],
    "mode": "replace",
    "aoiGeoJson": {
      "type": "Polygon",
      "coordinates": [[[10.0, 59.0], [10.1, 59.0], [10.1, 59.1], [10.0, 59.1], [10.0, 59.0]]]
    }
  }'

Poll:

curl -sS "${GEOBASE_PROJECT_URL}/worker/jobs/overtureImportArea/<job_id>" \
  -H "apikey: ${GEOBASE_SERVICE_ROLE_KEY}" \
  -H "Authorization: Bearer ${GEOBASE_SERVICE_ROLE_KEY}"

Cancel:

curl -sS -X DELETE "${GEOBASE_PROJECT_URL}/worker/jobs/overtureImportArea/<job_id>" \
  -H "apikey: ${GEOBASE_SERVICE_ROLE_KEY}" \
  -H "Authorization: Bearer ${GEOBASE_SERVICE_ROLE_KEY}"

On success, job metadata includes types, layers ([{ type, table, inserted }]), and totals.

Modes and size limits

  • mode: replace (default) clears each target table before insert; union appends / upserts by area_id.
  • Imports use the AOI bounding box (exact polygon clip is a follow-up).
  • Size guards (env): OVERTURE_MAX_BBOX_AREA_SQ_DEG (default 1.0), OVERTURE_MAX_FEATURES_PER_TYPE (50000), OVERTURE_MAX_FEATURES_TOTAL (100000). Prefer small AOIs; start with one type.
Last updated on
OpenStreetMaposm2pgsql (advanced)