Documentation

Overview

Beyond vector tiles, geolith can emit geocoding indexes from the same Overture data using --output-format geocoding. Three formats are supported:

FormatFlagOutputTarget
PostgreSQL COPY--geocoding-format pg-copy (default).tsvCOPY into Postgres full-text search
Photon--geocoding-format photon.ndjsonPhoton geocoder import
Pelias--geocoding-format pelias.ndjsonElasticsearch _bulk API
geolith \
  --data ./data/overture \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons \
  --output ./data/planet.pmtiles \
  --output-format geocoding \
  --geocoding-format pelias \
  --geocoding-output ./data/geocoding.ndjson

--bbox works the same as in tile builds — only features inside the box are indexed.

What Gets Indexed

Overture sourceGeocoding layer
places/placevenue — requires a primary name; carries categories, confidence, and multilingual names
addresses/addressaddress — requires a street or house number; carries number/street/unit/postcode
buildings/buildingPelias only — separate flat-schema buildings index (see below)

Pelias Format

The Pelias output is Elasticsearch bulk NDJSON — pairs of action + document lines compatible with the pelias-model document shape:

{"index":{"_index":"pelias","_id":"overture:venue:08f2a100d388cfff0200724f76a3f4e8"}}
{"source":"overture","layer":"venue","source_id":"08f2a100d388cfff0200724f76a3f4e8","name":{"default":"Blue Bottle Coffee","es":"Cafe Blue Bottle"},"phrase":{"default":"Blue Bottle Coffee","es":"Cafe Blue Bottle"},"center_point":{"lon":-122.4194,"lat":37.7749},"category":["cafe","coffee_shop"],"addendum":{"overture":"{\"confidence\":0.97,...}"}}

Key properties of the document shape:

  • _id is the Pelias GID: {source}:{layer}:{source_id} with the original lowercased Overture GERS UUID.
  • phrase is a literal copy of name; multilingual names live inside name as per-language keys.
  • parent.* admin hierarchy values are arrays (country, country_a, region, county, locality, neighbourhood), with alpha-3 country codes in country_a.
  • category is a lowercased array built from basic_category → taxonomy → categories in priority order.
  • addendum.overture is a JSON-stringified string (the pelias-model codec convention) carrying confidence, category provenance, and contact fields.
  • center_point coordinates are rounded to 6 decimals.
  • Empty objects are omitted entirely — never emitted as {}.

Import with:

curl -s -H "Content-Type: application/x-ndjson" \
  -XPOST "http://localhost:9200/_bulk" \
  --data-binary @geocoding.ndjson

Buildings Index (Pelias only)

When Overture buildings data is present, the Pelias format additionally writes <stem>-buildings.ndjson targeting a separate overture-buildings index. Buildings use a flat Overture-schema document, not the Pelias document model:

{"index":{"_index":"overture-buildings","_id":"08b2a100d388cfff"}}
{"id":"08b2a100d388cfff","source":"overture","theme":"buildings","type":"building","centroid":{"lat":37.775,"lon":-122.415},"geometry":{"type":"Polygon","coordinates":[...]},"bbox_shape":{"type":"envelope","coordinates":[...]},"class":"residential","height":12.5,"num_floors":4}
  • _id is the raw lowercased building ID (no source:layer: prefix).
  • centroid is a {lat, lon} object (Elasticsearch geo_point).
  • geometry is GeoJSON, stored as geo_shape.
  • bbox_shape is an Elasticsearch envelope for fast bounding-box queries.
  • Physical attributes (height, num_floors, class, subtype, roof/facade fields) are included when present.

Admin Hierarchy

Each record is enriched with a resolved admin hierarchy (country → region → county → locality → neighbourhood) via point-in-polygon lookups against Overture divisions. Address records additionally fall back to the Overture country and postal_city fields when spatial resolution yields nothing.