API-Dokumentation

vitaRoute API Integrationsleitfaden

Schnellstart

Die vitaRoute API ist REST-basiert und arbeitet mit JSON. Alle Anfragen müssen über HTTPS gesendet werden.

Base URL: https://api.vitaroute.ai

Kostenloses Konto erstellen
API-Schlüssel im Dashboard generieren
Ihre erste Optimierungsanfrage senden

Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung über den X-Api-Key-Header.

X-Api-Key: vtr_live_xxxxxxxxxxxxxxxxxxxx

⚠️ Sicherheitshinweis

Fügen Sie Ihre API-Schlüssel nicht in den Quellcode ein. Verwenden Sie Umgebungsvariablen.

Endpunkte

POST/api/optimization/optimize

Erweiterte Routenoptimierung. Die effizientesten Routen werden durch Bewertung von 20+ Parametern mit dem proprietären RL-Algorithmus von vitaRoute berechnet.

POST/api/route/calculate

Grundlegende Routenberechnung. Einfacher cluster-basierter Routenplan.

POST/api/route/cluster-stops

Gruppiert vorhandene Haltestellen nach Fahrzeugkapazität.

Anfrage-Schema

Feld	Typ	Beschreibung
`facilityLat`	float	Breitengrad der Anlage/des Depots
`facilityLng`	float	Längengrad der Anlage/des Depots
`totalCapacity`	int	Maximale Kapazität pro Fahrzeug (Standard: 14)
`vehicleCount`	int	Immer 0 — Fahrzeuganzahl wird automatisch bestimmt
`maxWalking`	int?	Maximale Gehentfernung (Meter, Standard: 500)
`maxDuration`	int?	Maximale Routendauer (Minuten, Standard: 90)
`maxClusterDiameterKm`	float	Maximaler geografischer Durchmesser der Haltestellen im selben Cluster (km, Standard: 25)
`minSavingsKm`	float	Mindest-Distanzeinsparung zum Zusammenführen einer Haltestelle (km, Standard: 0,3)
`maxDetourFactor`	float	Maximaler Umwegfaktor beim Hinzufügen einer Haltestelle zu einer bestehenden Route (Standard: 0,6)
`minDistrictPassengers`	int	Mindestanzahl an Fahrgästen für eine bezirksspezifische Route (Standard: 8)
`tripDirection`	string	Fahrtrichtung: 'to_facility' (Hinfahrt zum Depot) oder 'from_facility' (Rückfahrt vom Depot)
`arrivalTimeAtDepot`	string?	Ankunftszeit der Fahrzeuge am Depot (ISO 8601 UTC). Bei Angabe wird die Geschwindigkeit anhand des Verkehrsprofils berechnet; sonst werden feste 28 km/h verwendet.
`useDistanceMatrix`	boolean	Google Maps Distance Matrix API für genaue Straßenentfernungen verwenden (Standard: false)
`nodes`	NodeInput[]	Liste des zu optimierenden Personals/der Standorte

NodeInput

Feld	Typ	Beschreibung
`id`	string	Eindeutige Personal-/Standortkennung
`name`	string	Personalname
`latitude`	float	Breitengradkoordinate
`longitude`	float	Längengradkoordinate
`district`	string?	Bezirksname (optional, für Bezirksregeln)

Antwort-Schema

{
  "routes": [
    {
      "routeId": "uuid",
      "routeName": "GEBZE 1",
      "totalDuration": 45,
      "totalDistance": 28500,
      "nodeCount": 14,
      "totalLoad": 14,
      "stops": [
        {
          "stopIndex": 0,
          "latitude": 40.8962,
          "longitude": 29.1882,
          "nodes": [
            { "id": "1", "name": "Ali Yilmaz" }
          ]
        }
      ],
      "routeCenter": {
        "latitude": 40.9,
        "longitude": 29.2
      }
    }
  ]
}

Ratenlimits

Plan	Monatl. Anfragen	Max. Knoten	Gleichzeitig
Free	50	1	1
Starter	1,000	100	5
Growth	5,000	500	20
Enterprise	Unbegrenzt	Unbegrenzt	Individuell

Wenn das Ratenlimit überschritten wird, wird eine 429 Too Many Requests Antwort zurückgegeben. Der Retry-After-Header gibt die Wartezeit an.

