Truck Routing That Warns You Before the Bridge Does

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, where it isn’t, 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 exactly what Road511’s routing endpoint closes. We compute the route geometry, 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 — this is 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: it has 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 comes from our routing engine. 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. The catalogue:

Each warning’s properties are type-specific: a bridge_clearance reports the measured clearance_m, your truck_height_m, and the deficit_m; a weight_restriction reports the violated dimension; a rail_crossing reports why it’s flagged. 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 is flagged, 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 returning 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 in the response. Refetch it with GET /api/v1/routing/route/saved/{id} any time inside that window and the warnings are re-evaluated against current conditions — a new closure that popped up since you planned the trip 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 having to poll.

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; when you need more, FIFO top-up packs add calls on top. Refetching a saved route, as noted above, is free.

Why This Is Different

The distinction is simple. 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 route geometry, plus a corridor scan against the live 511 data that flow APIs were never built to read.

Try It

• API docs — full request and response reference for POST /api/v1/routing/route
• Free API key — no credit card, 14-day trial
• Live map — see the underlying 511 data on a map