Round Trip
round_tripRead-only
Create a round-trip route starting and ending at the same location. Specify a time or distance range to define the loop extent.
Instructions
Generate a circular round-trip route that starts and ends at the same location. Accepts a starting point as coordinates or place name, with a range parameter for time-based (seconds) or distance-based (meters) loop extent. Returns route geometry, distance, and duration for the circular route.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| transport | No | Transport mode for the round trip. Exactly one of: "car", "lorry"/"truck", "pedestrian", "bike" (default for leisure loops), "public". | car |
| type | No | Optimization objective and units for `range`. Exactly one of: "fastest" — `range` interpreted as SECONDS of travel time (default; valid for all transport modes). "shortest" — `range` interpreted as METERS of travel distance (valid for all transport modes). "economic" — energy-minimizing cost model; VALID ONLY for e-bikes (requires transport="bike" AND `vehicle.profile` set to a pedelec/spedelec sub-profile such as "city_pedelec"). Range units same as "fastest". Do NOT use for cars, trucks, regular bikes, or pedestrians. "scenic" — prefers scenic roads; valid for car, truck/lorry, and pedestrian. NOT valid for transport="bike". Range units same as "fastest". | fastest |
| departure | Yes | Start AND end point of the loop (round trips begin and end at the same location). Provide `coordinates` (longitude, latitude) when known, or `location` to resolve from a place/address. | |
| avoid | No | Road features to exclude. Array of zero or more of: "highway", "toll", "ferry", "unpaved", "turnaround", "traffic", "roadblocks". Empty array (default) means avoid nothing. | |
| number_of_routes | No | Number of distinct loop variants to return. Range: 1-3 for car/truck/bike/pedestrian; 1-11 for transport="public". Default 1. Use >1 to offer the user a few different loops of similar length. | |
| terrain | No | When true, include an elevation/terrain profile alongside the route geometry. Default false. Enable for hiking/cycling routes where elevation matters. | |
| range | Yes | Target size of the loop. Must be positive. UNITS depend on `type`: SECONDS when type="fastest"/"economic"/"scenic", METERS when type="shortest". Example: range=3600 with type="fastest" for 1-hour loop. | |
| random_seed | No | Integer seed for the route-generation randomizer. Use the same seed to reproduce a loop; change it to get a different loop with the same parameters. | |
| locale | No | ISO 639-2 / ISO 639-3 language code for place names in the response. Default "en". | en |
| departure_time | No | Departure time as a Unix epoch timestamp in SECONDS (not milliseconds). Pass 0 (default) to use the server-side current time. Used for traffic-aware and time-dependent routing. | |
| profile | No | Detailed sub-profile for bike/pedestrian modes. For transport="bike": "city" (default), "road", "cross", "mountain". For e-bikes append "_pedelec" (≤25 km/h) or "_spedelec" (≤45 km/h). For transport="pedestrian": "walk" (default) or "hike". Ignored for car/truck/public. Shortcut for `vehicle.profile`; if both are set, `vehicle.profile` takes precedence. | city |
| vehicle | No | Vehicle profile used to apply road restrictions and energy modelling to the loop. REQUIRED for transport="truck"/"lorry" (dimensions/weight to avoid restricted roads). REQUIRED for electric vehicles (set `vehicle.fuel="electric"` and `vehicle.ev` for range-aware loops). REQUIRED for bike with type="economic" — set `vehicle.profile` to a pedelec/spedelec eBike variant. OPTIONAL for car/regular-bike/pedestrian — defaults apply when omitted. When `vehicle.profile` is set it overrides the top-level `profile` field. |