Documentation API

Guide d'intégration de l'API vitaRoute

Démarrage rapide

L'API vitaRoute est basée sur REST et fonctionne avec JSON. Toutes les requêtes doivent être envoyées via HTTPS.

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

Créer un compte gratuit
Générer une clé API depuis le tableau de bord
Envoyer votre première requête d'optimisation

Authentification

Toutes les requêtes API nécessitent une authentification via l'en-tête X-Api-Key.

X-Api-Key: vtr_live_xxxxxxxxxxxxxxxxxxxx

⚠️ Note de sécurité

N'incluez pas vos clés API dans le code source. Utilisez des variables d'environnement.

Points de terminaison

POST/api/optimization/optimize

Optimisation avancée des itinéraires. Les itinéraires les plus efficaces sont calculés en évaluant 20+ paramètres avec l'algorithme RL propriétaire vitaRoute.

POST/api/route/calculate

Calcul de route de base. Plan de route simple basé sur les clusters.

POST/api/route/cluster-stops

Regroupe les arrêts existants selon la capacité du véhicule.

Schéma de requête

Champ	Type	Description
`facilityLat`	float	Coordonnée de latitude de l'installation/dépôt
`facilityLng`	float	Coordonnée de longitude de l'installation/dépôt
`totalCapacity`	int	Capacité maximale par véhicule (défaut : 14)
`vehicleCount`	int	Toujours 0 — le nombre de véhicules est déterminé automatiquement
`maxWalking`	int?	Distance de marche maximale (mètres, défaut : 500)
`maxDuration`	int?	Durée maximale de l'itinéraire (minutes, défaut : 90)
`maxClusterDiameterKm`	float	Diamètre géographique maximal des arrêts dans le même cluster (km, défaut : 25)
`minSavingsKm`	float	Économie de distance minimale requise pour fusionner un arrêt (km, défaut : 0,3)
`maxDetourFactor`	float	Ratio de détour maximal lors de l'ajout d'un arrêt à une route existante (défaut : 0,6)
`minDistrictPassengers`	int	Nombre minimum de passagers pour créer une route spécifique à un district (défaut : 8)
`tripDirection`	string	Direction du trajet : 'to_facility' (vers le dépôt) ou 'from_facility' (depuis le dépôt)
`arrivalTimeAtDepot`	string?	Heure d'arrivée des véhicules au dépôt (ISO 8601 UTC). Si fournie, la vitesse est calculée selon le profil de trafic ; sinon 28 km/h fixe est utilisé.
`useDistanceMatrix`	boolean	Utiliser l'API Google Maps Distance Matrix pour des distances routières précises (défaut : false)
`nodes`	NodeInput[]	Liste du personnel/des emplacements à optimiser

NodeInput

Champ	Type	Description
`id`	string	Identifiant unique du personnel/emplacement
`name`	string	Nom du personnel
`latitude`	float	Coordonnée de latitude
`longitude`	float	Coordonnée de longitude
`district`	string?	Nom du district (optionnel, pour les règles de district)

Schéma de réponse

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

Limites de taux

Plan	Requêtes/mois	Nœuds max	Simultané
Free	50	1	1
Starter	1,000	100	5
Growth	5,000	500	20
Enterprise	Illimité	Illimité	Personnalisé

Lorsque la limite de taux est dépassée, une réponse 429 Too Many Requests est renvoyée. L'en-tête Retry-After spécifie le temps d'attente.

Codes d'erreur

400

Bad Request

JSON invalide ou champ obligatoire manquant

401

Unauthorized

Clé API manquante ou invalide

403

Forbidden

La limite de votre plan a été dépassée

429

Too Many Requests

Limite de taux dépassée

500

Internal Server Error

Erreur serveur, veuillez contacter le support

Exemples de code

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