HyperRoute API

HyperRoute API

Welcome to the HyperRoute API documentation. HyperRoute is an advanced routing and logistics optimization engine specifically designed for Turkey's unique transportation network. It provides precise distance calculations, optimal path finding, detailed cost analysis including fuel consumption, and supports multiple vehicle types with their specific characteristics. The engine offers both fastest and shortest route options while considering real-time traffic conditions.

HyperRoute API dokümantasyonuna hoş geldiniz. HyperRoute, Türkiye'nin kendine özgü ulaşım ağı için özel olarak tasarlanmış gelişmiş bir rota ve lojistik optimizasyon motorudur. Hassas mesafe hesaplamaları, optimal yol bulma, yakıt tüketimi dahil detaylı maliyet analizi sunar ve her biri kendi özelliklerine sahip çoklu araç tiplerini destekler. Motor, gerçek zamanlı trafik koşullarını dikkate alarak hem en hızlı hem de en kısa rota seçenekleri sunar.

Quick Start

Hızlı Başlangıç

Get up and running with HyperRoute API in minutes.

HyperRoute API ile dakikalar içinde çalışmaya başlayın.

Your First Request

İlk İsteğiniz

curl -X POST https://test.api.router.siriusaitech.com/route/generate \
  -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicleTypeId": 5,
    "from": {
      "lat": "41.0082",
      "lng": "28.9784"
    },
    "to": {
      "lat": "40.1885",
      "lng": "29.0610"
    },
    "waypoints": [],
    "avoidPoints": [],
    "routeType": "fast",
    "isToll": 1,
    "isShip": 0,
    "fuelRatio": 35
  }'

const response = await fetch('https://test.api.router.siriusaitech.com/route/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    vehicleTypeId: 5,
    from: { lat: "41.0082", lng: "28.9784" },
    to: { lat: "40.1885", lng: "29.0610" },
    waypoints: [],
    avoidPoints: [],
    routeType: "fast",
    isToll: 1,
    isShip: 0,
    fuelRatio: 35
  })
});

