How to Avoid Tolls, Highways, Ferries, and Restricted Locations During Optimization

Avoid tolls, highways, ferries, and restricted locations during optimization

You need to optimize assignments and stop order while keeping planned travel away from selected road features or locations. Add top-level avoid rules to the Route Planner request so the same routing restrictions are considered across all agent plans.

Avoidance changes the travel costs used by optimization and the resulting routes. It does not change which tasks exist; constraints may make a plan longer or leave work unassigned when no feasible route remains.

Task flow: agents, tasks, and avoidance rules → Route Planner API → restricted optimized routes and schedules.

Choose avoidance rules

For tolls, highways, and ferries, an optional importance from 0 to 1 controls how strongly the preference applies; 1 is most important. Omit it to use the service default.

Location values use objects with explicit lat and lon fields. This differs from agent and task location arrays, which use [longitude, latitude] order.

The API also supports rules for green zones, transfers, polygons, and country codes. Keep the request focused on restrictions that are operationally meaningful; combining many strong rules can produce long detours or an infeasible plan.

Avoid roads and one location

This Munich example avoids tolls and ferries, strongly prefers avoiding highways, and keeps the route away from one restricted coordinate.

POST https://api.geoapify.com/v1/routeplanner?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "mode": "drive",
  "agents": [
    {
      "id": "courier-a",
      "start_location": [11.5775, 48.1374],
      "end_location": [11.5775, 48.1374]
    }
  ],
  "jobs": [
    {
      "id": "delivery-1",
      "location": [11.7499, 48.2142],
      "duration": 300
    }
  ],
  "avoid": [
    {"type": "tolls"},
    {"type": "highways", "importance": 0.8},
    {"type": "ferries"},
    {
      "type": "locations",
      "values": [{"lat": 48.175, "lon": 11.65}]
    }
  ]
}

Reduced response:

{
  "type": "FeatureCollection",
  "features": [
    {
      "properties": {
        "agent_id": "courier-a",
        "distance": 47139,
        "time": 4692
      }
    }
  ]
}

The returned distance is 47,139 meters and the plan time is 4,692 seconds for this exact set of restrictions. Compare it with a request containing no avoid rules if the application needs to show the cost of the detour.

Validate restricted routes

• Apply avoid at the request level only when the restriction should affect every agent. The request does not define separate avoidance rules per agent.
• Treat avoidance as routing configuration, not as a replacement for legal or safety validation. Verify regulated vehicle restrictions against authoritative operational data.
• Compare distance, time, assigned work, and reported issues with and without the rule before enabling it broadly.
• Explain detours to dispatchers and users. A restriction may legitimately increase travel distance or time.
• Inspect properties.issues for unassigned work. A successful HTTP response does not guarantee that every job or shipment remains feasible.
• Use a polygon when an area must be avoided rather than approximating a large area with many individual points.
• Keep coordinates and polygons away from the origin, destination, and required task locations unless the intended behavior has been tested.

When a road is temporarily closed, update or remove the relevant rule when the closure ends. Avoid storing short-lived restrictions as permanent fleet configuration.