Documentation API OptiRoad

Introduction

L'API OptiRoad vous permet d'optimiser des tournées, de géocoder des adresses et de gérer vos contacts par programme. L'accès nécessite un plan Business et une clé API.

URL de base :

https://optiroad.io/api/v1

Toutes les requêtes doivent inclure l'en-tête Authorization . Les réponses sont en JSON. Les dates sont au format ISO 8601. Les distances sont en kilomètres, les durées en minutes.

Authentification

Authentifiez-vous avec votre clé API dans l'en-tête Authorization :

curl https://optiroad.io/api/v1/usage \
  -H "Authorization: Bearer or_live_YOUR_KEY"

Les clés API sont créées dans Paramètres → Clés API. Chaque clé est affichée une seule fois à la création. Maximum 5 clés par compte.

Exemple JavaScript

const BASE = "https://optiroad.io/api/v1";
const KEY  = process.env.OPTIROAD_API_KEY;

const res = await fetch(`${BASE}/usage`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
const data = await res.json();

Exemple Python

import os, requests

BASE = "https://optiroad.io/api/v1"
KEY  = os.environ["OPTIROAD_API_KEY"]

resp = requests.get(
    f"{BASE}/usage",
    headers={"Authorization": f"Bearer {KEY}"}
)
data = resp.json()

Optimiser un itinéraire

POST/api/v1/optimizeCalcule l'ordre de visite optimal pour un ensemble d'adresses.

Corps de la requête

{
  "addresses": [
    { "label": "Dépôt",    "lat": 48.8566, "lng": 2.3522 },
    { "label": "Client A", "lat": 48.8737, "lng": 2.2950 },
    { "label": "Client B", "lat": 48.8416, "lng": 2.3224 }
  ],
  "options": {
    "mode":         "driving",
    "startAddress": 0,
    "roundTrip":    true
  }
}

Paramètres

ChampTypeDescription
addressesarrayObligatoire. Liste des étapes (min 2, max 150). Chaque élément : { label, lat, lng }.
options.modestringProfil de routage : driving (défaut), walking, cycling.
options.startAddressnumberIndex de l'adresse de départ/dépôt dans le tableau (défaut : 0).
options.roundTripbooleanRetour au départ après la dernière étape (défaut : true).

Réponse

{
  "optimizedOrder": [0, 2, 1],
  "totalDistanceKm": 12.4,
  "totalDurationMin": 22,
  "legs": [
    { "from": 0, "to": 2, "distanceKm": 5.1, "durationMin": 9 },
    { "from": 2, "to": 1, "distanceKm": 4.2, "durationMin": 8 },
    { "from": 1, "to": 0, "distanceKm": 3.1, "durationMin": 5 }
  ],
  "googleMapsUrl": "https://www.google.com/maps/dir/...",
  "usageRemaining": 487
}

Géocoder une adresse

POST/api/v1/geocodeConvertit une adresse en texte libre en coordonnées lat/lng.
// Request
{ "address": "10 Downing Street, London" }

// Response
{
  "lat": 51.5034,
  "lng": -0.1276,
  "label": "10 Downing Street, Westminster, London, UK"
}

Contacts

Gérez votre carnet d'adresses. Toutes les opérations sont limitées à votre compte.

GET/api/v1/contactsLister les contacts (paginé).
GET /api/v1/contacts?page=1&limit=20&search=Paris
{
  "contacts": [
    {
      "id": "clx...",
      "name": "Entrepôt Paris",
      "address": "12 rue de Rivoli, 75001 Paris",
      "lat": 48.856,
      "lng": 2.352,
      "phone": "+33 1 23 45 67 89",
      "createdAt": "2026-03-01T10:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}
POST/api/v1/contactsCréer un contact.
// Request
{
  "name": "Entrepôt Paris",
  "address": "12 rue de Rivoli, 75001 Paris",
  "lat": 48.856,
  "lng": 2.352,
  "phone": "+33 1 23 45 67 89"
}

// Response — 201 Created
{ "id": "clx...", "name": "...", ... }
PUT/api/v1/contacts/:idMettre à jour un contact.
DELETE/api/v1/contacts/:idSupprimer un contact.
// Response — 204 No Content

Véhicules

GET/api/v1/vehiclesLister les véhicules.
GET /api/v1/vehicles?status=active&type=van
{
  "vehicles": [
    {
      "id": "clx...",
      "name": "Camion 1",
      "type": "truck",
      "status": "active",
      "depotAddress": "ZI Nord, 59000 Lille",
      "depotLat": 50.651,
      "depotLng": 3.074
    }
  ]
}

Historique des optimisations

GET/api/v1/historyLister les optimisations passées (paginé).
GET /api/v1/history?page=1&limit=20&from=2026-01-01&to=2026-04-01
{
  "items": [
    {
      "id": "clx...",
      "addressCount": 8,
      "totalDistanceKm": 34.2,
      "totalDurationMin": 61,
      "createdAt": "2026-03-15T08:30:00.000Z"
    }
  ],
  "total": 42
}

Utilisation de l'API

GET/api/v1/usageCompteurs de requêtes pour la clé courante.
{
  "keyPrefix": "or_live_ab12",
  "today":     { "optimize": 3,   "geocode": 12  },
  "thisMonth": { "optimize": 47,  "geocode": 203 },
  "allTime":   { "optimize": 312, "geocode": 1024 }
}

Limites de débit

Les limites s'appliquent par clé API. Les en-têtes de réponse indiquent toujours l'état de la fenêtre courante.

Type d'endpointPar minutePar heurePar jour
Léger (geocode, contacts, vehicles)1001 000—
Lourd (optimize)10100500

Quand une limite est atteinte, l'API retourne 429 Too Many Requests avec un en-tête Retry-After (secondes).

En-têtes de limite de débit

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1744012800   # Unix timestamp (UTC)
Retry-After: 38                 # Présent uniquement en cas de 429

Codes d'erreur

HTTPerrorSignification
401UNAUTHORIZEDEn-tête Authorization manquant ou malformé.
401INVALID_API_KEYClé introuvable ou révoquée.
402QUOTA_EXCEEDEDQuota mensuel d'optimisations atteint. Passez à un plan supérieur.
403PLAN_REQUIREDCet endpoint nécessite un plan Business.
422VALIDATION_ERRORCorps de la requête invalide (voir message pour les détails).
422MAX_KEYS_REACHEDVous avez déjà 5 clés API. Révoquez-en une d'abord.
429RATE_LIMIT_EXCEEDEDTrop de requêtes. Vérifiez l'en-tête Retry-After.
500INTERNAL_ERRORErreur serveur inattendue. Réessayez.

Format de réponse d'erreur

{
  "error": "QUOTA_EXCEEDED",
  "message": "Monthly quota reached (5/5). Upgrade to Pro for unlimited optimizations.",
  "statusCode": 402
}

Des questions ? Contactez support@optiroad.io

OptiRoad API v1 · 2026