Telemap Developer Docs

Getting started

Three things you need before making a real call: a base URL, an API key, and a vehicle profile (for routing calls). This section walks through all three.

1. Get an API key

   There's no self-serve signup yet — keys are issued by running a script against a live stack:

   Copy./scripts/issue-api-key.py acme-corp                      # standard tier, 60 req/min
   ./scripts/issue-api-key.py acme-corp-trial --tier sandbox  # free trial tier, 10 req/min, never billed

   This appends a new consumer to gateway/kong.yml and hot-reloads Kong's config — no restart needed. Just trying things out? Ask for a --tier sandbox key.

2. Call the gateway, not a direct service port

   Every real request goes to http://localhost:8010 with your key in an apikey header (or query param):

   Copycurl -H "apikey: YOUR_KEY" \
     "http://localhost:8010/route?profile=car&from=85.3240,27.6710&to=85.4298,27.6710"

   No key or a bad one returns 401. A missing/invalid profile, malformed coordinates, or a point too far from any mapped road returns 400 from the underlying service — see each endpoint's own error list below.

3. Watch your rate limit

   Standard keys get 60 requests/minute; sandbox keys get 10/minute. Every response carries RateLimit-* and Retry-After headers, and going over the limit returns 429.

4. Pick a vehicle profile

   Every routing call needs a profile: car, bus, motorcycle, or truck. Each is backed by its own OSRM graph with real vehicle dimensions (height/width/length/weight) checked against OSM tags — a bus and a car can legitimately get routed onto different roads, not just scored with different ETAs on the same route.

5. Explore interactively (optional, dev-only)

   Each backend service serves its own Swagger UI directly, unauthenticated, for poking at requests without writing any code:

   routing-api

   localhost:8000/docs →

   geocoding-api

   localhost:8001/docs →

   live-tracking

   localhost:8002/docs →

   These talk straight to the backend, bypassing the gateway entirely — fine for local exploration, not the path a real integration should use.

API versioning

Every endpoint on this page is implicitly v1 — unprefixed paths, no version header. Check which version a service is serving with GET /version on any of the three backends:

Copycurl "http://localhost:8000/version"
# {"service": "routing-api", "api_version": "v1"}

When a breaking change is actually needed, it lands as a new path prefix (e.g. /v2/route) introduced alongside the existing v1 endpoint, which stays live through a deprecation window — never a retroactive rename or an abrupt cutoff.

Guides

Task-oriented walkthroughs for each feature. For the exhaustive param-by-param contract, see the API reference below — these guides link into it.

Plan a route

GET /route plans between exactly two points for one vehicle profile:

Copycurl -H "apikey: YOUR_KEY" \
  "http://localhost:8010/route?profile=car&from=85.3240,27.6710&to=85.4298,27.6710"

Copy{"profile": "car", "distance_km": 11.906, "duration_min": 12.57, "geometry": null}

Get a realistic ETA

GET /eta takes the same inputs as /route but blends real historical speeds (where the road segment has been driven before) with a static per-profile average as fallback — instead of OSRM's optimistic legal-speed duration:

Copycurl -H "apikey: YOUR_KEY" \
  "http://localhost:8010/eta?profile=bus&from=85.3240,27.6710&to=85.4298,27.6710"

Copy{
  "profile": "bus", "distance_km": 11.938, "osrm_duration_min": 14.52,
  "eta_min": 43.03, "static_eta_min": 44.77,
  "average_speed_kmh": 16.0, "historical_coverage_pct": 5.9
}

historical_coverage_pct tells you how much of the route's distance was actually backed by real driven history (vs. the static fallback) — a route with zero coverage returns eta_min == static_eta_min exactly. All three numbers (eta_min, static_eta_min, osrm_duration_min) are returned together so you can see how far apart they are. Full reference: GET /eta.

Multi-stop routes

For a route through more than two points — an office shuttle's pickup list, a freight pickup-then-delivery run — use GET /route/stops with 2–25 waypoints, visited in the order you give them:

Copycurl -H "apikey: YOUR_KEY" \
  "http://localhost:8010/route/stops?profile=bus&waypoints=85.3157,27.6997;85.2803,27.6939;85.3127,27.7167"

