API Overview

This API is designed to calculate the shortest / most efficient route based on given location points. During calculation, both the OR-Tools algorithm and AI-based optimization are executed, and the results are returned comparatively. The best result is indicated in the winner field.

Çoklu Araç (VRP) Desteği: Sistemimiz, birden fazla araç kullanıldığında noktaları coğrafi olarak en mantıklı kümelere (Clustering) ayırır ve her bir kümeyi paralel iş parçacıkları (multithreading) ile optimize eder. Bu sayede karmaşık lojistik operasyonları saniyeler içinde AI tarafından çözülür.

Authentication

You must use a Bearer token under the Authorization header for all requests. You can obtain your API key from the dashboard.

BASH

curl -X POST https://routing.deede.tr/api/v1/optimize.php \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'
            

HTTP Request Info

Method: POST
Content-Type: application/json
Response-Type: application/json
Timeout Recommendation: 60 seconds (minimum)

Client-side timeout duration should be set to 60 seconds due to potentially long-running multi-vehicle calculations.

Route Solver

Finds the best route using the Hybrid Engine (AI + OR-Tools). Supports multiple vehicles with automatic clustering.

POST

/api/v1/optimize.php

Çoklu Araç (VRP) Kullanımı

Birden fazla araç için num_vehicles parametresini isteğe eklemeniz yeterlidir. Sistem, noktaları otomatik olarak en verimli kümelere ayırır ve her bir araç için ayrı rota hesaplar.

Request Body (JSON)

JSON

{
  // Coordinate List: [Longitude, Latitude] or [Latitude, Longitude]
  // First point (Index 0) is always considered the START (Depot).
  "coords": [
    [28.978493, 41.009688],
    [28.977893, 41.010113],
    [28.977303, 41.01047],
    [28.980000, 41.01100],
    [28.981000, 41.01200]
  ],
  // Return to depot? (Optional, Default: true)
  "return_to_depot": true,
  "num_vehicles": 2
}
            

Code Examples

Python Request Example

PYTHON

import requests

url = "https://routing.deede.tr/api/v1/optimize.php"
payload = {
    "coords": [
        [28.978493, 41.009688],
        [28.977893, 41.010113],
        [28.977303, 41.01047],
        [28.980000, 41.01100],
        [28.981000, 41.01200]
    ],
    "return_to_depot": True,
    "num_vehicles": 2
}

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.post(url, json=payload, headers=headers, timeout=60)
response.raise_for_status()

data = response.json()
print(data["best_route"], data["best_distance"])
            

PHP Request Example

PHP

<?php
$ch = curl_init("https://routing.deede.tr/api/v1/optimize.php");

$data = json_encode([
    "coords" => [
        [28.978493, 41.009688],
        [28.977893, 41.010113],
        [28.977303, 41.01047],
        [28.980000, 41.01100],
        [28.981000, 41.01200]
    ],
    "return_to_depot" => true,
    "num_vehicles" => 2
]);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: Bearer YOUR_API_KEY"
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result["best_route"]);
            

Successful Response (200 OK)

JSON

{
  "success": true,
  "winner": "OR-Tools",
  "best_distance": 36036.0,
  "best_route": [0, 1, 2, 0, 0, 3, 4, 0],
  "improvement_percentage": 0.0,
  "matrix_fetch_duration": 0.000115,
  "results": {
    "ai": {
      "distance": 36036.0,
      "duration": 32.62,
      "model_duration": 17.12,
      "route": [0, 1, 2, 4, 3]
    },
    "ortools": {
      "distance": 36036.0,
      "duration": 17.00,
      "route": [0, 1, 2, 4, 3]
    }
  },
  "route_geometry": {
    "type": "LineString",
    "coordinates": [...] 
  }
}
            

Field Descriptions

best_distance: Total distance found (meters)
best_route: Visit order of points (index-based). In multi-vehicle scenarios, routes are separated by 0 (e.g., [0,1,2,0,0,3,4,0]). (Çoklu araç durumunda rotalar 0 durakları ile birbirinden ayrılır).
winner: The algorithm that gave the best result (AI or OR-Tools)
num_vehicles: Araç sayısı (Varsayılan: 1). Sistem, noktaları bu sayıya göre kümelere bölerek paralel optimize eder.
results.ai / results.ortools: Detailed metrics for the algorithms
route_geometry: GeoJSON compatible route for map plotting

Error & Debug Notes

Do not parse JSON if you receive a status code other than HTTP 200.
If an empty response or HTML is returned, response.text should be logged.
JSON parse errors are usually caused by timeouts or upstream errors.