Guides & Tutorials
Step-by-step guides to help you integrate and optimize your routing solutions.
Quick Start Guide
Step 1: Get Your API Key
Sign up for a free account and obtain your API key from the dashboard.
FREE10,000 monthly credits included
Get API Key →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"
}
💡 Best Practices & Tips
Performance Optimization
- • Use distance matrices for repeated optimizations
- • Batch multiple small problems together
- • Cache solutions for similar problem types
- • Set appropriate time limits for large problems
Error Handling
- • Always check job status before polling
- • Implement exponential backoff for polling
- • Handle rate limit errors gracefully
- • Validate input data before submission