Guides & Tutorials

Step-by-step guides to help you integrate and optimize your routing solutions.

Quick Start Guide

Step 1: Get Your API Key

FREE10,000 monthly credits included

Step 2: Make Your First Request

Here's a simple example to optimize a delivery route with 3 stops:

curl -X POST https://api.routes.ai/v1/solve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {
        "id": "warehouse",
        "lat": 37.7749,
        "lng": -122.4194,
        "type": "depot"
      },
      {
        "id": "customer_1",
        "lat": 37.7849,
        "lng": -122.4094,
        "demand": 15,
        "time_window": [540, 720]
      },
      {
        "id": "customer_2", 
        "lat": 37.7649,
        "lng": -122.4294,
        "demand": 25,
        "time_window": [480, 600]
      },
      {
        "id": "customer_3",
        "lat": 37.7549,
        "lng": -122.4394,
        "demand": 10,
        "time_window": [600, 800]
      }
    ],
    "vehicles": [
      {
        "id": "truck_1",
        "capacity": 100,
        "start": "warehouse",
        "end": "warehouse",
        "shift_start": 480,
        "shift_end": 960
      }
    ],
    "objective": "minimize_total_time"
  }'

Step 3: Get the Solution

The API returns a job ID immediately. Poll for the solution:

curl -X GET https://api.routes.ai/v1/solve/job_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response with optimized route:

{
  "job_id": "job_abc123",
  "status": "completed",
  "solution": {
    "routes": [
      {
        "vehicle_id": "truck_1",
        "stops": [
          "warehouse",
          "customer_2",
          "customer_1", 
          "customer_3",
          "warehouse"
        ],
        "total_distance": 12.4,
        "total_time": 185,
        "total_demand": 50
      }
    ],
    "total_distance": 12.4,
    "total_time": 185,
    "credits_consumed": 4
  }
}

Node.js Integration

Install the SDK:

npm install @routes-ai/sdk

const RoutesAI = require('@routes-ai/sdk');

const client = new RoutesAI({
  apiKey: process.env.ROUTES_AI_API_KEY
});

async function optimizeRoute() {
  const job = await client.solve({
    nodes: [...],
    vehicles: [...],
    objective: 'minimize_distance'
  });
  
  const solution = await client.waitForSolution(job.id);
  console.log(solution.routes);
}

Python Integration

Install the SDK:

pip install routes-ai

from routes_ai import RoutesAI

client = RoutesAI(api_key="your_api_key")

# Define your optimization problem
job = client.solve(
    nodes=[...],
    vehicles=[...],
    objective="minimize_distance"
)

# Wait for solution
solution = client.wait_for_solution(job.id)
print(solution.routes)

🚛 Vehicle Routing with Capacity Constraints (CVRP)

Optimize routes for multiple vehicles with different capacities and constraints.

{
  "nodes": [
    {"id": "depot", "lat": 37.7749, "lng": -122.4194},
    {"id": "stop_1", "lat": 37.7849, "lng": -122.4094, "demand": 20},
    {"id": "stop_2", "lat": 37.7649, "lng": -122.4294, "demand": 35},
    {"id": "stop_3", "lat": 37.7549, "lng": -122.4394, "demand": 15}
  ],
  "vehicles": [
    {"id": "small_truck", "capacity": 50, "start": "depot", "end": "depot"},
    {"id": "large_truck", "capacity": 100, "start": "depot", "end": "depot"}
  ],
  "objective": "minimize_vehicles_used"
}

⏰ Time Window Optimization (VRPTW)

Schedule deliveries within specific time windows for each customer.

{
  "nodes": [
    {"id": "depot", "lat": 37.7749, "lng": -122.4194},
    {
      "id": "morning_delivery",
      "lat": 37.7849, "lng": -122.4094,
      "demand": 20,
      "time_window": [480, 600],  // 8:00 AM - 10:00 AM
      "service_time": 15
    },
    {
      "id": "afternoon_delivery", 
      "lat": 37.7649, "lng": -122.4294,
      "demand": 15,
      "time_window": [720, 900],  // 12:00 PM - 3:00 PM
      "service_time": 10
    }
  ],
  "vehicles": [
    {
      "id": "truck_1",
      "capacity": 100,
      "start": "depot",
      "shift_start": 420,  // 7:00 AM
      "shift_end": 1020    // 5:00 PM
    }
  ]
}

📍 Multi-Depot Routing

Optimize routes across multiple warehouses or service centers.

{
  "nodes": [
    {"id": "warehouse_north", "lat": 37.8049, "lng": -122.4194},
    {"id": "warehouse_south", "lat": 37.7449, "lng": -122.4194},
    {"id": "customer_1", "lat": 37.7849, "lng": -122.4094, "demand": 25},
    {"id": "customer_2", "lat": 37.7649, "lng": -122.4294, "demand": 30}
  ],
  "vehicles": [
    {"id": "truck_n1", "capacity": 50, "start": "warehouse_north"},
    {"id": "truck_n2", "capacity": 50, "start": "warehouse_north"},
    {"id": "truck_s1", "capacity": 75, "start": "warehouse_south"}
  ],
  "objective": "minimize_total_distance"
}