`geocoder://`¶

Forward and reverse geocoding. Forward turns an address into coordinates; reverse turns coordinates into an address. Two providers are supported: Nominatim (OpenStreetMap, the default, no API key) and Google Maps (requires apiKey). It is the enrichment step of Helix's GIS surface — its coordinates feed geo://, sl::gis, and geospatial RAG.

URI shape¶

geocoder://<forward|reverse>?provider=nominatim&limit=1&language=en&apiKey=...&baseURL=...

Producer-only — CreateConsumer returns an error.

Token	Description
`<operation>`	Required — `forward` (address → coordinates) or `reverse` (coordinates → address).

Parameters¶

Param	Type	Default	Producer/Consumer/Both	Description
`provider`	string	`nominatim`	Producer	`nominatim` or `google`.
`apiKey`	string	—	Producer	Required for `provider=google`.
`limit`	integer	`1`	Producer	`forward` — max results. `1` returns a single object; `>1` returns an array.
`language`	string	—	Producer	Preferred result language (sent as `Accept-Language`).
`userAgent`	string	`helix-geocoder/1.0`	Producer	User-Agent sent to the provider (Nominatim requires a real one).
`timeout`	duration	`15s`	Producer	HTTP request timeout.
`baseURL`	string	—	Producer	Override the provider base URL (self-hosted Nominatim, or a test server).

Operations¶

`forward`¶

Address in, coordinates out.

Input — the address as either the body (a string) or the geocoder.address header. Output — a normalized result ({lat, lon, displayName, ...}); a single object when limit=1, or an array when limit>1.

`reverse`¶

Coordinates in, address out.

Input — the point as any of: a [lon, lat] array body, a {lat, lon} / {lat, lng} object body, or the geocoder.lat + geocoder.lon headers. Output — the matched place ({displayName, address, ...}).

Headers¶

Read by the producer¶

Header	Description
`geocoder.address`	`forward` — the address to geocode (alternative to the body).
`geocoder.lat` / `geocoder.lon`	`reverse` — the point to reverse-geocode (alternative to the body).

Written by the producer¶

Header	Description
`HelixGeoLat`	Latitude of the (first) result.
`HelixGeoLng`	Longitude of the (first) result.
`HelixGeoDisplayName`	Human-readable name/address of the result.
`HelixGeoProvider`	Provider used (`nominatim` / `google`).
`HelixGeoResultCount`	Number of results returned.

HelixGeo* headers are Helix-internal (stripped on egress).

Examples¶

Forward geocode an address (Nominatim, no key):

- set-body:
    constant: "1600 Amphitheatre Parkway, Mountain View, CA"
- target: geocoder://forward
# body -> {"lat":37.42, "lon":-122.08, "displayName":"..."}; HelixGeoLat/Lng set

Forward geocode via a header, top 5 results (array), with Google:

- set-header:
    name: geocoder.address
    constant: "Springfield"
- target: geocoder://forward?provider=google&apiKey=${GOOGLE_MAPS_KEY}&limit=5

Reverse geocode a coordinate:

- target: geocoder://reverse
# body [-122.08, 37.42] -> {"displayName":"1600 Amphitheatre Pkwy, ..."}

Chain geocoding into a geo:// operation:

- set-body:
    constant: "Eiffel Tower, Paris"
- target: geocoder://forward          # -> {lat, lon, ...} + HelixGeoLat/Lng
- transform:
    starlang: |
      %sl 2.0
      output application/json
      ---
      [input.lon, input.lat]
- target: geo://geohash?precision=8   # geohash of the geocoded point

Behavior notes¶

Nominatim usage policy — the public endpoint rate-limits and requires a real User-Agent; for volume, run your own Nominatim and point baseURL at it.
baseURL — overrides the provider endpoint; this is also the test seam (mirrors qdrant's url).
Provider parity — both providers normalize to the same result shape and the same HelixGeo* headers, so routes are provider-agnostic.
Producer-only — use it as a target: step.

Source¶

pkg/component/geocoder/geocoder.go

geocoder://¶