Maps

Overview

Maps proxies customer geospatial APIs to the VijiMaps upstream and provides browser map rendering via MapLibre (@vijihub/maps-gl). Data APIs are reached through Gateway paths under /maps.

API

{pe} = /projects/{projectId}/environments/{environmentId}.

Gateway routes are catch-all proxies:

Method	Path	Notes
GET	`/maps/health`	Health
*	`/maps/public/` and `/maps/public/{*path}`	API key (full scope)
*	`/maps{pe}/public/` and `/maps{pe}/public/{*path}`	API key or owner JWT

Upstream shapes (locations, roads, POIs, routing, OV zones, basemap/tiles, …) are documented in the Maps OpenAPI artifact in the repo (vijimaps_docs/vijimaps-api-public-docs/openapi.yaml). Remap upstream public paths to Gateway /maps/public/....

Clients

Package	Runtime
`@vijihub/maps`	server
`@vijihub/maps-gl`	browser (MapLibre; no `vh_` key)
`VijiHub.Maps`	.NET

// Browser map (no API key)
import { createMap } from '@vijihub/maps-gl'

Browser  →  @vijihub/maps-gl
Browser  →  Your BFF (session)
Your BFF →  @vijihub/maps + full vh_  →  Gateway /maps/...

Implementation

Enable Maps on the environment and ensure upstream VijiMaps connectivity from the Gateway.
Use @vijihub/maps-gl in the frontend for tiles/interaction.
Call data endpoints from a BFF with @vijihub/maps or raw HTTP + full API key / JWT.
Prefer /maps{pe}/public/{*path} when binding to a specific project environment with JWT.

Constraints

Never put unrestricted Maps API keys in frontend bundles.
/maps/public/... requires a full-scope project API key.
Browser package does not replace authenticated data APIs.
See Constraints for the canonical Maps pattern.