Copy{
  "profile": "bus", "stop_count": 3, "distance_km": 15.916, "duration_min": 20.07,
  "legs": [
    {"from_index": 0, "to_index": 1, "distance_km": 9.1, "duration_min": 11.59},
    {"from_index": 1, "to_index": 2, "distance_km": 6.816, "duration_min": 8.48}
  ],
  "geometry": null
}

Map-match a GPS trace

POST /match snaps a sequence of noisy GPS pings onto the road network — the reverse problem from /route: given where a vehicle actually was, figure out which roads it drove.

Copycurl -X POST "http://localhost:8010/match?profile=car" \
  -H "apikey: YOUR_KEY" -H "Content-Type: application/json" -d '[
  {"lon": 85.3240, "lat": 27.6710, "timestamp": 1700000000},
  {"lon": 85.3300, "lat": 27.6720, "timestamp": 1700000015},
  {"lon": 85.3360, "lat": 27.6730, "timestamp": 1700000030}
]'

A ping too far from any mapped road comes back "matched": false instead of forcing a bad snap. A trace can split into multiple matchings (e.g. across a large time gap), each with its own confidence score. Pass annotations=true to also get per-road-segment distance/duration/speed, timestamped by interpolation — this is exactly what live-tracking uses to build the traffic history behind /eta. Full reference: POST /match.

Search & geocode

Forward search (free text → places) and reverse geocoding (coordinate → nearest place), over OpenStreetMap plus Geomate's own POIs:

Copycurl -H "apikey: YOUR_KEY" "http://localhost:8010/search?q=Thamel&limit=5"
curl -H "apikey: YOUR_KEY" "http://localhost:8010/reverse?lat=27.7172&lon=85.3240"

Every result carries source: "osm" or "custom" — that's how you tell a GeoMate-added POI (corporate offices, depots, landmarks not in OSM) apart from plain OSM data. Custom POIs aren't writable through this API yet — they're seeded in Postgres and synced into search via a script, read-only from the API's point of view. /reverse returns result: null (not a 404) when nothing is found nearby — a normal outcome, not an error. Full reference: GET /search · GET /reverse.

Live vehicle tracking

A GPS tracker (or a simulator standing in for one) posts pings one at a time to POST /ingest/{vehicle_id} — this endpoint is fleet-side, not gated by the gateway, so it's called directly against live-tracking's own port:

Copycurl -X POST "http://localhost:8002/ingest/bus-14?profile=bus" \
  -H "Content-Type: application/json" \
  -d '{"lat": 27.7000, "lon": 85.3200, "timestamp": 1786524200}'

Pings buffer per-vehicle in memory; a background loop flushes each vehicle's window to /match every ~20 seconds once it has at least 2 pings, and persists every matched road segment to Postgres. Check a vehicle's live status (buffer size, last flush outcome) through the gateway:

Copycurl -H "apikey: YOUR_KEY" "http://localhost:8010/vehicles/bus-14"

Full reference: POST /ingest/{vehicle_id} · GET /vehicles.

Live traffic overlay

Recent matched road segments, as GeoJSON, straight off the persisted match history — this is what a map viewer polls to draw a color-coded live traffic layer:

Copycurl -H "apikey: YOUR_KEY" "http://localhost:8010/traffic/segments?minutes=5"

