Intégration et migration

Exemples de démarrage exécutables

Node.js 24 et bibliothèque standard Python 3. Définissez OSRM_API_KEY dans l’environnement du serveur, jamais dans le code envoyé au navigateur. Les exemples font des appels réels et consomment les crédits habituels.

Exemple Node.js Exemple Python Vérificateur HMAC Adaptateur de migration

SDK · API v1.1

Version du SDK JavaScript dans le dépôt: 1.1.0. Les SDK JavaScript et Python prennent en charge les tâches asynchrones et les points d’accès sandbox et métadonnées. Installez JavaScript depuis npm et Python depuis PyPI.

JavaScript / TypeScript · npm install osrmroute Python · pip install osrmroute

Liste de vérification pour la migration

Validez l’analyse des réponses dans le sandbox à données de test avant un appel réel payant.
OSRM utilise longitude,latitude. Les tableaux point et matrix de /api/1 utilisent latitude,longitude. L’adaptateur illustre explicitement cette conversion.
Comparez le point d’accès, le profil, les champs de réponse et les limites du forfait. La compatibilité ne garantit pas un remplacement intégral de chaque fournisseur.
Limitez la clé réelle par service, origin/IP, expiration et budget du projet, puis effectuez un test réel à faible volume.
Prévoyez une transition de 1 ou 24 heures, vérifiez la nouvelle clé, puis révoquez les anciens alias.

Tâches asynchrones

Opérations : geocode_batch, matrix, optimize. POST /api/jobs renvoie 202 et un identifiant de tâche. Le même Idempotency-Key et le même contenu renvoient la tâche existante ; un contenu différent renvoie 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.

Notifications signées

Créez un webhook HTTPS public, conservez le secret unique en sécurité et transmettez webhook_id à la création d’une tâche. Vérifiez X-OSRM-Timestamp et X-OSRM-Signature avec le corps brut.

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.

Erreurs, suivi et métadonnées sources

Les erreurs conservent error et ajoutent type, title, status, detail, code, request_id et retryable. Utilisez X-Request-Id pour l’assistance et le suivi des requêtes.

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.