Integração e migração

Exemplos iniciais executáveis

Node.js 24 e biblioteca padrão do Python 3. Configure OSRM_API_KEY no ambiente do servidor; nunca inclua segredos no código do navegador. Os exemplos fazem chamadas reais e consomem créditos normais.

Exemplo Node.js Exemplo Python Verificador HMAC Adaptador de migração

SDK · API v1.1

Versão do SDK JavaScript no repositório: 1.1.0. Os SDKs JavaScript e Python suportam tarefas assíncronas e endpoints de sandbox e metadados. Instale JavaScript pelo npm e Python pelo PyPI.

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

Lista de verificação de migração

Valide a leitura das respostas no sandbox com dados de teste antes de uma chamada real paga.
OSRM usa longitude,latitude. Os arrays point e matrix de /api/1 usam latitude,longitude. O adaptador de exemplo demonstra essa conversão.
Compare endpoint, perfil, campos de resposta e limites do plano. A compatibilidade não garante a substituição direta completa de todos os provedores.
Restrinja a chave real por serviço, origin/IP, validade e orçamento do projeto; depois execute um teste real de baixo volume.
Use um período de transição de 1 ou 24 horas, verifique a nova chave e revogue os aliases antigos.

Tarefas assíncronas

Operações: geocode_batch, matrix, optimize. POST /api/jobs retorna 202 e um ID de tarefa. O mesmo Idempotency-Key e conteúdo retornam a tarefa existente; conteúdo diferente retorna 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.

Notificações assinadas

Crie um webhook HTTPS público, guarde o segredo de uso único com segurança e envie webhook_id ao criar uma tarefa. Verifique X-OSRM-Timestamp e X-OSRM-Signature com o corpo original.

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.

Erros, rastreamento e metadados de origem

Os erros mantêm error e acrescentam type, title, status, detail, code, request_id e retryable. Use X-Request-Id para suporte e rastreamento de solicitações.

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.