Интеграция и миграция

Готовые стартовые примеры

Node.js 24 и стандартная библиотека Python 3. Храните OSRM_API_KEY в переменной окружения сервера, никогда не включайте секрет в код браузера. Примеры выполняют реальные запросы и расходуют обычные кредиты.

Стартовый пример Node.js Стартовый пример Python Проверка HMAC Адаптер миграции

SDK · API v1.1

Версия JavaScript SDK в репозитории: 1.1.0. SDK для JavaScript и Python поддерживают асинхронные задачи, sandbox и метаданные. Установите JavaScript из npm, а Python из PyPI.

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

Проверки при миграции

Проверьте обработку ответов в sandbox с тестовыми данными перед платным реальным запросом.
OSRM использует longitude,latitude. Массивы point и matrix в /api/1 используют latitude,longitude. Пример адаптера явно показывает преобразование.
Сравните endpoint, профиль, поля ответа и лимиты тарифа. Совместимость не означает полной прямой замены любого провайдера.
Ограничьте рабочий ключ по сервису, origin/IP, сроку действия и бюджету проекта, затем проведите небольшой реальный тест.
Используйте переходный период 1 или 24 часа, проверьте новый ключ и отзовите старые псевдонимы.

Асинхронные задачи

Операции: geocode_batch, matrix, optimize. POST /api/jobs возвращает 202 и ID задачи. Одинаковые Idempotency-Key и содержимое возвращают существующую задачу; другое содержимое возвращает 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.

Подписанные уведомления

Создайте публичный HTTPS webhook, безопасно сохраните однократно выдаваемый секрет и передайте webhook_id при создании задачи. Проверяйте X-OSRM-Timestamp и X-OSRM-Signature по исходному телу запроса.

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.

Ошибки, отслеживание и метаданные источников

Ответы об ошибках сохраняют error и добавляют type, title, status, detail, code, request_id и retryable. Используйте X-Request-Id для поддержки и отслеживания запросов.

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.