const route = await response.json();
console.log(\`Distance: \${route.data.distance} km\`);
console.log(\`Total Cost: \${route.data.totalCost} TL\`);

import requests

response = requests.post(
    'https://test.api.router.siriusaitech.com/route/generate',
    headers={
        'Authorization': 'Bearer YOUR_ACCESS_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'vehicleTypeId': 5,
        'from': {'lat': '41.0082', 'lng': '28.9784'},
        'to': {'lat': '40.1885', 'lng': '29.0610'},
        'waypoints': [],
        'avoidPoints': [],
        'routeType': 'fast',
        'isToll': 1,
        'isShip': 0,
        'fuelRatio': 35
    }
)

route = response.json()
print(f"Distance: {route['data']['distance']} km")
print(f"Total Cost: {route['data']['totalCost']} TL")

Authentication

Kimlik Doğrulama

HyperRoute API uses Bearer token authentication. Include your access key in the Authorization header of every request.

HyperRoute API, Bearer token kimlik doğrulaması kullanır. Her istekte Authorization başlığına erişim anahtarınızı ekleyin.

Authorization: Bearer YOUR_ACCESS_KEY

Getting Access Keys

Erişim Anahtarları Edinme

To obtain access keys for development or production use:

Geliştirme veya üretim kullanımı için erişim anahtarları edinmek için:

• Contact our technical team at tech@siriusaitech.com
• Provide your company name and use case
• Specify if you need test or production access

• Teknik ekibimize tech@siriusaitech.com adresinden ulaşın
• Şirket adınızı ve kullanım senaryonuzu belirtin
• Test mi yoksa üretim erişimi mi ihtiyacınız olduğunu belirtin

Rate Limits

Kullanım Sınırları

To ensure fair usage and system stability, the following rate limits apply:

Adil kullanım ve sistem kararlılığını sağlamak için aşağıdaki kullanım sınırları geçerlidir:

Rate limit information is included in response headers:

Kullanım sınırı bilgileri yanıt başlıklarında yer alır:

• X-RateLimit-Limit - Your rate limit
• X-RateLimit-Remaining - Remaining requests
• X-RateLimit-Reset - Reset timestamp

• X-RateLimit-Limit - Kullanım sınırınız
• X-RateLimit-Remaining - Kalan istek sayısı
• X-RateLimit-Reset - Sıfırlama zamanı

Health Check

Sağlık Kontrolü

No authentication required for this endpoint.

Bu uç nokta için kimlik doğrulama gerekmez.

Response Example

Yanıt Örneği

{
  "status": "healthy",
  "timestamp": "2024-12-25T10:00:00.000Z",
  "uptime": 3600,
  "version": "1.0.0",
  "services": {
    "database": "up",
    "cache": "up",
    "routeEngine": "up"
  }
}

Generate Route

Rota Oluştur

Request Body

istek Gövdesi

Vehicle Types

Araç Tipleri

• 1 - Automobile
• 2 - Minibus
• 3 - Bus
• 4 - Light Commercial
• 5 - Truck

• 1 - Otomobil
• 2 - Minibüs
• 3 - Otobüs
• 4 - Hafif Ticari
• 5 - Kamyon

Response Example

Yanıt Örneği

{
  "status": true,
  "data": {
    "distance": 354.82,
    "totalCost": 2150.65,
    "totalTime": 18540,
    "routeId": "route_abc123",
    "segments": [
      {
        "start": {"lat": 41.0082, "lng": 28.9784},
        "end": {"lat": 40.1885, "lng": 29.0610},
        "distance": 354820,
        "duration": 18540
      }
    ],
    "costs": {
      "fuel": 1850.65,
      "toll": 300.00,
      "total": 2150.65
    }
  }
}

Get Route Details

Rota Detaylarını Al

Query Parameters

Sorgu Parametreleri

Response Example

Yanıt Örneği

{
  "status": true,
  "data": {
    "location": {
      "from": {
        "lat": "41.0082",
        "lng": "28.9784",
        "name": "Istanbul"
      },
      "to": {
        "lat": "40.1885",
        "lng": "29.0610",
        "name": "Bursa"
      },
      "waypoints": [],
      "avoidPoints": []
    },
    "route": {
      "routeId": "route_abc123",
      "vehicleType": "Truck",
      "routeType": "fast",
      "distance": 354.82,
      "duration": 18540,
      "totalCost": 2150.65,
      "fuelCost": 1850.65,
      "tollCost": 300.00,
      "segments": [
        {
          "points": [[41.0082, 28.9784], [40.9876, 29.0123]],
          "distance": 15.5,
          "duration": 900
        }
      ],
      "tollPoints": [
        {
          "name": "Osmangazi Bridge",
          "lat": 40.7589,
          "lng": 29.7311,
          "cost": 300.00
        }
      ]
    }
  },
  "message": "işlem başarılı"
}

Vehicle Types

Araç Tipleri

This endpoint returns the list of vehicle types that can be used in route generation.

Bu uç nokta, rota oluşturmada kullanılabilecek araç tiplerinin listesini döndürür.

Response Example

Yanıt Örneği

{
  "status": true,
  "data": [
    {
      "id": 1,
      "name": "Automobile"
    },
    {
      "id": 2,
      "name": "Minibus"
    },
    {
      "id": 3,
      "name": "Bus"
    },
    {
      "id": 4,
      "name": "Light Commercial"
    },
    {
      "id": 5,
      "name": "Truck"
    }
  ]
}

Route History Management

Rota Geçmişi Yönetimi

Query Parameters

Sorgu Parametreleri

Response Example

Yanıt Örneği

{
  "status": true,
  "data": {
    "routeKey": "rou_123456",
    "activeRoute": {
      "id": 1234,
      "routeKey": "rou_123456",
      "fromLat": 41.0082,
      "fromLng": 28.9784,
      "toLat": 39.9334,
      "toLng": 32.8597,
      "vehicleTypeId": 5,
      "vehicleTypeName": "Tır",
      "isActive": true,
      "totalCost": 450.00,
      "kilometer": 453.2,
      "totalMinutes": 360,
      "waypoints": [...],
      "avoidPoints": [...],
      "costSummary": {
        "totalCost": 450.00,
        "hgsOgs": 85.50,
        "bridge": 20.00,
        "fuel": 344.50
      }
    },
    "history": [
      {
        "id": 1233,
        "routeKey": "rou_123456",
        "isActive": false,
        "totalCost": 440.00,
        "kilometer": 451.5,
        "totalMinutes": 355
      }
    ],
    "summary": {
      "totalVersions": 2,
      "hasActiveRoute": true,
      "historyCount": 1
    }
  }
}

Request Body

İstek Gövdesi

{
  "routeKey": "rou_123456",
  "routeId": 1233
}

Parameters

Parametreler

Response Example

Yanıt Örneği

{
  "status": true,
  "data": {
    "message": "Aktif rota başarıyla değiştirildi",
    "activeRoute": {
      "id": 1233,
      "routeKey": "rou_123456",
      "fromLat": 41.0082,
      "fromLng": 28.9784,
      "toLat": 39.9334,
      "toLng": 32.8597,
      "vehicleTypeId": 5,
      "vehicleTypeName": "Tır",
      "isDelete": 0,
      "totalCost": 440.00,
      "kilometer": 451.5,
      "totalMinutes": 355
    }
  }
}

Usage Statistics

Kullanım İstatistikleri

Query Parameters

Sorgu Parametreleri

Response Example

Yanıt Örneği

{
  "status": true,
  "data": {
    "accessKey": "us-JNMSZ8V...L1H8",
    "period": {
      "days": 7,
      "startDate": "2024-12-18T10:00:00.000Z",
      "endDate": "2024-12-25T10:00:00.000Z"
    },
    "summary": {
      "totalRoutes": 1500,
      "totalDistance": "25000.50",
      "totalCost": "15000.75",
      "avgDistance": "16.67",
      "avgCost": "10.00",
      "uniqueRoutes": 120
    },
    "dailyUsage": [
      {
        "period": "2024-12-25",
        "totalRoutes": 50,
        "totalDistance": "850.25",
        "totalCost": "500.50"
      }
    ],
    "vehicleTypes": [
      {
        "vehicleType": "Kamyon",
        "count": 800,
        "totalDistance": "15000.00",
        "totalCost": "9000.00"
      }
    ],
    "routeTypes": [
      {
        "routeType": "fast",
        "count": 900,
        "avgDistance": "17.50",
        "avgCost": "10.50"
      }
    ]
  }
}

Overall Statistics (Admin)

Genel İstatistikler (Yönetici)

Query Parameters

Sorgu Parametreleri

Response Example

{
  "status": true,
  "data": {
    "period": {
      "days": 7,
      "startDate": "2024-12-18T10:00:00.000Z",
      "endDate": "2024-12-25T10:00:00.000Z"
    },
    "keys": [
      {
        "keyName": "Production Key 1",
        "accessKey": "us-JNMSZ8V...L1H8",
        "totalRoutes": 5000,
        "totalDistance": "85000.00",
        "totalCost": "45000.00",
        "lastUsed": "2024-12-25T09:45:00.000Z"
      },
      {
        "keyName": "Development Key",
        "accessKey": "us-A8M4P1...7WYE",
        "totalRoutes": 1500,
        "totalDistance": "25000.00",
        "totalCost": "15000.00",
        "lastUsed": "2024-12-25T08:30:00.000Z"
      }
    ]
  }
}

Additional Endpoint

Ek Uç Nokta

Parameters and response format are the same as /usage/my-stats.

Parametreler ve yanıt formatı /usage/my-stats ile aynıdır.

Error Handling

Hata Yönetimi

All errors follow a consistent format:

Tüm hatalar tutarlı bir formatı takip eder:

{
  "status": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE",
    "statusCode": 400
  }
}

Common Error Codes

Yaygın Hata Kodları

SDKs (Coming Soon)

SDK'lar (Yakında)

We're working on official SDKs to make integration even easier. Stay tuned for:

Entegrasyonu daha da kolaylaştırmak için resmi SDK'lar üzerinde çalışıyoruz. Şu konularda bizi takip edin:

Meanwhile, you can use the REST API directly with any HTTP client library.

Bu arada, herhangi bir HTTP istemci kütüphanesi ile REST API'yi doğrudan kullanabilirsiniz.

Best Practices

En İyi Uygulamalar

1. Implement Retry Logic

1. Yeniden Deneme Mantığı Uygulama

Use exponential backoff for transient failures:

Geçici hatalar için üssel geri çekilme kullanın:

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
    }
  }
}

2. Cache Frequently Used Routes

2. Sık Kullanılan Rotaları Önbelleğe Alma

Implement client-side caching for repeated route queries to reduce API calls and improve performance.

API çağrılarını azaltmak ve performansı artırmak için tekrarlanan rota sorguları için istemci tarafında önbelleğe alma uygulatın.

3. Handle Rate Limits Gracefully

3. Kullanım Sınırlarını Zararlı Yönetin

Monitor rate limit headers and implement queuing when approaching limits.

Kullanım sınırı başlıklarını izleyin ve sınırlara yaklaşırken sıralama uygulatın.

4. Use Webhook Notifications

4. Webhook Bildirimlerini Kullanın

For long-running operations, consider using webhooks instead of polling.

Uzun süren işlemler için sürekli kontrol etmek yerine webhook'ları kullanmayı düşünün.