hg-map-sdk

Client for Mummy's Dabba map-service (mesh-service/map-osrm): road routing and ETAs, trip optimization, geocoding (address ⇄ lat/lng, search-as-you-type) and India PIN codes.

Answers are in our own format whatever map provider runs behind the service (OSRM / Photon / Nominatim today; Google, Ola Maps or Mappls later). Code that uses this SDK never changes when the provider does:

• points are { lat, lng }
• distances are metres
• durations are seconds

Node 18+, no dependencies, TypeScript types included.

Setup

1. Give your service its own key on map-service:

   cd mesh-service/map-osrm/map-service
   npm run clients -- create user-backend   # prints the key once

2. Add it to your service's env:

   MAP_SERVICE_URL=http://map-service:4120/api/v1/maps
   MAP_SERVICE_API_KEY=mk_…

3. Create one client per process and reuse it:

   const { createMapClient, MapServiceError } = require("hg-map-sdk");
   
   const map = createMapClient({
     baseUrl: process.env.MAP_SERVICE_URL,
     apiKey: process.env.MAP_SERVICE_API_KEY,
     // timeoutMs: 8000, retries: 1
   });

Methods

| Method | Returns | |---|---| | eta({ from, to, profile?, departAt? }) | { distance_m, duration_s, eta } | | route({ points, profile?, geometry?, alternatives? }) | Distance, time, legs, GeoJSON line | | matrix({ sources, destinations?, profile? }) | durations[][], distances[][] (null = unreachable) | | nearest({ point, profile? }) | The point snapped to the nearest road | | optimizeTrip({ start, end?, stops, profile?, departAt?, geometry? }) | Stops in visit order with ETAs | | reverse({ point, language? }) | { place, provider, cache }: the address at a GPS point | | search({ query, near?, limit?, language? }) | { results, provider, cache } | | autocomplete({ query, near?, limit?, language? }) | Suggestions while the user types | | pincode(pin, { geometry? }) | Official PIN details (+ boundary GeoJSON) | | locatePincode({ point }) | Which PIN a point is in | | pincodesWithin({ center, radiusM }) | Every PIN a radius reaches, with share_inside | | clientConfig() | What an app's map should draw (tiles provider, renderer, style URL) | | health() | { status: "OK" \| "DEGRADED", … }, without throwing on DEGRADED |

Profiles: bike (default, scooter or motorcycle) and bicycle.

place.components.pincode always comes from the official India Post boundaries, not the map provider. PIN data is under the Government Open Data Licence – India. Show the attribution string from the PIN-code answers wherever you display that data.

Examples

// Is this customer within 10 km (by road) of the kitchen?
const { distance_m } = await map.eta({ from: kitchen, to: customer });
const serviceable = distance_m <= 10000;

// GPS at app start → city + PIN
const { place } = await map.reverse({ point: { lat: 26.4842, lng: 80.311 } });
// place.components → { city: "Kanpur", pincode: "208002", … }

// Which PINs to offer home delivery in
const { pincodes } = await map.pincodesWithin({ center: kitchen, radiusM: 10000 });
const mostlyInside = pincodes.filter((p) => p.share_inside >= 0.5).map((p) => p.pincode);

Errors

Every failure is a MapServiceError with:

• code: map-service's own code, or NETWORK_ERROR / TIMEOUT
• status: the HTTP status, or null if map-service wasn't reached
• details
• retryAfterS
• retryable

try {
  await map.eta({ from, to });
} catch (err) {
  if (err instanceof MapServiceError && err.code === "POINT_OUTSIDE_COVERAGE") {
    // address outside the map region we serve
  }
  throw err;
}

| code | Meaning | |---|---| | INVALID_API_KEY (401) | Missing, unknown or revoked key | | RATE_LIMITED (429) | This service is over its per-minute limit | | POINT_OUTSIDE_COVERAGE / NO_ROUTE (422) | Not reachable by road in the loaded map | | PINCODE_NOT_FOUND (404) | No such PIN | | INVALID_* (400) | Bad input; details says which field | | PROVIDER_UNAVAILABLE / GEOCODING_UNAVAILABLE (503) | Engine down / no geocoder configured | | NETWORK_ERROR, TIMEOUT | map-service not reachable or too slow |

Retries: network errors, timeouts and 5xx are retried retries times (default 1), with backoff. This is safe because every map-service endpoint only reads. A 429 is retried only when Retry-After is at most maxRetryAfterS (2 s); otherwise it is thrown at once. 4xx errors are never retried.

Develop

The SDK lives in the map-service repo (sdk/), next to the API it calls, so an API change and its SDK change land in one PR. Only this folder is published; the files list in package.json limits the package to index.js, index.d.ts, src/ and this README.

cd sdk
npm test              # against a fake map-service; no engines needed
npm pack --dry-run    # shows exactly what would be published
npm publish           # from sdk/ only, after bumping `version` (npm account: satyamsonker1010)