Each feature carries speed_kmh — color it red under 15 km/h, orange 15–30, green above 30 (the same bands the reference map viewer and the JS SDK's TelemapMap use). The JS SDK wraps this whole flow (polling + rendering) in one call. Full reference: GET /traffic/segments.

Geofencing for ad triggers

Circular zones defined in Postgres — every ingested ping is checked against all of them (a real meter-radius check, not a flat-degrees approximation), and enter/exit transitions are logged. Built for Module C's location-triggered in-vehicle ad campaigns (e.g. "play this campaign when the bus is within 200m of the office").

Copycurl -H "apikey: YOUR_KEY" "http://localhost:8010/geofences"
curl -H "apikey: YOUR_KEY" "http://localhost:8010/geofences/events"

Monitor pipeline health

GET /alerts flags three kinds of gap in the live-tracking pipeline: dead trackers (a vehicle that's stopped sending pings), match errors (a vehicle whose most recent flush to routing-api failed), and a stalled pipeline (nothing new persisted anywhere, independent of any one vehicle). It's an ops endpoint — not gated by the gateway, and detection-only, no built-in alerting channel:

Copycurl "http://localhost:8002/alerts"

Wire the non-zero exit code of scripts/traffic-gap-check.py into cron or a monitoring system. Full reference: GET /alerts.

Embed the map (JS SDK)

The fastest path to a working map with search, routing, and live traffic in your own app:

Copyimport { TelemapClient, TelemapMap } from "@telemap/sdk";

const client = new TelemapClient({ apiKey: "YOUR_KEY" });
const results = await client.search("Thamel", { limit: 5 });

const telemap = new TelemapMap({ apiKey: "YOUR_KEY", container: "map", client });
telemap.traffic.setLiveEnabled(true); // polls trafficSegments() every 15s

No MapLibre import, no engine instance to configure — see the full SDK reference below, or the working example at sdk/example/ in the repo.

API reference

The complete contract for every endpoint across the three backend services, plus the gateway that sits in front of them. All three backends are FastAPI — interactive Swagger docs are auto-served at /docs on each direct port. routing-api and geocoding-api are stateless; live-tracking is not.

Gateway & auth

Source: gateway/kong.yml — Kong in DB-less/declarative mode, port 8010 (proxy). This is the actual customer-facing entrypoint; everything documented under "routing-api" / "geocoding-api" / "live-tracking" below describes each service's own contract, reached in production through this gateway, not its direct port.

routing-api

Source: services/routing/. Base URL (direct): http://localhost:8000. One vehicle profile per request — car, bus, motorcycle, or truck — each backed by its own OSRM graph with real vehicle dimensions checked against OSM tags.

Copycurl "http://localhost:8000/route?profile=car&from=85.3240,27.6710&to=85.4298,27.6710"

Copy{"profile": "car", "distance_km": 11.906, "duration_min": 12.57, "geometry": null}

Copycurl "http://localhost:8000/route/stops?profile=bus&waypoints=85.3157,27.6997;85.2803,27.6939;85.3127,27.7167"

Copy{
  "profile": "bus", "stop_count": 3, "distance_km": 15.916, "duration_min": 20.07,
  "legs": [
    {"from_index": 0, "to_index": 1, "distance_km": 9.1, "duration_min": 11.59},
    {"from_index": 1, "to_index": 2, "distance_km": 6.816, "duration_min": 8.48}
  ],
  "geometry": null
}

Copycurl "http://localhost:8000/eta?profile=bus&from=85.3240,27.6710&to=85.4298,27.6710"

Copy{
  "profile": "bus", "distance_km": 11.938, "osrm_duration_min": 14.52,
  "eta_min": 43.03, "static_eta_min": 44.77,
  "average_speed_kmh": 16.0, "historical_coverage_pct": 5.9
}

Copycurl -X POST "http://localhost:8000/match?profile=car" -H "Content-Type: application/json" -d '[
  {"lon": 85.3240, "lat": 27.6710, "timestamp": 1700000000},
  {"lon": 85.3300, "lat": 27.6720, "timestamp": 1700000015},
  {"lon": 85.3360, "lat": 27.6730, "timestamp": 1700000030}
]'

Copy{
  "profile": "car",
  "points": [
    {"input_index": 0, "matched": true, "lon": 85.324206, "lat": 27.670902, "matching_index": 0},
    {"input_index": 1, "matched": true, "lon": 85.329716, "lat": 27.672237, "matching_index": 0},
    {"input_index": 2, "matched": true, "lon": 85.335616, "lat": 27.673113, "matching_index": 0}
  ],
  "matchings": [
    {"index": 0, "confidence": 0.62, "distance_km": 1.67, "duration_min": 3.56, "geometry": null, "segments": null}
  ]
}

Copy{"from_node": 1832396853, "to_node": 1496663340, "distance_m": 44.11, "duration_s": 2.9, "speed_kmh": 54.72, "observed_at": 1786524870.4}

geocoding-api

Source: services/geocoding/. Base URL (direct): http://localhost:8001. Wraps Photon (which sits on Nominatim). Every query is logged for a weekly relevance-tuning report — nothing a caller needs to do.

Copycurl "http://localhost:8001/search?q=Thamel&limit=2"

Copy{
  "query": "Thamel",
  "results": [
    {
      "name": "Thamel", "lat": 27.7166578, "lon": 85.3127015,
      "osm_type": "place", "osm_value": "neighbourhood", "place_type": "locality",
      "source": "osm",
      "address": {"city": "Kathmandu", "state": "Bagmati Province", "country": "Nepal", "countrycode": "NP"}
    }
  ]
}

Copycurl "http://localhost:8001/reverse?lat=27.7172&lon=85.3240"

Copy{
  "lat": 27.7172, "lon": 85.324,
  "result": {
    "name": "Nano Hana Garden &Thakali Chulo", "lat": 27.7176566, "lon": 85.3242651,
    "osm_type": "amenity", "osm_value": "restaurant", "place_type": "house",
    "source": "osm", "address": {"city": "Kathmandu", "country": "Nepal"}
  }
}

live-tracking

Source: services/live-tracking/. Base URL (direct): http://localhost:8002. Different shape from the two above: this ingests a continuous stream of GPS pings per vehicle, buffers them in memory, and periodically hands each vehicle's window to routing-api's POST /match. No real GeoMate fleet feed is wired up yet — a simulator stands in.

Copycurl -X POST "http://localhost:8002/ingest/demo-car-1?profile=car" \
  -H "Content-Type: application/json" \
  -d '{"lat": 27.7000, "lon": 85.3200, "timestamp": 1786524200}'

Copy{"vehicle_id": "demo-car-1", "buffered_pings": 1}

Copycurl "http://localhost:8002/vehicles/demo-car-1"

Copy{"profile": "car", "buffered_pings": 1, "last_flush_at": null, "last_match_confidence": null, "last_match_error": null, "current_geofences": []}

Copycurl "http://localhost:8002/traffic/segments?minutes=5"

Copy{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {"type": "LineString", "coordinates": [[85.400175, 27.674118], [85.400201, 27.674111]]},
    "properties": {"speed_kmh": 24.84, "profile": "car", "vehicle_id": "sim-car-1", "observed_at": "2026-08-12T10:55:47.9+00:00"}
  }]
}

