Routing

Compute a route between two locations

Generate routes, ETAs, and turn-by-turn directions between locations. Live traffic is post-route ETA enrichment and does not change the returned path; truck traffic adjustments are slowdown-only. Supports auto / truck / bicycle / pedestrian / motorcycle, with hazmat + dimension + toll avoidance for commercial routing. Costs 1 quota unit per call.

post/v1/directions

Request

  • Base URL: https://geo.thinair.co
  • URL: https://geo.thinair.co/v1/directions
  • Auth: HTTP bearer

Request body

alternatesinteger

Number of genuine motorized alternate routes to request (0, 1, or 2). Positive values require no via waypoints.

costing'auto' | 'truck' | 'bicycle' | 'pedestrian' | 'motorcycle'

Transport mode. Default: auto.

presetstring

Routing preset — one of: car_default, truck_53, truck_box26, truck_tanker, truck_flatbed, truck_step_deck, truck_auto_carrier, truck_sprinter, truck_double, truck_oversize, motorcycle, scooter, bike, walk, transit. Sets costing AND dimensions together. NOTE: these are NOT the vehicle_profile names — passing a vehicle_profile id here is not recognised and currently falls back to a CAR route.

vehicle_profilestring

Truck dimension profile (10): DRY_VAN_53, FLATBED_48, FLATBED_40, STEP_DECK, TANKER, BOX_TRUCK_26, AUTO_CARRIER, SPRINTER_VAN, DOUBLE_TRAILER, OVERSIZE. Sets height/weight/length/axles. Distinct from preset, which also sets costing.

truck_heightnumber

Truck height (m)

truck_weightnumber

Truck weight (metric tons)

truck_widthnumber
truck_lengthnumber
hazmatboolean

Routing avoids hazmat-restricted roads when true.

axle_loadnumber
axle_countinteger
top_speednumber
use_highwaysnumber
use_ferrynumber
avoid_tollsboolean
include_trafficboolean

Apply post-route live-traffic ETA enrichment. Default: true. Traffic does not change the returned path (path_influenced=false); truck adjustments are slowdown-only.

include_weatherboolean
include_elevationboolean

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. Default: false (an extra upstream lookup, opt-in only).

units'miles' | 'kilometers'

Distance units. Default: miles. Accepts 'km'/'mi' as aliases.

depart_atstring date-time

Departure time (ISO 8601). Default: now.

include_geometry'none' | 'encoded' | 'full'

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.

Example request

{
  "origin": "Houston, TX",
  "destination": "Houston, TX",
  "via": [
    "Houston, TX"
  ],
  "costing": "auto",
  "preset": "truck_53",
  "vehicle_profile": "DRY_VAN_53",
  "truck_height": 4.11,
  "truck_weight": 36.3,
  "units": "miles"
}

Response

Successful route. See geojson for FeatureCollection geometry.

distancenumber required
distance_units'miles' | 'kilometers' required
duration_secondsnumber required
base_duration_secondsnumber required

The routing engine's duration with no traffic applied. Equal to duration_seconds.

effective_duration_secondsnumber required

What to plan against: base_duration_seconds adjusted by any computed traffic delay, else identical to base_duration_seconds.

traffic_delay_secondsnumber required

effective_duration_seconds minus base_duration_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.

traffic_adjusted_secondsnumber

Computed traffic-adjusted duration in seconds when traffic produced an adjustment. Use effective_duration_seconds as the authoritative duration for this response.

base_arrival_utcstring required

Arrival time assuming base_duration_seconds, in UTC.

base_arrival_localstring nullable required

Same instant as base_arrival_utc, in the destination's local time. Null when no destination timezone was resolved.

effective_arrival_utcstring required

Arrival time assuming effective_duration_seconds, in UTC.

effective_arrival_localstring nullable required

Same instant as effective_arrival_utc, in the destination's local time. Null when no destination timezone was resolved.

has_tollboolean required
has_highwayboolean required
has_ferryboolean required
costingstring required
legsobject[] required
maneuversobject[] required
maneuver_countnumber required
originobject required
destinationobject required
geojsonobject
timezone_startstring nullable required

IANA timezone at the route origin, or null when unresolved. Contains information from timezone-boundary-builder, which is made available under the Open Database License (ODbL) v1.0. Timezone boundaries © OpenStreetMap contributors. US legal-zone cross-check: U.S. Department of Transportation, Bureau of Transportation Statistics (public domain).

timezone_endstring nullable required

IANA timezone at the route destination, or null when unresolved. Contains information from timezone-boundary-builder, which is made available under the Open Database License (ODbL) v1.0. Timezone boundaries © OpenStreetMap contributors. US legal-zone cross-check: U.S. Department of Transportation, Bureau of Transportation Statistics (public domain).

timezone_start_status'resolved' | 'boundary_ambiguous' | 'source_conflict' | 'not_covered' | 'unavailable' required
timezone_end_status'resolved' | 'boundary_ambiguous' | 'source_conflict' | 'not_covered' | 'unavailable' required
timezone_artifact_versionstring nullable required
elevation_gain_mnumber nullable required
elevation_loss_mnumber nullable required
elevation_gain_ftnumber nullable required
elevation_loss_ftnumber nullable required
elevation_start_mnumber nullable required
elevation_end_mnumber nullable required
elevation_start_ftnumber nullable required
elevation_end_ftnumber nullable required
metaobject required

Changes

No recorded changes to this operation across all 1 revision of this API.