Fehlercodes

400

Bad Request

Ungültiges JSON oder fehlendes Pflichtfeld

401

Unauthorized

API-Schlüssel fehlt oder ist ungültig

403

Forbidden

Ihr Planlimit wurde überschritten

429

Too Many Requests

Ratenlimit überschritten

500

Internal Server Error

Serverfehler, bitte wenden Sie sich an den Support

Code-Beispiele

curl

curl -X POST https://api.vitaroute.ai/api/optimization/optimize \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: vtr_live_your_key_here" \
  -d '{
    "facilityLat": 40.9139,
    "facilityLng": 29.1167,
    "totalCapacity": 16,
    "vehicleCount": 0,
    "maxWalking": 500,
    "maxDuration": 90,
    "maxClusterDiameterKm": 25,
    "minSavingsKm": 0.3,
    "maxDetourFactor": 0.6,
    "minDistrictPassengers": 8,
    "tripDirection": "to_facility",
    "arrivalTimeAtDepot": "2025-01-15T05:00:00Z",
    "useDistanceMatrix": false,
    "nodes": [
      { "id": "1", "name": "Ali Yilmaz", "latitude": 40.8962, "longitude": 29.1882, "district": "Kadikoy" },
      { "id": "2", "name": "Ayse Demir", "latitude": 40.9278, "longitude": 29.3125, "district": "Gebze" }
    ]
  }'

python

import requests

response = requests.post(
    "https://api.vitaroute.ai/api/optimization/optimize",
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": "vtr_live_your_key_here"
    },
    json={
        "facilityLat": 40.9139,
        "facilityLng": 29.1167,
        "totalCapacity": 16,
        "vehicleCount": 0,
        "maxWalking": 500,
        "maxDuration": 90,
        "maxClusterDiameterKm": 25,
        "minSavingsKm": 0.3,
        "maxDetourFactor": 0.6,
        "minDistrictPassengers": 8,
        "tripDirection": "to_facility",
        "arrivalTimeAtDepot": "2025-01-15T05:00:00Z",
        "useDistanceMatrix": False,
        "nodes": [
            {"id": "1", "name": "Ali Yilmaz", "latitude": 40.8962, "longitude": 29.1882}
        ]
    }
)

data = response.json()
for route in data["routes"]:
    print(f"{route['routeName']}: {route['nodeCount']} stops, {route['totalDuration']} min")

javascript

const response = await fetch(
  "https://api.vitaroute.ai/api/optimization/optimize",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": "vtr_live_your_key_here",
    },
    body: JSON.stringify({
      facilityLat: 40.9139,
      facilityLng: 29.1167,
      totalCapacity: 16,
      vehicleCount: 0,
      maxWalking: 500,
      maxDuration: 90,
      maxClusterDiameterKm: 25,
      minSavingsKm: 0.3,
      maxDetourFactor: 0.6,
      minDistrictPassengers: 8,
      tripDirection: "to_facility",
      arrivalTimeAtDepot: "2025-01-15T05:00:00Z",
      useDistanceMatrix: false,
      nodes: [
        { id: "1", name: "Ali Yilmaz", latitude: 40.8962, longitude: 29.1882 },
      ],
    }),
  }
);

const { routes } = await response.json();
routes.forEach(route => {
  console.log(`${route.routeName}: ${route.nodeCount} stops`);
});

C#

using System.Net.Http.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "vtr_live_your_key_here");

var payload = new {
    facilityLat = 40.9139,
    facilityLng = 29.1167,
    totalCapacity = 16,
    vehicleCount = 0,
    maxWalking = 500,
    maxDuration = 90,
    maxClusterDiameterKm = 25,
    minSavingsKm = 0.3,
    maxDetourFactor = 0.6,
    minDistrictPassengers = 8,
    tripDirection = "to_facility",
    arrivalTimeAtDepot = "2025-01-15T05:00:00Z",
    useDistanceMatrix = false,
    nodes = new[] {
        new { id = "1", name = "Ali Yilmaz", latitude = 40.8962, longitude = 29.1882 }
    }
};

var response = await client.PostAsJsonAsync(
    "https://api.vitaroute.ai/api/optimization/optimize",
    payload
);

var result = await response.Content.ReadFromJsonAsync<RouteResponse>();