Integration and migration

Runnable starter examples

Node.js 24 and Python 3 standard library. Set OSRM_API_KEY as a server environment variable. Never bundle a live secret in browser code. Starters make a live call and consume normal credits.

SDK · API v1.1

JavaScript SDK repository version: 1.1.0. The JavaScript and Python SDKs support async jobs, sandbox and metadata endpoints. Install JavaScript from npm and Python from PyPI.

Migration checklist

1. Validate response parsing in the fixture sandbox before a paid live call.
2. OSRM coordinates use longitude,latitude. The /api/1 point and matrix arrays use latitude,longitude. The example adapter makes this conversion explicit.
3. Compare endpoint, profile, response fields and plan limits. Compatibility does not imply full drop-in equivalence with every provider.
4. Restrict the live key by service, origin/IP, expiry and project budget, then run a low-volume real test.
5. Use a 1-hour or 24-hour rotation grace period, verify the new key, then revoke old aliases.

Async jobs

Operations: geocode_batch, matrix, optimize. POST /api/jobs returns 202 and a job ID. Reusing the same Idempotency-Key and payload returns the existing job; a different payload returns 409.

curl -X POST https://osrmroute.com/api/jobs \
  -H "Authorization: Bearer $OSRM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-durable-operation-id-001" \
  -d '{"operation":"geocode_batch","input":{"queries":["Baku, Azerbaijan"]}}'

GET    /api/jobs/{id}
GET    /api/jobs/{id}?result=1
DELETE /api/jobs/{id}     # queued jobs only
States: queued → running → completed | failed | unknown
queued → cancelled | expired
Inputs/results: encrypted, 24-hour expiry
Unknown outcomes: investigate X-Request-Id; never auto-retry
Normal API entitlement, origin/IP policy and credits apply at dispatch.

Signed callbacks

Create a public HTTPS webhook in the console, keep the one-time secret securely and pass webhook_id when creating a job. Verify X-OSRM-Timestamp and X-OSRM-Signature against the raw body.

signature = "sha256=" + HMAC_SHA256(secret, timestamp + "." + rawBody)
Reject timestamps outside ±300 seconds.
Compare signatures in constant time. Persist event IDs to deduplicate.
Callbacks contain event ID, job ID and state; fetch results with the API key.
Timeout: 10s. At most 5 attempts with backoff. No redirects.
Treat repeated delivery as normal; do not repeat a charge or job.

Problems, tracing and source metadata

Error responses retain the legacy error field and add type, title, status, detail, code, request_id and retryable. Use X-Request-Id for support and request traces.

GET /api/source-metadata   # live key, info scope
Coverage/freshness/source evidence only; no inferred legal speed limit.
Trace retention: 7 days; service names, durations and status only.
No request coordinates, payload, raw keys or SQL text in traces.