Elonn Docs Platform Documentation

maps

maps.elonn.local is the geographic object service for Elonn. Production is maps.elonn.com.

Maps owns live geographic facts and point-of-interest normalization. World does not keep geographic truth of its own — maps is the authority.

Owns

  • nearby place lookup and normalization
  • reverse geocoding and geocoding
  • point-of-interest coordinates and categories
  • provider-neutral map presentation contracts for place surfaces

Role in the stack

Maps provides the spatial foundation of the Elonn world. World consumes geographic objects from maps and includes them in the runtime contract. Web renders those objects in a 360-degree demo panorama. Android renders those objects over the live camera view from device orientation. The service data path stays the same across runtimes.

Key terms

Field — the shared spatial panorama visible to all members. Field objects are placed at coordinates within the field. The maps service produces geographic objects for the field; the output is not called a "map."

Marker — a visual point-of-interest placed in the field, authored by the maps service and rendered differently by each runtime.

Field width — field_width is the panoramic width in abstract units used by the web runtime for layout.

Readiness

Maps exposes GET /ready as its readiness check. It confirms database connectivity before the service is considered ready for runtime composition.

Verification

Maps has a local smoke test suite through the platform smoke target:

bash docs.elonn.local/test.sh

The platform smoke suite verifies that GET /ready returns elonn_maps when the service is ready.

Routes

  • GET /health
  • GET /ready
  • GET /db-check
  • GET /maps/session
  • GET /maps/objects
  • GET /maps/geo/nearby
  • GET /maps/geo/lookup
  • GET /maps/geo/reverse
  • GET /maps/presentation

GET /maps/presentation?lat={latitude}&lon={longitude} returns elonn.map.runtime version 1: viewport center and zoom, declared raster layers, markers, and attribution. It does not create a Surface and it is not a runtime endpoint. Surface consumes it while translating a place finding; runtimes receive the result through World inside a map_surface.

Canonical terms

  • field — the shared spatial panorama; authority: maps.elonn.local
  • marker — visual POI in the field
  • maps — the spatial data service