Skip to main content

⚡ Real-time nowcast

The current segment always carries live radar-derived lightning, thunderstorm, and precipitation data — not model estimates.

🔭 Forecast ahead

Upcoming segments are enriched with hourly NWP forecast weather so drivers can plan for conditions hours away.

🗺️ Smart segmentation

The route is split into Uber H3 hexagonal cells. Each cell gets its own ETA and independent weather query, keeping data fresh and spatially accurate.

What is the Enroute API?

The Enroute API turns a planned route into a live weather-monitoring session. You provide the route geometry, departure time, and duration — the API splits the path into geographic segments, attaches scheduled arrival times to each one, and returns weather data for every segment on every subsequent poll. Two endpoints drive the entire lifecycle:
All timestamps in requests and responses are epoch milliseconds (64-bit integers). Never send ISO strings or fractional seconds.

How segmentation works

When you register a route, the service decodes the route geometry (encoded polyline or coordinate list) and maps every point to an Uber H3 hexagonal cell at resolution 5. Consecutive points falling in the same cell are merged, yielding an ordered list of unique cells — the segments. Each segment receives:
  • eta — scheduled arrival time, interpolated from departureTime + (distanceToEntry / totalDistance) × durationSeconds
  • etd — scheduled departure time (same interpolation using distanceToExit)
  • distanceToEntry / distanceToExit — cumulative metres from route start
  • arrivalPoint / departurePoint — the geographic coordinates where the route enters and exits the cell
  • h3Address — the H3 cell identifier (used for weather queries)
H3 resolution 5 cells cover roughly 252 km² each, comparable to a medium-sized city district. A typical 90-minute highway route passes through 7–10 segments.
Why segment? Weather is spatially heterogeneous. Rain may be falling at your destination while skies are clear 80 km back. Segmentation lets the API query the right weather model cell for each portion of the journey and schedule those queries to the driver’s actual ETA — not all at once.

Nowcast vs Forecast

The response contains two structurally different weather payloads depending on the segment’s time horizon.

currentSegment — Nowcast + Forecast

The segment the driver is currently in (or the first segment, at registration time) receives nowcast data: real-time observations derived from live radar and sensor networks. This is the richest, most accurate weather picture available. Nowcast includes three dedicated summary objects: Why can upcoming segments not use nowcast? Each of the three nowcast services carries a different but complementary constraint:
  • Lightning: Sensor networks record only events that have already occurred. They produce no forward-looking output whatsoever. A lightning nowcast for a cell the driver will reach two hours from now is physically impossible.
  • Thunderstorm: Radar-based cell tracking observes the current position, speed, and direction of active storm cells. It generates no forecast projection; a meaningful threat assessment for a segment hours ahead cannot be derived from it.
  • Precipitation: Alongside live radar observations, a very short-range NWP projection may also be available; this is what feeds the expectedStartSec / expectedEndSec fields in precipitationSummary. However, this horizon only extends slightly beyond the current observation window and does not represent conditions for a segment hours ahead.
In short: the value of all three services lies in answering “right here, right now.” Once that question becomes meaningless for a future segment, multi-hour NWP forecast models take over.

upcomingSegments — Forecast only

All segments after the current one carry NWP (Numerical Weather Prediction) hourly forecast data: temperature, apparent temperature, humidity, cloud cover, wind speed/gust/direction, precipitation, precipitation probability, snowfall, and visibility.
At registration time, if departureTime is within 60 minutes of now, the current segment also fetches nowcast data. If the departure is further in the future, only forecast data is returned for the first segment as well.

Registering a route

Request

Either encodedPolyline (with polylinePrecision) or coordinates must be provided. Sending neither returns a 400 error.

Response

Save routeId from the registration response — it is the only key needed to poll the /weather endpoint throughout the journey. expirationTime tells you until when the session is valid; however, it is extended when segments are recalculated due to an off-schedule event (see Off-schedule).

Polling route weather

Request

Response

GetRouteWeatherResponse extends RouteRegistrationResponse and adds: All other fields (routeId, expirationTime, distanceUnit, status, currentSegment, upcomingSegments) are identical in structure to the registration response.

Response field reference

LocationStatus

expectedSegmentIndex reflects the route schedule, not GPS position. If the driver is in segment 2 but the schedule expected them to be in segment 3, this field shows 3. Compare it with currentSegment.index to detect schedule drift.

BaseRouteSegment (shared by currentSegment and upcomingSegments)

ForecastWeatherEvents (all segments)


Nowcast summary fields