Copycurl "http://localhost:8002/alerts"

Copy{
  "checked_at": 1786552424.08, "gap_threshold_seconds": 90.0,
  "dead_trackers": [{"vehicle_id": "sim-car-1", "last_ingest_at": 1786552330.1, "seconds_since_ingest": 93.9}],
  "match_errors": [],
  "pipeline": {"last_observation_at": 1786552409.9, "seconds_since_last_observation": 14.2, "stale": false},
  "healthy": false
}

Copycurl "http://localhost:8002/geofences"

Copy[{"id": 1, "name": "GeoMate Head Office", "lon": 85.3157, "lat": 27.6997, "radius_m": 200.0, "metadata": {"ad_campaign": "hq-local-diner-promo"}}]

Copycurl "http://localhost:8002/geofences/events"

Copy[{"ts": 1786554678.1, "vehicle_id": "ad-geofence-demo", "zone_id": 1, "zone_name": "GeoMate Head Office", "event": "exit"}]

JS SDK

Source: the sibling telemap-sdk repo, not this one. TypeScript, built with esbuild into two bundles — an ESM build for your own bundler and a self-contained browser IIFE build. The underlying map engine (MapLibre GL JS today) is never exposed — nothing in the public API accepts, returns, or requires a MapLibre type or instance; every argument/return value is a named type under the Telemap namespace (Telemap.Pin, Telemap.Route.Plan, Telemap.Vehicle.Position, …), never a plain object. That's deliberate: it means the engine can be swapped later without breaking anything built against this SDK.

TelemapClient

A thin, fully-typed fetch wrapper over the gateway contract.

Copyimport { TelemapClient, type Telemap } from "@telemap/sdk";

const client = new TelemapClient({
  apiKey: "YOUR_KEY",
  baseUrl: "http://localhost:8010", // default
});

