decision-labs/geobase-skills/geobase-worker-overture-import

Worker: Overture Maps Import

When to use this skill

• Import Overture Maps layers into a Geobase project via overtureImportArea
• Fill gaps when OSM building (or other) coverage is thin — e.g. geobase-kblock workspaces
• Select specific Overture types (building, segment, water, place, …)
• Not for OSM (@geobase-worker-osm-import) or local file import (@geobase-project-db-data-import)

Authoritative worker spec: apps/worker/specs/OVERTURE_IMPORT.md in the Geobase monorepo. OpenAPI: worker GET /ui / GET /doc.

Secrets (human in the loop)

Worker HTTP needs `GEOBASE_SERVICE_ROLE_KEY`. Agents cannot obtain it. Ask the user to put it in a gitignored `.env.secrets`. Do not paste keys in chat. See @geobase → Secrets (human in the loop).

The worker process also needs `GEOBASE_PROJECT_DB_URI` (project Postgres) in its environment — that is how features are written.

Required inputs

• @geobase → private-beta / Studio path if CLI unavailable
• project_ref
• GEOBASE_SERVICE_ROLE_KEY in local secrets
• Payload JSON:
• areaName (required)
• aoiGeoJson — Polygon or MultiPolygon, WGS84, closed rings
• tablePrefix (optional; defaults to areaName)
• mode — replace (default) | union
• layers: prefer `types`; or `topics`; omit both → building only
• theme — accepted for osmImportArea/kblock drop-in; ignored

Layer selection

Resolution order: types → topics → default ["building"].

Overture types → output tables

Topic aliases (when types omitted)

Raw Overture type names are also valid inside topics.

Output columns

area_id (bigint PK), geom (typed 4326), tags (jsonb, includes overture_type), source = overture.

Size guards (fail fast)

Prefer small AOIs. Reproject shapefiles to EPSG:4326 before submit (source CRS mistakes are common).

Procedure

1. Session / project: geobase-cli whoami, geobase-cli projects refs (or Studio project_ref).
2. Env: geobase-cli projects env <ref> --persona web --format dotenv for non-secrets; user sources .env.secrets for service role.
3. Validate AOI:

• WGS84 lon/lat (not UTM meters)
• closed rings; Polygon or MultiPolygon

1. Validate tablePrefix: prefer ^[a-z][a-z0-9_]{0,62}$ (same hygiene as OSM skill). Worker also accepts ^[a-zA-Z_][a-zA-Z0-9_]*$.
2. Collision check: ensure {prefix}_{suffix} tables for selected types do not already exist (or user approved mode: replace).
3. Prefer explicit types for clarity. Start with one type (e.g. building) on first run.
4. Submit:

• POST https://${GEOBASE_PROJECT_REF}.geobase.app/worker/jobs/overtureImportArea
• headers: apikey + Authorization: Bearer = service role; Content-Type: application/json
• Studio proxy (when available): POST /api/projects/{ref}/jobs/overtureImportArea

1. Poll: GET .../worker/jobs/overtureImportArea/<job_id> — 5s then backoff (10s / 20s / 30s).
2. On success: check metadata types, layers ([{type,table,inserted}]), row counts, source=overture.

Example payload

{
  "areaName": "habitat_geisha",
  "tablePrefix": "habitat_geisha",
  "types": ["building", "segment", "water"],
  "mode": "replace",
  "aoiGeoJson": {
    "type": "Polygon",
    "coordinates": [[[33.9880641, -11.47290614], [33.98889819, -11.47421489], [33.98935488, -11.47574151], [33.9880641, -11.47290614]]]
  }
}

(kblock drop-in: same shape as osmImportArea with theme/topics: ["kblock"] → buildings only.)

Submit rule (mandatory)

Only submit when AOI CRS is WGS84, prefix/collision checks passed, and layer selection matches user intent. Never silently enlarge the AOI or add heavy types (land_cover, bathymetry, divisions) without approval.

Failure handling

• Auth → refresh service role in .env.secrets
• Schema / unknown type → fix types / topics against the table above
• Size-guard errors → shrink AOI, fewer types, or raise env limits with user approval
• Wrong CRS / empty results → reproject AOI to WGS84; confirm bbox on a map
• Missing Python deps on local worker → pip install -r apps/worker/tasks/requirements-overture.txt (no overturemaps[geopandas])
• Preserve failed job_id and truncated result for debugging

Related skills

• @geobase-worker-osm-import — OpenStreetMap import (shortbread topics)
• @geobase-project-db-data-import — local files via ogr2ogr
• @geobase — secrets, project ref, routing