OptiRoad API-Dokumentation

Einführung

Die OptiRoad API ermöglicht es Ihnen, Lieferrouten zu optimieren, Adressen zu geokodieren und Kontakte programmatisch zu verwalten. Zugang erfordert einen Business-Plan und einen API-Schlüssel.

Basis-URL:

https://optiroad.io/api/v1

Alle Anfragen müssen den Header Authorization enthalten. Antworten sind JSON. Datumsangaben sind ISO 8601-Strings. Entfernungen in Kilometern, Dauern in Minuten.

Authentifizierung

Authentifizieren Sie sich mit Ihrem API-Schlüssel im Header Authorization :

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

API-Schlüssel werden in Einstellungen → API-Schlüssel. erstellt. Jeder Schlüssel wird nur einmal bei der Erstellung angezeigt. Maximal 5 Schlüssel pro Konto.

JavaScript-Beispiel

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

Python-Beispiel

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

Route optimieren

POST/api/v1/optimizeBerechnet die optimale Besuchsreihenfolge für eine Menge von Adressen.

Anfrage-Body

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

Parameter

Feld	Typ	Beschreibung
addresses	array	Pflichtfeld. Liste der Haltestellen (min 2, max 150). Jedes Element: { label, lat, lng }.
options.mode	string	Routing-Profil: driving (Standard), walking, cycling.
options.startAddress	number	Index der Start-/Depot-Adresse im Array (Standard: 0).
options.roundTrip	boolean	Rückkehr zum Start nach der letzten Haltestelle (Standard: true).

Antwort

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

Adresse geokodieren

POST/api/v1/geocodeWandelt eine Freitextadresse in lat/lng-Koordinaten um.

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

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

Kontakte

Verwalten Sie Ihr gespeichertes Adressbuch. Alle Operationen sind auf Ihr Konto beschränkt.

GET/api/v1/contactsKontakte auflisten (paginiert).

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/contactsKontakt erstellen.

// 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/:idKontakt aktualisieren.

DELETE/api/v1/contacts/:idKontakt löschen.

// Response — 204 No Content

Fahrzeuge

GET/api/v1/vehiclesFahrzeuge auflisten.

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

Optimierungsverlauf

GET/api/v1/historyVergangene Optimierungen auflisten (paginiert).

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
}

API-Nutzung

GET/api/v1/usageAnfragezähler für den aktuellen Schlüssel.

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

Ratenlimits

Limits gelten pro API-Schlüssel. Antwortheader enthalten immer den aktuellen Fensterstatus.

Endpoint-Typ	Pro Minute	Pro Stunde	Pro Tag
Leicht (geocode, contacts, vehicles)	100	1 000	—
Schwer (optimize)	10	100	500

Wenn ein Limit erreicht wird, gibt die API 429 Too Many Requests mit einem Retry-After Header (Sekunden) zurück.

Ratenlimit-Header

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1744012800   # Unix timestamp (UTC)
Retry-After: 38                 # Nur bei 429 vorhanden

Fehlercodes

HTTP	error	Bedeutung
401	UNAUTHORIZED	Fehlender oder fehlerhafter Authorization-Header.
401	INVALID_API_KEY	Schlüssel nicht gefunden oder widerrufen.
402	QUOTA_EXCEEDED	Monatliches Optimierungskontingent erreicht. Upgraden Sie Ihren Plan.
403	PLAN_REQUIRED	Dieser Endpoint erfordert einen Business-Plan.
422	VALIDATION_ERROR	Anfrage-Body hat Validierung nicht bestanden (Details in message).
422	MAX_KEYS_REACHED	Sie haben bereits 5 API-Schlüssel. Widerrufen Sie zunächst einen.
429	RATE_LIMIT_EXCEEDED	Zu viele Anfragen. Prüfen Sie Retry-After.
500	INTERNAL_ERROR	Unerwarteter Serverfehler. Bitte erneut versuchen.

Fehlerantwort-Format

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

Fragen? Kontaktieren Sie support@optiroad.io

OptiRoad API v1 · 2026