devLap

Truck Routing That Warns You Before the Bridge Does

go dev.to

A routing API will happily hand a truck the fastest line between two points. What it usually won't tell you is that the line runs under a 4.0 m overpass with a 4.2 m load on the trailer, crosses an at-grade rail line you're legally required to stop at with placarded hazmat, or threads a county road that's posted closed for construction this week.

Flow APIs — HERE, TomTom, INRIX — are excellent at speed: where traffic is moving, how long the trip takes. That's congestion data. It is not infrastructure data. The overpass height, the bridge weight rating, the truck-restricted segment, the rail crossing, the active work zone — those live in 57 different state and provincial 511 systems, and a flow API doesn't read them.

That gap is what Road511's routing endpoint closes. We take the route geometry from HERE, then enrich the corridor from our own live traffic database — the same normalized 511 data behind the rest of the API — and return the hazards as a structured warnings[] array scored against your truck's dimensions.

How It Works

One call to POST /api/v1/routing/route. You send an origin, a destination, and — required — a truck profile. The profile is what makes a clearance "critical" instead of trivia: a 4.2 m height flags the 4.0 m overpass; a 36-tonne gross weight flags the posted 30-tonne bridge; a hazmat flag turns public at-grade rail crossings into mandatory-stop warnings.

curl -X POST "https://api.road511.com/api/v1/routing/route" \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "origin":      { "lat": 47.6062, "lng": -122.3321 },
    "destination": { "lat": 47.6588, "lng": -117.4260 },
    "truck": {
      "profile":  "tractor",
      "weight_t": 36.0,
      "height_m": 4.2,
      "width_m":  2.6,
      "length_m": 21.0,
      "axles":    5,
      "hazmat":   true
    },
    "alternatives": 1,
    "avoid": ["tolls"],
    "enrichment": {
      "buffer_m": 100,
      "clearance_pad_m": 0.15,
      "min_severity": "warning",
      "include_features": ["truck_parking", "rest_areas"]
    }
  }'
Enter fullscreen mode Exit fullscreen mode

That's Seattle to Spokane for a 4.2 m, 36-tonne, placarded tractor-trailer. The truck object accepts profile (tractor, straight_truck, or van), weight_t, height_m, and optional width_m, length_m, axles, and hazmat. You can add waypoints, request up to 3 alternatives, and avoid any of tolls, ferries, or tunnels.

The Response

You get back a routes[] array. Each route carries a summary, a GeoJSON geometry (a LineString you can drop straight onto a map), and the part that matters — a warnings[] array. Every warning is positioned: a type, a severity (info, warning, or critical), a distance_along_route, a projected_arrival_time, its own geometry, and type-specific properties.

{"routes":[{"summary":{"distance_m":449300,"duration_s":16980,"has_tolls":false},"geometry":{"type":"LineString","coordinates":[[-122.3321,47.6062],[-120.5,47.4],[-117.4260,47.6588]]},"warnings":[{"type":"bridge_clearance","severity":"critical","distance_along_route":38200,"projected_arrival_time":"2026-05-29T15:12:00Z","geometry":{"type":"Point","coordinates":[-121.97,47.51]},"properties":{"name":"I-90 over Snoqualmie Pass on-ramp","clearance_m":4.11,"truck_height_m":4.2,"clearance_pad_m":0.15,"deficit_m":0.29}},{"type":"rail_crossing","severity":"critical","distance_along_route":201400,"projected_arrival_time":"2026-05-29T17:41:00Z","geometry":{"type":"Point","coordinates":[-119.85,47.20]},"properties":{"crossing_id":"BNSF-094821X","grade":"at_grade","public":true,"reason":"placarded_hazmat_mandatory_stop_49cfr39210"}},{"type":"traffic_event","severity":"warning","distance_along_route":372600,"projected_arrival_time":"2026-05-29T19:08:00Z","geometry":{"type":"Point","coordinates":[-118.20,47.45]},"properties":{"event_type":"construction","description":"US-2 EB right lane closed for paving","jurisdiction":"WA"}}],"features":[{"type":"truck_parking","distance_along_route":250100,"properties":{"name":"Ritzville Rest Area","spaces":28}}]}],"route_id":"rt_8f3c2a1b"}
Enter fullscreen mode Exit fullscreen mode

The route geometry is HERE's. Everything in warnings[] and features[] is Road511's enrichment of the corridor.

The Warning Types

A warning is only emitted when the corridor actually contains the hazard — and for the dimension-checked types, only when your profile would violate it.

Type What it flags
bridge_clearance Overpass clearance vs your height_m + clearance_pad_m. Critical — the one that ends loads.
truck_restriction A segment your profile is barred from. Critical, per violated dimension.
weight_restriction Posted or seasonal weight limit your gross weight exceeds. Critical.
rail_crossing Public at-grade crossing. Critical for placarded hazmat (49 CFR 392.10 mandatory stop); info for high-volume otherwise.
traffic_event Live incident, closure, or construction on the corridor.
future_construction Planned work zones the route passes through.
special_event Scheduled events affecting nearby roads.
weigh_station / inspection_station Scale houses and inspection sites along the route.
alert Jurisdiction-issued advisories on the corridor.
weather Conditions reported near the route.

Each warning's properties are type-specific: a bridge_clearance reports the measured clearance_m, your truck_height_m, and the deficit_m. The data is only as fresh as the underlying feed — clearances come from inventories that refresh on the order of days, while traffic_event warnings ride the live incident feed.

Tuning the Enrichment

The enrichment object controls how aggressively the corridor is scanned:

  • buffer_m — how far off the line to look, 10–1000 m (default 100).
  • clearance_pad_m — safety margin added to your height before a clearance flags, 0–1 m (default 0.15).
  • min_severity — drop everything below info, warning, or critical.
  • exclude_types — suppress warning types you don't care about.
  • skip_temporal_filter — include time-bounded items outside their active window.
  • max_distance_m — cap how far along the route enrichment runs.
  • include_features — opt into a separate features[] channel of truck_parking, truck_rest_areas, and rest_areas near the route.

Saved Routes, Re-Evaluation, and Monitoring

Every routing call is auto-saved for 30 minutes under the route_id. Refetch with GET /api/v1/routing/route/saved/{id} inside that window and the warnings are re-evaluated against current conditions — a closure that popped up since you planned shows up on the refetch. Refetches do not consume routing quota.

To keep a route past the 30-minute TTL, call POST /api/v1/routing/route/saved/{id}/persist. Persisted routes count against your plan's saved-route slots, and they can be put under webhook monitoring — so when a new critical warning lands on a route you've already dispatched, you get notified instead of polling.

Quota and Access

Routing is a paid-plan feature, featured most heavily on Pro+. The Free 14-day trial includes a small daily cap so you can try it. Quota is a monthly routing-call bucket; FIFO top-up packs add calls on top. Refetching a saved route is free.

Why This Is Different

HERE and TomTom sell you flow — how fast the road is moving. Road511 adds the infrastructure — what your specific truck physically and legally can't do on that road. The routing endpoint puts both in one response: a drivable HERE geometry, plus a corridor scan against the live 511 data that flow APIs were never built to read.

Try It

Source: dev.to

arrow_back Back to Tutorials