Every call rejects with a TelemapApiError (carrying status and body) on a non-2xx response. Field names are camelCase throughout (distanceKm, not distance_km) — the client translates the wire format, so the TypeScript-facing surface reads like a real SDK, not a JSON pass-through.

TelemapMap

A map pre-configured with Telemap's own style, plus telemap.pins (markers — no MapLibre knowledge required), telemap.traffic (the live overlay), telemap.routes (drawing a planned route's geometry), telemap.vehicles (live tracking + animation), and telemap.geofences (zone rendering + enter/exit events).

Copyimport { TelemapMap, type Telemap } from "@telemap/sdk";

const telemap = new TelemapMap({
  apiKey: "YOUR_KEY",
  container: "map",       // element id or HTMLElement
  center: [85.3240, 27.7172], // default: Kathmandu
  zoom: 12,
  theme: "light",          // "light" | "dark"
});

const pin: Telemap.Pin = { id: "hq", lon: 85.3157, lat: 27.6997, label: "GeoMate HQ" };
telemap.pins.add(pin, { onClick: (p) => console.log("clicked", p.id) });

await telemap.traffic.setLiveEnabled(true, { minutes: 5, pollMs: 15000 });

// Needs geometry: true, or draw() throws a clear error instead of drawing nothing.
const plan = await client.route("car", [85.3157, 27.6997], [85.2803, 27.6939], { geometry: true });
telemap.routes.draw("hq-to-depot", plan); // fits the camera to it by default

// telemap.vehicles: bring-your-own-data (path 1) — no Telemap backend involved,
// the SDK just renders it, animating between hops and rotating to face travel.
telemap.vehicles.update("bus-14", { lat: 27.6997, lon: 85.3157, timestamp: Date.now() / 1000 });

// telemap.vehicles: Telemap-managed (path 2) — pings ingested elsewhere via
// client.ingest()/POST /ingest, polled back and fed into the same update().
telemap.vehicles.track("bus-14", { pollMs: 3000 });

// telemap.geofences: zones are global, read-only data -- one fixed overlay of
// real geodesic circles, plus a delivery hook for enter/exit events.
await telemap.geofences.show();
telemap.geofences.onEvent((e) => console.log(e.event, e.vehicleId, e.zoneName));

// ... later
telemap.destroy();

telemap.traffic.setLiveEnabled polls trafficSegments() on the given interval while enabled and color-codes each segment by speed (red <15, orange 15–30, green >30 km/h) — the same live overlay verified in the reference map viewer, just re-platformed behind the adapter. telemap.routes.draw() is id-keyed like pins (a dispatch-style caller can show more than one route at once) and accepts the direct result of client.route() or client.routeStops(). telemap.vehicles.update() is the shared rendering primitive for both paths in the vehicle-tracking model — bring-your-own-data calls it directly with zero backend involvement, and telemap.vehicles.track(vehicleId) (the Telemap-managed path) polls client.vehicle() and feeds each result into the same update(). Animation (position interpolation, heading) is engine-agnostic logic in the SDK itself, not the map engine. telemap.geofences.show() renders every zone from GET /geofences as one fixed overlay (real geodesic circles, not a zoom-dependent pixel radius) — global read-only data, so it's a single toggle like telemap.traffic, not id-keyed like pins/routes/vehicles. telemap.geofences.onEvent() is a delivery hook, not a rendering feature: it polls geofenceEvents() and calls your handler for genuinely new enter/exit transitions (the first poll seeds a baseline rather than replaying history). All five modules named in the original SDK v2 plan are now built.

Plain <script>, zero build step: <script src="telemap-sdk.iife.js"></script> is the only tag needed — no separate MapLibre script or stylesheet, both are inlined and injected automatically. Exposes a global Telemap object (const { TelemapClient, TelemapMap } = Telemap;).

Full working example: sdk/example/index.html — search flies the map to a result, the traffic toggle renders live segments, a pin toggle demonstrates telemap.pins, two vehicle toggles demonstrate both tracking paths side by side, and a geofence toggle renders the real zones already configured in the stack with a live enter/exit event log.

Known limitations

Real gaps, documented rather than hidden — what this platform can't do yet.

Build status by leg

See MAP_ENGINE_ROADMAP.md and each leg's section in README.md for the full detail behind each line.