The currentSegment.weatherEvents object contains three additional summary objects when nowcast data is available.

LightningSummary

Real-time lightning activity derived from ground-based electromagnetic sensors. What this means for a mobile app user: Show a lightning shield icon with the riskLevel colour. If riskLevel is HIGH or EXTREME, surface an urgent alert. Use nearestFlashDistance and lastFlashAgeSec to give context: “A flash was detected 3.2 km away 45 seconds ago — stay in your vehicle.”

ThunderstormSummary

Storm cell tracking derived from multi-layer radar analysis.

summary object

activeStorms[] — per-storm detail

What this means for a mobile app user: If insideAnyThreatBoundary is true, this is an immediate safety alert — the driver is inside a storm’s forecast impact zone. The approachState: APPROACHING flag combined with nearestThreatBoundaryDistance helps drivers decide whether to pull over or continue. Show the per-storm bearing so drivers understand which direction the storm is coming from.

PrecipitationSummary

Radar-derived precipitation analysis for the current H3 cell. What this means for a mobile app user: Surface currentIntensity as a weather badge. Use expectedStartSec to give advance warning — “Heavy rain expected in 8 minutes” — so drivers can prepare (wipers, speed reduction). HEAVY or above warrants a proactive push notification.

Off-route and off-schedule

Off-route

The /weather endpoint checks whether the driver’s currentLocation is within 1,000 metres of any segment of the registered route (perpendicular distance). If the driver has deviated beyond this threshold:
  • The route session is immediately deleted from cache.
  • A 400 Bad Request is returned with error: "Off Route".
  • The routeId is no longer valid.
  • The client must call /register again with a new route.
UX guidance: Listen for HTTP 400 with error: "Off Route". Show the user a dialog: “You have left the route. Please start navigation on your new route to continue weather monitoring.” Do not retry /weather with the same routeId.

Off-schedule

If the driver’s GPS position is significantly behind the expected schedule — specifically, if now is more than 10 minutes past the scheduled ETA of the segment after the driver’s current segment — the service silently recalculates the remaining route segments from the driver’s current position. When recalculation occurs:
  • segmentsRecalculated: true is set in the response.
  • warning contains a human-readable explanation.
  • Segment indices, ETAs, and distances are reset from the driver’s current position.
  • currentSegment reflects the new segment 0 starting from where the driver is now.
  • The expirationTime is extended to new ETA + 2 hours.
When segmentsRecalculated is true, discard any cached segment data from previous responses and re-render the full segment list from the new response.

Error reference

Duplicate Route (409)

Expired or Not Found (400)

Data Provider Error (500)

Returned when any of the underlying weather data services (lightning, thunderstorm, precipitation, or forecast) is unreachable. The message field identifies which source and service failed so you can log it and present a user-friendly fallback.

Developer notes

Every Instant-typed field in the API serializes as a 64-bit integer epoch millisecond — routeId, expirationTime, eta, etd, estimatedArrivalTime. Never parse these as seconds. Multiply by 1 and interpret directly as Date(value) in JavaScript or Instant.ofEpochMilli(value) in Java.
The API enforces deduplication on (userId, originH3, destinationH3). If the driver tries to register the same route while an active session exists, a 409 Conflict is returned with the existing routeId and expirationTime in the messages array. Parse the messages array to extract the existing routeId and resume polling rather than treating the 409 as a fatal error.
Sessions expire at ETA + 2 hours. After expiration, calls to /weather with the old routeId return 400. Poll /weather before expirationTime to detect expiry proactively without waiting for an error.
There is no server-side push; all updates require a client-initiated /weather poll. Recommended polling interval: every 30–60 seconds while the vehicle is moving. Reduce to every 5 minutes when stationary (e.g. at a traffic stop).
When segmentsRecalculated: true, the segment list has been rebuilt from the driver’s current position. Segment index values restart from 0. Any UI element that cached previous segment indices (progress bars, segment list scrolling) must be re-initialized using the new response.
The distanceUnit field in the response is always "m". All distanceToEntry, distanceToExit, and remainingDistance values are in metres. Convert to km or miles in your UI layer.

Testing with Postman

The Postman visualization script below renders a human-readable route summary directly in the Visualize tab after each /register or /weather request — no need to read raw JSON to understand the current route state. How to use:
  1. Open the request in Postman (POST /v1/enroute/register or POST /v1/enroute/weather).
  2. Go to ScriptsPost-response and paste the script below.
  3. Send the request, then switch to the Visualize tab to see the summary.