Documentazione API OptiRoad

Introduzione

L'API OptiRoad consente di ottimizzare percorsi di consegna, geocodificare indirizzi e gestire contatti tramite programmazione. L'accesso richiede un piano Business e una chiave API.

URL di base:

https://optiroad.io/api/v1

Tutte le richieste devono includere l'intestazione Authorization . Le risposte sono JSON. Le date sono stringhe ISO 8601. Le distanze sono in chilometri, le durate in minuti.

Autenticazione

Autenticarsi usando la propria chiave API nell'intestazione Authorization :

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

Le chiavi API vengono create in Impostazioni → Chiavi API. Ogni chiave viene mostrata una sola volta alla creazione. Massimo 5 chiavi per account.

Esempio 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();

Esempio 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()

Ottimizzare un percorso

POST/api/v1/optimizeCalcola l'ordine di visita ottimale per un insieme di indirizzi.

Corpo della richiesta

{
  "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
  }
}

Parametri

Campo	Tipo	Descrizione
addresses	array	Obbligatorio. Lista delle tappe (min 2, max 150). Ogni elemento: { label, lat, lng }.
options.mode	string	Profilo di routing: driving (predefinito), walking, cycling.
options.startAddress	number	Indice dell'indirizzo di partenza/deposito nell'array (predefinito: 0).
options.roundTrip	boolean	Ritorno al punto di partenza dopo l'ultima tappa (predefinito: true).

Risposta

{
  "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
}

Geocodificare un indirizzo

POST/api/v1/geocodeConverte un indirizzo in testo libero in coordinate lat/lng.

// Request
{ "address": "10 Downing Street, London" }

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

Contatti

Gestite la vostra rubrica salvata. Tutte le operazioni sono limitate al vostro account.

GET/api/v1/contactsElencare i contatti (paginato).

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/contactsCreare un contatto.

// 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/:idAggiornare un contatto.

DELETE/api/v1/contacts/:idEliminare un contatto.

// Response — 204 No Content

Veicoli

GET/api/v1/vehiclesElencare i veicoli.

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
    }
  ]
}

Cronologia delle ottimizzazioni

GET/api/v1/historyElencare le ottimizzazioni passate (paginato).

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
}

Utilizzo dell'API

GET/api/v1/usageContatori di richieste per la chiave corrente.

{
  "keyPrefix": "or_live_ab12",
  "today":     { "optimize": 3,   "geocode": 12  },
  "thisMonth": { "optimize": 47,  "geocode": 203 },
  "allTime":   { "optimize": 312, "geocode": 1024 }
}

Limiti di frequenza

I limiti si applicano per chiave API. Le intestazioni di risposta indicano sempre lo stato della finestra corrente.

Tipo di endpoint	Al minuto	All'ora	Al giorno
Leggero (geocode, contacts, vehicles)	100	1 000	—
Pesante (optimize)	10	100	500

Quando viene raggiunto un limite, l'API restituisce 429 Too Many Requests con un'intestazione Retry-After (secondi).

Intestazioni limite di frequenza

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1744012800   # Unix timestamp (UTC)
Retry-After: 38                 # Presente solo in caso di 429

Codici di errore

HTTP	error	Significato
401	UNAUTHORIZED	Intestazione Authorization mancante o malformata.
401	INVALID_API_KEY	Chiave non trovata o revocata.
402	QUOTA_EXCEEDED	Quota mensile di ottimizzazioni raggiunta. Aggiornate il piano.
403	PLAN_REQUIRED	Questo endpoint richiede un piano Business.
422	VALIDATION_ERROR	Il corpo della richiesta non ha superato la validazione (dettagli in message).
422	MAX_KEYS_REACHED	Avete già 5 chiavi API. Revocarne una prima.
429	RATE_LIMIT_EXCEEDED	Troppe richieste. Controllare Retry-After.
500	INTERNAL_ERROR	Errore del server imprevisto. Si prega di riprovare.

Formato di risposta di errore

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

Domande? Contattateci a support@optiroad.io

OptiRoad API v1 · 2026