Waypoints & Multi-Stop Routing

Waypoints allow you to add intermediate stops along your route, enabling complex multi-stop routing scenarios for deliveries, services, and tours.

🎯 What are Waypoints?

Waypoints are intermediate locations that your route must pass through between the origin and destination. The Route API automatically:

• Determines the optimal order to visit waypoints
• Calculates distances and durations for each segment
• Provides turn-by-turn geometry for the complete route

📋 Basic Usage

Adding Waypoints

Waypoints are specified as an array of coordinate pairs:

{
  "mode": "car",
  "origin": [41.0082, 28.9784],
  "waypoints": [
    [41.0100, 28.9800],
    [41.0122, 28.9820],
    [41.0135, 28.9835]
  ],
  "destination": [41.0150, 28.9850],
  "minimize": "duration"
}

Response Structure

The response includes sections for each segment of your route:

{
  "routes": [
    {
      "sections": [
        {
          "departure": {
            "coordinate": [41.0082, 28.9784],
            "type": "place"
          },
          "arrival": {
            "coordinate": [41.0100, 28.9800],
            "waypoint": 0
          },
          "summary": {
            "distance": 2150,
            "duration": 420
          }
        },
        {
          "departure": {
            "coordinate": [41.0100, 28.9800],
            "waypoint": 0
          },
          "arrival": {
            "coordinate": [41.0122, 28.9820],
            "waypoint": 1
          },
          "summary": {
            "distance": 2850,
            "duration": 480
          }
        }
        // ... more sections
      ]
    }
  ]
}

💡 Use Cases

1. Delivery Routes

Plan efficient multi-stop delivery routes:

{
  "mode": "car",
  "origin": [41.0082, 28.9784],
  "waypoints": [
    [41.0100, 28.9800],  // Customer 1
    [41.0122, 28.9820],  // Customer 2
    [41.0135, 28.9835]   // Customer 3
  ],
  "destination": [41.0082, 28.9784],  // Return to depot
  "minimize": "duration"
}

2. Service Technician Routes

Optimize service call sequences:

{
  "mode": "car",
  "origin": [41.0082, 28.9784],  // Office
  "waypoints": [
    [41.0100, 28.9800],  // Service Call 1
    [41.0150, 28.9850],  // Service Call 2
    [41.0180, 28.9880]   // Service Call 3
  ],
  "destination": [41.0082, 28.9784],  // Return to office
  "minimize": "distance"
}

3. Tourist Routes

Create sightseeing tours with multiple stops:

{
  "mode": "car",
  "origin": [41.0082, 28.9784],  // Hotel
  "waypoints": [
    [41.0100, 28.9800],  // Museum
    [41.0122, 28.9820],  // Restaurant
    [41.0150, 28.9850]   // Park
  ],
  "destination": [41.0082, 28.9784],  // Return to hotel
  "minimize": "duration"
}

🔧 Best Practices

1. Waypoint Ordering

The API visits waypoints in the order specified. For optimal routing: - Consider geographic proximity - Account for time constraints - Use the Optimize API if you need automatic sequencing

2. Number of Waypoints

• Recommended: 1-10 waypoints per route
• Maximum: Check API limits in documentation
• More waypoints = longer calculation time

3. Coordinate Accuracy

Use precise coordinates (6-7 decimal places) for accurate routing:

// Good
[41.008200, 28.978400]

// Less precise
[41.01, 28.98]

4. Return to Origin

To create round-trip routes, set destination = origin:

{
  "origin": [41.0082, 28.9784],
  "waypoints": [...],
  "destination": [41.0082, 28.9784]  // Same as origin
}

⚠️ Important Considerations

Waypoint Order

The Route API follows the specified waypoint order. If you need automatic optimization of waypoint sequence, use the Optimize API instead.

Route Complexity

More waypoints increase: - Calculation time - Response payload size - Route complexity

Geographic Distribution

Waypoints should be reasonably distributed. Very distant waypoints may result in: - Longer calculation times - Less optimal routes - Potential routing errors

📊 Waypoints vs Optimize API

Aspect	Waypoints (Route API)	Jobs (Optimize API)
Order	Fixed, as specified	Automatically optimized
Use Case	Known sequence	Need optimization
Complexity	Simple, straightforward	Advanced, multi-constraint
Output	Route geometry	Vehicle assignments + routes

🚀 Example Implementation

import requests

API_BASE_URL = "https://api.flio.ai"
ROUTE_ENDPOINT = "/solver/route"
API_KEY = "YOUR-API-KEY"

payload = {
    "tasks": [
        {
            "mode": "car",
            "origin": [41.0082, 28.9784],
            "waypoints": [
                [41.0100, 28.9800],
                [41.0122, 28.9820],
                [41.0135, 28.9835]
            ],
            "destination": [41.0150, 28.9850],
            "minimize": "duration"
        }
    ]
}

url = f"{API_BASE_URL}{ROUTE_ENDPOINT}?api_key={API_KEY}"
response = requests.post(url, json=payload)

if response.status_code == 200:
    data = response.json()
    # Process route with waypoints
    for route in data["tasks"][0]["routes"]:
        total_distance = sum(s["summary"]["distance"] for s in route["sections"])
        total_duration = sum(s["summary"]["duration"] for s in route["sections"])
        print(f"Total Distance: {total_distance}m")
        print(f"Total Duration: {total_duration}s")

📚 See Also

• Route API Reference
• Route Examples
• Alternative Routes
• Minimize Criteria

---

Waypoints enable flexible multi-stop routing while maintaining simplicity. For automatic stop sequencing and multi-vehicle optimization, consider the Optimize API.