API Dokümantasyonu

vitaRoute API entegrasyon rehberi

Hızlı Başlangıç

vitaRoute API'si REST tabanlıdır ve JSON ile çalışır. Tüm istekler HTTPS üzerinden gönderilmelidir.

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

Ücretsiz hesap oluşturun
Dashboard'dan API key oluşturun
İlk optimizasyon isteğinizi gönderin

Kimlik Doğrulama

Tüm API istekleri X-Api-Key header'ı ile kimlik doğrulaması gerektirir.

X-Api-Key: vtr_live_xxxxxxxxxxxxxxxxxxxx

⚠️ Güvenlik Notu

API key'lerinizi kaynak kodunuza dahil etmeyin. Ortam değişkenleri kullanın.

Endpoint'ler

POST/api/optimization/optimize

Gelişmiş rota optimizasyonu. RL destekli tescilli vitaRoute algoritması ile 20+ parametre değerlendirilerek en verimli rotalar hesaplanır.

POST/api/route/calculate

Temel rota hesaplama. Kümeleme tabanlı basit rota planı.

POST/api/route/cluster-stops

Mevcut duraksları araç kapasitesine göre kümelere ayırır.

İstek Şeması

Alan	Tip	Açıklama
`facilityLat`	float	Tesis/depo enlem koordinatı
`facilityLng`	float	Tesis/depo boylam koordinatı
`totalCapacity`	int	Araç başına maksimum kapasite (varsayılan: 14)
`vehicleCount`	int	Her zaman 0 — araç sayısı otomatik belirlenir
`maxWalking`	int?	Maksimum yürüme mesafesi (metre, varsayılan: 500)
`maxDuration`	int?	Maksimum rota süresi (dakika, varsayılan: 90)
`maxClusterDiameterKm`	float	Aynı kümedeki durakların maksimum coğrafi çapı (km, varsayılan: 25)
`minSavingsKm`	float	Bir durak birleştirme için minimum mesafe kazancı (km, varsayılan: 0.3)
`maxDetourFactor`	float	Mevcut rotaya eklenen durağın maksimum sapma oranı (varsayılan: 0.6)
`minDistrictPassengers`	int	İlçeye özel rota oluşturmak için minimum yolcu sayısı (varsayılan: 8)
`tripDirection`	string	Yolculuk yönü: 'to_facility' (tesise gidiş) veya 'from_facility' (tesisten dönüş)
`arrivalTimeAtDepot`	string?	Araçların tesise varış saati (ISO 8601 UTC). Verilirse trafik profiline göre hız hesaplanır; verilmezse sabit 28 km/sa kullanılır.
`useDistanceMatrix`	boolean	Google Maps Distance Matrix API kullanılsın mı? (varsayılan: false)
`nodes`	NodeInput[]	Optimize edilecek personel/konum listesi

NodeInput

Alan	Tip	Açıklama
`id`	string	Benzersiz personel/lokasyon kimliği
`name`	string	Personel adı
`latitude`	float	Enlem koordinatı
`longitude`	float	Boylam koordinatı
`district`	string?	İlçe adı (isteğe bağlı, district kuralları için)

Yanıt Şeması

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

İstek Limitleri

Plan	Aylık İstek	Maks. Node	Eş Zamanlı
Free	50	1	1
Starter	1,000	100	5
Growth	5,000	500	20
Enterprise	Sınırsız	Sınırsız	Özel

Rate limit aşıldığında 429 Too Many Requests yanıtı döner. Retry-After header'ı bekleme süresini belirtir.

Hata Kodları

400

Bad Request

Geçersiz JSON veya eksik zorunlu alan

401

Unauthorized

API key eksik veya geçersiz

403

Forbidden

Plan limitiniz aşıldı

429

Too Many Requests

Rate limit aşıldı

500

Internal Server Error

Sunucu hatası, destek ekibine bildirin

Kod Örnekleri

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