Documentación API OptiRoad

Introducción

La API de OptiRoad le permite optimizar rutas de entrega, geocodificar direcciones y gestionar contactos mediante programación. El acceso requiere un plan Business y una clave API.

URL base:

https://optiroad.io/api/v1

Todas las solicitudes deben incluir el encabezado Authorization . Las respuestas son JSON. Las fechas son cadenas ISO 8601. Las distancias están en kilómetros, las duraciones en minutos.

Autenticación

Autentíquese usando su clave API en el encabezado Authorization :

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

Las claves API se crean en Ajustes → Claves API. Cada clave se muestra solo una vez en la creación. Máximo 5 claves por cuenta.

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

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

Optimizar una ruta

POST/api/v1/optimizeCalcula el orden de visita óptimo para un conjunto de direcciones.

Cuerpo de la solicitud

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

Parámetros

CampoTipoDescripción
addressesarrayObligatorio. Lista de paradas (mín 2, máx 150). Cada elemento: { label, lat, lng }.
options.modestringPerfil de enrutamiento: driving (por defecto), walking, cycling.
options.startAddressnumberÍndice de la dirección de inicio/depósito en el array (por defecto: 0).
options.roundTripbooleanRetorno al inicio después de la última parada (por defecto: true).

Respuesta

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

Geocodificar una dirección

POST/api/v1/geocodeConvierte una dirección en texto libre a coordenadas lat/lng.
// Request
{ "address": "10 Downing Street, London" }

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

Contactos

Gestione su libreta de direcciones guardada. Todas las operaciones están limitadas a su cuenta.

GET/api/v1/contactsListar contactos (paginado).
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/contactsCrear un contacto.
// 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/:idActualizar un contacto.
DELETE/api/v1/contacts/:idEliminar un contacto.
// Response — 204 No Content

Vehículos

GET/api/v1/vehiclesListar vehículos.
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
    }
  ]
}

Historial de optimizaciones

GET/api/v1/historyListar optimizaciones pasadas (paginado).
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
}

Uso de la API

GET/api/v1/usageContadores de solicitudes para la clave actual.
{
  "keyPrefix": "or_live_ab12",
  "today":     { "optimize": 3,   "geocode": 12  },
  "thisMonth": { "optimize": 47,  "geocode": 203 },
  "allTime":   { "optimize": 312, "geocode": 1024 }
}

Límites de velocidad

Los límites se aplican por clave API. Los encabezados de respuesta siempre incluyen el estado de la ventana actual.

Tipo de endpointPor minutoPor horaPor día
Ligero (geocode, contacts, vehicles)1001 000—
Pesado (optimize)10100500

Cuando se alcanza un límite, la API devuelve 429 Too Many Requests con un encabezado Retry-After (segundos).

Encabezados de límite de velocidad

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1744012800   # Unix timestamp (UTC)
Retry-After: 38                 # Solo presente en 429

Códigos de error

HTTPerrorSignificado
401UNAUTHORIZEDEncabezado Authorization faltante o malformado.
401INVALID_API_KEYClave no encontrada o revocada.
402QUOTA_EXCEEDEDCuota mensual de optimizaciones alcanzada. Actualice su plan.
403PLAN_REQUIREDEste endpoint requiere un plan Business.
422VALIDATION_ERROREl cuerpo de la solicitud no pasó la validación (detalles en message).
422MAX_KEYS_REACHEDYa tiene 5 claves API. Revoque una primero.
429RATE_LIMIT_EXCEEDEDDemasiadas solicitudes. Compruebe Retry-After.
500INTERNAL_ERRORError de servidor inesperado. Por favor, reintente.

Formato de respuesta de error

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

¿Preguntas? Contacte support@optiroad.io

OptiRoad API v1 · 2026