Alternative Routes¶

Generate multiple route options for the same origin-destination pair, enabling comparison and flexible decision-making based on distance, duration, and other factors.

🎯 What are Alternative Routes?¶

Alternative routes provide different path options between the same origin and destination. Each alternative offers a trade-off between various factors like:

Total distance
Travel duration
Road types
Traffic conditions
Toll costs

📋 Basic Usage¶

Requesting Alternatives¶

Use the alternatives parameter to specify how many alternative routes you want (0-5):

{
  "mode": "car",
  "origin": [41.0082, 28.9784],
  "destination": [41.0150, 28.9850],
  "alternatives": 3,
  "minimize": "duration"
}

Response Structure¶

Each alternative is returned as a separate route:

{
  "routes": [
    {
      "id": "route_0",
      "sections": [...],
      // Main route - optimized for minimize criteria
    },
    {
      "id": "route_1",
      "sections": [...],
      // Alternative 1 - different path
    },
    {
      "id": "route_2",
      "sections": [...],
      // Alternative 2 - another different path
    }
  ]
}

💡 Use Cases¶

1. Route Comparison¶

Compare routes to choose the best option:

{
  "mode": "car",
  "origin": [41.0082, 28.9784],
  "destination": [41.0150, 28.9850],
  "alternatives": 2,
  "minimize": "duration",
  "tolls": true,
  "currency": "EUR"
}

Analysis: - Route 0: Fastest, uses toll roads (€2.50) - Route 1: Slightly slower, no tolls (€0.00) - Route 2: Scenic route, longest duration

2. Backup Routes¶

Provide drivers with fallback options:

{
  "mode": "truck",
  "origin": [41.0082, 28.9784],
  "destination": [41.0150, 28.9850],
  "alternatives": 1,
  "vehicle": {
    "length": 1200,
    "height": 350
  },
  "minimize": "distance"
}

3. Cost vs Time Analysis¶

Evaluate trade-offs between speed and cost:

{
  "mode": "car",
  "origin": [41.0082, 28.9784],
  "destination": [41.0150, 28.9850],
  "alternatives": 3,
  "minimize": "distance",
  "tolls": true,
  "currency": "USD"
}

🔧 Configuration Options¶

Number of Alternatives¶

Value	Description	Use Case
`0`	No alternatives (default)	Simple routing
`1-2`	Few alternatives	Quick comparison
`3-5`	Multiple options	Detailed analysis

Minimize Criteria Impact¶

The minimize parameter affects which route is returned first:

// Fastest route first
{
  "alternatives": 2,
  "minimize": "duration"
}

// Shortest route first
{
  "alternatives": 2,
  "minimize": "distance"
}

📊 Comparing Alternatives¶

Distance vs Duration Trade-off¶

import requests

response = requests.post(url, json={
    "tasks": [{
        "origin": [41.0082, 28.9784],
        "destination": [41.0150, 28.9850],
        "alternatives": 3,
        "tolls": true,
        "currency": "EUR"
    }]
})

data = response.json()
for idx, route in enumerate(data["tasks"][0]["routes"]):
    total_distance = 0
    total_duration = 0
    total_toll_cost = 0

    for section in route["sections"]:
        summary = section["summary"]
        total_distance += summary["distance"]
        total_duration += summary["duration"]
        total_toll_cost += summary.get("toll_cost", 0)

    print(f"\n=== Route {idx} ===")
    print(f"Distance: {total_distance/1000:.2f} km")
    print(f"Duration: {total_duration/60:.2f} minutes")
    print(f"Toll Cost: €{total_toll_cost:.2f}")
    print(f"Efficiency: {(total_distance/1000)/(total_duration/3600):.2f} km/h")

Example Output¶

=== Route 0 ===
Distance: 8.50 km
Duration: 12.30 minutes
Toll Cost: €2.50
Efficiency: 41.46 km/h

=== Route 1 ===
Distance: 10.20 km
Duration: 15.50 minutes
Toll Cost: €0.00
Efficiency: 39.48 km/h

=== Route 2 ===
Distance: 9.80 km
Duration: 18.20 minutes
Toll Cost: €1.20
Efficiency: 32.31 km/h

🎯 Best Practices¶

1. Request What You Need¶

Don't request more alternatives than necessary: - More alternatives = longer calculation time - Most users need 1-2 alternatives maximum

2. Set Clear Minimize Criteria¶

The first route always optimizes for your minimize parameter: - "duration" - Fastest route first - "distance" - Shortest route first

3. Enable Toll Calculations¶

Get complete cost comparison:

{
  "alternatives": 2,
  "tolls": true,
  "currency": "EUR"
}

4. Consider Vehicle Specifications¶

For trucks, alternatives consider vehicle constraints:

{
  "mode": "truck",
  "alternatives": 2,
  "vehicle": {
    "height": 350,
    "hazardous_goods": ["flammable"]
  }
}

⚠️ Important Considerations¶

Availability¶

Alternative routes may not always be available: - In rural areas with limited road networks - For highly constrained truck routing - When origin and destination are very close

Quality¶

The quality of alternatives depends on: - Road network density - Geographic area characteristics - Vehicle constraints

Performance¶

More alternatives increase: - API response time - Payload size - Processing requirements

🔍 Alternative Route Differences¶

Routes differ in various ways:

Road Types¶

Route 0: Mix of highways and main roads
Route 1: Local roads, avoiding highways
Route 2: Scenic route through secondary roads

Features¶

Route 0: Uses toll roads for speed
Route 1: Avoids tolls completely
Route 2: Balances speed and cost

Trade-offs¶

Route 0: Fastest but expensive
Route 1: Economical but slower
Route 2: Middle ground option

📚 See Also¶

Alternative routes provide flexibility and enable informed decision-making. Request only what you need for optimal performance.