Truck Routing That Warns You Before the Bridge Does

#api #trucking #go #webdev

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"]
    }
  }'

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"
}

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.