API Documentation

vitaRoute API integration guide

Quick Start

The vitaRoute API is REST-based and works with JSON. All requests must be sent over HTTPS.

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

Create a free account
Generate an API key from the Dashboard
Send your first optimization request

Authentication

All API requests require authentication via the X-Api-Key header.

X-Api-Key: vtr_live_xxxxxxxxxxxxxxxxxxxx

⚠️ Security Note

Do not include your API keys in source code. Use environment variables.

Endpoints

POST/api/optimization/optimize

Advanced route optimization. The most efficient routes are calculated by evaluating 20+ parameters with the RL-powered proprietary vitaRoute algorithm.

POST/api/route/calculate

Basic route calculation. Simple cluster-based route plan.

POST/api/route/cluster-stops

Clusters existing stops according to vehicle capacity.

Request Schema

Field	Type	Description
`facilityLat`	float	Facility/depot latitude coordinate
`facilityLng`	float	Facility/depot longitude coordinate
`totalCapacity`	int	Maximum capacity per vehicle (default: 14)
`vehicleCount`	int	Always 0 — vehicle count is auto-determined
`maxWalking`	int?	Maximum walking distance (meters, default: 500)
`maxDuration`	int?	Maximum route duration (minutes, default: 90)
`maxClusterDiameterKm`	float	Maximum geographic diameter of stops in the same cluster (km, default: 25)
`minSavingsKm`	float	Minimum distance saving required to merge a stop (km, default: 0.3)
`maxDetourFactor`	float	Maximum detour ratio when adding a stop to an existing route (default: 0.6)
`minDistrictPassengers`	int	Minimum passengers required to create a district-specific route (default: 8)
`tripDirection`	string	Trip direction: 'to_facility' (inbound to depot) or 'from_facility' (outbound from depot)
`arrivalTimeAtDepot`	string?	Vehicle arrival time at depot (ISO 8601 UTC). When provided, speed is calculated based on traffic profile; otherwise a fixed 28 km/h is used.
`useDistanceMatrix`	boolean	Whether to use Google Maps Distance Matrix API for accurate road distances (default: false)
`nodes`	NodeInput[]	List of personnel/locations to optimize

NodeInput

Field	Type	Description
`id`	string	Unique personnel/location identifier
`name`	string	Personnel name
`latitude`	float	Latitude coordinate
`longitude`	float	Longitude coordinate
`district`	string?	District name (optional, for district rules)

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

Rate Limits

Plan	Monthly Requests	Max Nodes	Concurrent
Free	50	1	1
Starter	1,000	100	5
Growth	5,000	500	20
Enterprise	Unlimited	Unlimited	Custom

When the rate limit is exceeded, a 429 Too Many Requests response is returned. The Retry-After header specifies the wait time.

Error Codes

400

Bad Request

Invalid JSON or missing required field

401

Unauthorized

API key missing or invalid

403

Forbidden

Your plan limit has been exceeded

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error, please contact support

Code Examples

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