directions
Read-onlyIdempotent
Generate routes, ETAs, and turn-by-turn directions between locations. Live traffic is post-route ETA enrichment and does not change the returned path (path_influenced=false); truck traffic adjustments are slowdown-only. Supports car / truck / motorcycle / pedestrian / bicycle, with hazmat + dimension + toll avoidance for commercial routing. ETAs are returned as ISO 8601 with timezone offset (in the destination's local timezone). Use vehicle_profile presets (10 total — DRY_VAN_53, FLATBED_48/_40, STEP_DECK, TANKER, BOX_TRUCK_26, AUTO_CARRIER, SPRINTER_VAN, DOUBLE_TRAILER, OVERSIZE) when routing trucks — they set height/weight/length in one parameter.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Destination: address string ('Houston, TX'), 'lat,lon' string, or { lat, lon } object | |
| via | No | Intermediate stops in order; same shape as from/to. Up to 48 waypoints (max 50 total locations). | |
| from | Yes | Origin: address string ('Houston, TX'), 'lat,lon' string, or { lat, lon } object | |
| units | No | Distance units (default: miles). Accepts 'km'/'mi' as aliases. | |
| hazmat | No | Set true when transporting hazardous materials to avoid restricted routes | |
| costing | No | Transport mode (default: auto). Use 'truck' for commercial vehicles | |
| axle_load | No | Axle weight in metric tons (e.g. 9.07t = 20,000 lbs per axle) | |
| top_speed | No | Maximum speed in km/h (default 105 for trucks) | |
| use_ferry | No | Ferry preference 0-1 (0=avoid, 1=allow) | |
| alternates | No | Number of genuine motorized alternate routes to request (0, 1, or 2). Positive values require no via waypoints. | |
| axle_count | No | Number of axles (default 5 for semi-trailer) | |
| avoid_tolls | No | Avoid toll roads when user requests toll-free routing | |
| truck_width | No | Truck width in meters (e.g. 2.6m = 8'6") | |
| truck_height | No | Truck height in meters (e.g. 4.11m = 13'6"). Triggers bridge avoidance | |
| truck_length | No | Truck length in meters (e.g. 16.2m = 53') | |
| truck_weight | No | Truck weight in metric tons (e.g. 36.3t = 80,000 lbs). Triggers weight-restricted road avoidance | |
| use_highways | No | Highway preference 0-1 (0=avoid, 1=prefer) | |
| include_traffic | No | Apply post-route live-traffic ETA enrichment (default: true). Traffic does not change the returned path; truck adjustments are slowdown-only. | |
| vehicle_profile | No | Preset vehicle profile (10): DRY_VAN_53, FLATBED_48, FLATBED_40, STEP_DECK, TANKER, BOX_TRUCK_26, AUTO_CARRIER, SPRINTER_VAN, DOUBLE_TRAILER, OVERSIZE. Each sets height/weight/length/axle_count for that vehicle class in one parameter (e.g. DRY_VAN_53 = 4.11m tall, 36.3t, 22.25m long, 5 axles; OVERSIZE = 4.88m tall, 3.66m wide, 45.36t). The response echoes the applied dims in costing_options.truck. Any individual truck_height/truck_weight/etc. overrides a single field. | |
| include_geometry | No | Route geometry shape control. "none" returns origin/destination Points only. "encoded" returns an encoded polyline6 string in a top-level `geometry` field plus origin/destination Points (≈95% smaller than raw GeoJSON; decode with @mapbox/polyline at precision 6). "full" emits decoded coordinates as a LineString in `geojson.features[0]`. When omitted (default), small routes use "full" and long routes auto-downgrade to "encoded" with a `geometry_truncated` warning. | |
| include_elevation | No | When true, include available route elevation fields. Point elevation may be returned for the origin and destination. Cumulative gain/loss is returned only when route-profile elevation is available. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | No | ||
| geojson | No | ||
| metrics | No | ||
| summary | No | Map of scalar facts the LLM should surface verbatim | |
| alternates | No | ||
| display_hint | No | ||
| timezone_end | No | ||
| traffic_route | No | ||
| timezone_start | No | ||
| costing_options | No | ||
| elevation_end_m | No | ||
| base_arrival_utc | Yes | Arrival time derived from the base duration, expressed as an ISO 8601 UTC timestamp. | |
| elevation_end_ft | No | ||
| elevation_gain_m | No | ||
| elevation_loss_m | No | ||
| elevation_gain_ft | No | ||
| elevation_loss_ft | No | ||
| elevation_start_m | No | ||
| base_arrival_local | Yes | Arrival time derived from the base duration in the destination's local time, or null when the local timezone is unavailable. | |
| elevation_start_ft | No | ||
| traffic_provenance | Yes | ||
| base_duration_seconds | Yes | Route duration before any traffic-based adjustment, in seconds. | |
| effective_arrival_utc | Yes | Authoritative arrival time for this response, expressed as an ISO 8601 UTC timestamp. | |
| traffic_delay_seconds | Yes | Effective duration minus base duration, in seconds. Positive means traffic made the ETA slower, negative means it made the ETA faster, and zero means the duration was unchanged. For truck costing, general traffic evidence is slowdown-only, so this value is never negative. | |
| effective_arrival_local | Yes | Authoritative arrival time in the destination's local time, or null when the local timezone is unavailable. | |
| effective_duration_seconds | Yes | Authoritative duration for this response, in seconds, after any applicable traffic-based adjustment. |