How to Avoid Tolls, Highways, and Ferries

Avoid tolls, highways, and ferries

You need a route that prefers local roads, avoids toll costs, or stays off ferries. The Routing API accepts one or more avoid rules and considers them while selecting the path between your waypoints.

Avoid rules express preferences rather than guaranteed exclusions. The router can still use an avoided feature when no practical alternative exists.

Task flow: waypoints and road preferences → Routing API → route that avoids the selected features when possible.

Understand avoid rules

Set avoid to one rule or join several rules with |.

Road-feature rules can include an importance from 0 to 1, for example tolls:0.8. A larger value makes the preference stronger. Omitting the importance applies the normal avoid behavior.

When constructing the request in code, use URLSearchParams; it safely encodes separators such as | for transport while keeping the logical value unchanged.

Avoid road features

The following request avoids tolls and ferries between Baltimore and Philadelphia:

https://api.geoapify.com/v1/routing?waypoints=39.2904,-76.6122|39.9526,-75.1652&mode=drive&avoid=tolls|ferries&format=json&apiKey=YOUR_API_KEY

Reduced response:

{
  "results": [
    {
      "distance": 165286,
      "time": 7053.077,
      "legs": [
        {
          "distance": 165286,
          "time": 7053.077
        }
      ]
    }
  ]
}

Use the same request shape for other preferences:

avoid=highways
avoid=ferries:0.9
avoid=tolls:0.8|highways:0.5

The returned distance is in meters and time is in seconds. Here, 165286 meters is about 165.3 km, and 7053 seconds is about 1 hour 58 minutes.

Handle unavoidable roads

Treat avoid rules as routing preferences and verify the returned route before presenting a claim such as “toll-free.” In particular:

• the router may use an avoided feature when it cannot find a reasonable alternative;
• toll and highway rules apply to relevant motorized modes, not every walking, cycling, or transit mode;
• stronger or multiple avoid rules can increase calculation time and API credit cost;
• avoiding a road feature may produce a substantially longer route;
• road attributes depend on available map data and can change as the road network is updated.

Request route details when your application must inspect properties such as toll, ferry, or road class. If avoiding a feature is a hard legal or operational constraint, validate the returned steps and handle the case where no acceptable route is available.