Route Planner
route_plannerRead-only
Calculate optimized routes for car, bicycle, pedestrian, or public transport between multiple locations. Supports multi-stop routing with automatic waypoint resolution and turn-by-turn instructions.
Instructions
Calculate optimized routes between two or more locations for car, bicycle, or pedestrian transport modes. Supports multi-stop routing with automatic waypoint resolution from place names or coordinates. Returns turn-by-turn instructions, distance, duration, and route geometry.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| transport | No | Transport mode used to compute the route. Exactly one of: "car" (passenger car, default; supports type="fastest"|"shortest"|"scenic"), "lorry" or "truck" (heavy goods vehicle — set the `vehicle` field with dimensions/weight; supports type="fastest"|"shortest"|"scenic"), "pedestrian" (walking; supports type="fastest"|"shortest"|"scenic"), "bike" (bicycle — use `fitness_factor` and `vehicle.profile`; supports type="fastest"|"shortest"; type="economic" REQUIRES an eBike `vehicle.profile` (pedelec/spedelec variant); type="scenic" is NOT supported), "public" (public transport: bus/train/tram; supports type="fastest"|"shortest"). | car |
| type | No | Route optimization objective. Exactly one of: "fastest" (minimize travel time, default; valid for all transport modes). "shortest" (minimize distance; valid for all transport modes). "economic" (minimize energy use; VALID ONLY for e-bikes — requires transport="bike" AND `vehicle.profile` set to one of the eBike sub-profiles: "road_pedelec", "cross_pedelec", "city_pedelec", "mountain_pedelec" (or the "_spedelec" 45 km/h variants). Do NOT use for cars, trucks, regular bikes, or pedestrians). "scenic" (prefer scenic roads at the cost of travel time; valid for car, truck/lorry, and pedestrian. NOT valid for transport="bike" — bicycle routing has no scenic cost model. Use "fastest" for bikes and tune `fitness_factor`/`vehicle.profile` instead). | fastest |
| origin | Yes | Route start point. Provide `coordinates` (longitude, latitude) when known - preferred for accuracy. Otherwise provide `location` to resolve the start from a place name or address. | |
| destination | Yes | Route end point. Provide `coordinates` (longitude, latitude) when known - preferred for accuracy. Otherwise provide `location` to resolve the end from a place name or address. | |
| avoid | No | Road features to exclude from the route. Array of zero or more of: "highway" (motorways), "toll" (toll roads), "ferry", "unpaved" (dirt/gravel), "turnaround" (U-turns), "traffic" (heavy-traffic segments), "roadblocks" (closures). Empty array (default) means avoid nothing. Adding entries may significantly increase travel time or fail to find a route. | |
| details | No | Response verbosity. Exactly one of: "full": geometry + turn-by-turn instructions (default; use when guiding the user). "path": geometry only, no instructions (use for map rendering). "timedistance": only total time and distance (smallest response; use for ETAs). | full |
| number_of_routes | No | Number of route alternatives to return, including the recommended primary route. Range: 1-3 for car/truck/bike/pedestrian; 1-11 for transport="public". Default 1. Use >1 only when the user explicitly wants alternatives. | |
| fitness_factor | No | Effort tolerance for bike and pedestrian routing, in [0.0, 1.0]. 0.0 = avoid steep climbs and long routes (low fitness); 1.0 = accept steep/hard terrain (high fitness). Default 0.5. Ignored for car/truck/public. | |
| intermediate_waypoints | No | Ordered list of stops between origin and destination, excluding origin and destination themselves. Order in the array defines visit order for fixed stops. Each entry has a `type` discriminator - see RoutingStopParametersSchema for the per-type rules ("coordinates", "address", "reference_poi", or "along_route_poi"). Default empty array (no intermediate stops). | |
| emergency | No | Enable emergency-vehicle routing. When true, the engine relaxes certain traffic restrictions (e.g. one-way streets, restricted zones) that apply to emergency services. Default false. Set to true ONLY for ambulance/fire/police use cases. | |
| locale | No | ISO 639-2 / ISO 639-3 language code for turn-by-turn instruction text (e.g. "en", "de", "fr", "es"). Default "en". Does not affect routing, only instruction language. | en |
| vehicle | No | Vehicle profile used for restrictions and energy modelling. REQUIRED for transport="truck"/"lorry" (dimensions/weight to avoid restricted roads). REQUIRED for electric vehicles (set `vehicle.fuel="electric"` and `vehicle.ev` for charging-aware routing). OPTIONAL for car/bike/pedestrian - defaults apply if omitted. |