Weather Notifications
Contents
(Available in North America only)
The Weather Notifications service can help you plan ahead to avoid potential delays and hazardous road conditions, and warn drivers when they are approaching bad weather. The service looks ahead along the planned route, and it uses predictive, hyperlocal weather data to issue alerts if the driver is expected to encounter inclement weather.
The alerts are automatically returned via a WebSocket connection:
- For an entire route, at the time a route is calculated. The alerts are based on the predicted weather conditions at the time the driver is expected to reach that point in the route. Alerts provide the time the driver will reach the location of that weather event.
- As the driver progresses along the route. The weather service checks for alerts with every GPS ping received from a vehicle on its route. If the weather changes or expires at a certain location, then the alert is re-sent with the published state as
expired, and a new alert is issued.
The service, which uses weather data from WeatherOptics, is available as a premium add-on feature.
Trimble Transportation Management System (TMS) and CoPilot navigation customers may be able to receive hyperlocal weather notifications through existing “out of the box” solutions, without needing to follow the integration steps below. Contact us or reach out to your Trimble account rep to learn more.
Setting up weather notifications
Weather alerts are received via push notifications. In order to connect, the integration should use a WebSocket client. Registration requires the following URL to establish the connection:
https://notifications.trimblemaps.com/register?apikey={yourAPIkeyHERE}
Use MethodName = notificationMessage
If the connection succeeds, you will receive the response: “Connected to notifications.trimblemaps.com/register”
If the connection fails, please contact us at to verify your API key.
To Disconnect
Notifications will keep coming until you disconnect from WebSocket via the Websocket.close() method.
(These methods might vary slightly depending on the coding language.)
WebSocket client example
C# WebSocket
NuGet package needed: "Microsoft.AspNetCore.SignalR.Client" Version="6.0.5"
C# Sample Code
var connection = new HubConnectionBuilder()
.WithUrl("https://notifications.trimblemaps.com/register?apikey={Your API Key here}")
.WithAutomaticReconnect(new [] {TimeSpan.FromSeconds(5)})
.Build();
connection.On<dynamic>("notificationMessage", (message) =>
{
try
{
Console.WriteLine($"message: {message}");
}
catch (Exception ex)
{
Console.WriteLine($"Exception: {ex}");
} });
try
{
await connection.StartAsync();
Console.WriteLine("Connection started");
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
await Task.Delay(new Random().Next(0, 5) * 100000);
await connection.StartAsync();
}
Console.ReadLine();
Sample response
{
"type":1,
"target":"weatherV2",
"arguments":[
{
"properties":{
"tripId":"195062805",
"tmsTripId": "1234567",
"publishedOn":"2023-12-05T17:03:10+00:00",
"tripStatus":"InProgress",
"tspDriverId":"test",
"notificationType":"weatherV2",
"weatherNotificationId":"f3f3e1da-c764-443d-89e8-96175d2f798f",
"slowdownSummary":5.29,
"distanceUOM":"Miles",
"temperatureUOM":"Fahrenheit",
"precipitationUOM":"Inches",
"weatherSummary":[
"Visibility",
"Rain",
"Snow"
],
"riskSummary":{
"maxRoadRisk":"Moderate",
"maxRoadIndex":5.7,
"maxCrashRisk":"Low",
"maxCrashIndex":4.0,
"maxDisruptionRisk":"Low",
"maxDisruptionIndex":3.5,
"maxTippingIndex":0.0,
"minVisibility":0.124274194,
"maxTemperature":38.454407,
"minTemperature":33.810394
},
"weatherImpact":[
{
"lineColor":"yellow",
"roadRisk":"Moderate",
"maxRoadIndex":5.7,
"impactMaxCrashRisk":"Low",
"impactMaxDisruptionRisk":"Low",
"impactStartPoint":"-85.39083889298561 40.923016",
"impactEndPoint":"-85.305424 40.96036780709054",
"impactLength":6.253464836753678,
"custMsgId":null,
"impactSummary":[
"Snow",
"Visibility"
],
"impactMaxTippingIndex":0.0,
"impactMaxFloodIndex":1.0,
"impactMaxWindGust":7.7734904,
"impactMaxWindSpeed":3.8569693111334655,
"impactMaxPrecipitation":0.0,
"impactMaxRainfall":0.016405523,
"impactMaxSnowFall":0.0,
"impactMaxRainAccumulation":0.04585042,
"impactMaxSnowAccumulation":0.0,
"impactMaxFreezingRainAccumulation":0.0,
"impactMinVisibility":0.124274194,
"impactMaxHeatIndex":32.44359000000001,
"impactMaxTemperature":34.5979,
"impactMinTemperature":34.0354,
"publishedOn": "2023-11-24T17:53:58Z",
"weatherAlerts":[
],
"weatherGrids":[
{
"publishStateEnum":"New",
"publishState":"New",
"weatherGrid":{
"routeLine":"LINESTRING (-85.39083889298561 40.923016, -85.385627 40.929891, -85.383363 40.932923, -85.38202 40.934953, -85.378638 40.941179, -85.37697 40.94475, -85.37672 40.94533710144926)",
"geometry":null,
"weatherGridId":46761895,
"distanceToEvent":41.528592565196284,
"lastUpdateTime":"2023-12-05T15:00:00+00:00",
"estimatedImpactTime":"2023-12-05T17:53:01.0586646+00:00",
"roadRisk":null,
"roadIndex":5.7,
"crashRisk":"Low",
"crashIndex":4.0,
"disruptionRisk":"Low",
"disruptionIndex":3.9,
"floodIndex":1.0,
"tippingIndex":0.0,
"speedReduction":0.17,
"windGust":7.7734904,
"windSpeed":3.8569693111334655,
"totalPrecipitation":0.0,
"totalRainfall":0.013098433,
"totalSnowFall":0.10669297,
"rainAccumulation":0.028633877000000002,
"snowAccumulation":1.0926777201470947,
"freezingRainAccumulation":0.0,
"visibility":0.124274194,
"temperature":34.14792,
"heatIndex":31.962712
},
"startPoint":null,
"endPoint":null
},
{
"publishStateEnum":"New",
"publishState":"New",
"weatherGrid":{
"routeLine":"LINESTRING (-85.376698 40.9453887663768, -85.37472166625525 40.95003)",
"geometry":null,
"weatherGridId":46761896,
"distanceToEvent":43.2425721909033,
"lastUpdateTime":"2023-12-05T15:00:00+00:00",
"estimatedImpactTime":"2023-12-05T17:55:04.4651977+00:00",
"roadRisk":null,
"roadIndex":5.0,
"crashRisk":"Low",
"crashIndex":4.0,
"disruptionRisk":"Low",
"disruptionIndex":3.5,
"floodIndex":1.0,
"tippingIndex":0.0,
"speedReduction":0.14,
"windGust":7.354064,
"windSpeed":3.6781672202598212,
"totalPrecipitation":0.0,
"totalRainfall":0.016405523,
"totalSnowFall":0.10078746,
"rainAccumulation":0.04585042,
"snowAccumulation":0.9645673645272828,
"freezingRainAccumulation":0.0,
"visibility":0.18641129,
"temperature":34.5979,
"heatIndex":32.44359000000001
},
"startPoint":null,
"endPoint":null
},
{
"publishStateEnum":"New",
"publishState":"New"
}
],
"weatherAlertReferences":[
],
"custMsgRef":null
}
]
}
}
]
}
Notification fields
Overview
These are summary fields for the weather notification.
| Name | Type | Description | Sample Value |
|---|---|---|---|
weatherNotificationId
|
string | The unique identifier of a weather notification. | 07eb5b1d-f9ce-49de-bf8b-52b5fa5a714b |
tripId
|
string | The unique identifier for a Trimble Maps Trip Management trip. | 183009256 |
publishedOn
|
dateTime | The date/time that the notification was retrieved. | 2023-11-24T17:53:58Z |
slowdownSummary
|
number | The slowdown summary is the overall percentage that the travel speed is reduced due to a weather-related impact. Example: Route duration is 100 minutes with a slowdownSummary of 0.1. This means 10% of 100 minutes, which equates to 10 minutes of additional delay.
| Range from 0.0 to 1.0 to signify 0 to 100% |
distanceUOM
|
string | Units of measure for distance. | Default is Miles. |
precipitationUOM
|
string | Units of measure for precipitation. | Default is Inches. |
temperatureUOM
|
string | Units of measure for temperature. | Default is Fahrenheit. |
weatherSummary
|
array | The weather summary contains any type of weather events that are expect to occur on the route. The events are only listed if they are “True” meaning they are expect to occur. | Rain, Snow, FreezingRain, Wind, Visibility, ExtremeWeather |
custMsgRef
|
array | The custom message reference is an array of custom messages with an ID that can be used as a lookup for the custMsgId.
| 2345 |
Notification details
To provide hyperlocal weather information, the notifications service divides the U.S. into 3-kilometer-square grids. It retrieves predicted weather events, if any, for each grid that intersects with the planned route.
As a result, weather notifications include three JSON objects that provide increasing levels of granularity.
- The
riskSummaryobject provides a high-level overview of how weather is expected to impact the entire route. - The
weatherImpactobject provides the location and details of a weather event. If multiple contiguous grids that intersect the route include the same level of road risk (Low, Moderate, High, etc.), they are grouped together as a singleweatherImpact. - The
weatherGridsobject provides detailed information about each of the individual grids involved in a weather notification. It can be used to pinpoint the weather conditions at a specific location.
riskSummary
The Weather Risk Summary provides a high level overview of how weather is expected to impact the entire trip.
| Name | Type | Description | Sample Value | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
maxRoadRisk
|
string | The highest amount of road risk the driver is expected to encounter on the route.
| Moderate | ||||||||||||||||||||||||||||||||
maxRoadIndex
|
number | The highest value of road risk on the route based on a 0 to 10 scale of severity. It is directly correlated to maxRoadRisk.
|
weatherImpact
The Weather Impact provides the location and details of a weather event.
| Name | Type | Description | Sample Value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
lineColor
|
string | Color value based on the road risk: Green, Yellow, Red, Black | Yellow | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
impactRoadRisk
|
string | The amount of risk recorded in a weather impact event: None, Low, Moderate, High, Extreme | Low | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
impactMaxRoadIndex
|
number | The index value of a weather impact event.
|
weatherGrids
Hyperlocal weather is provided by monitoring 3-kilometer square grids across the U.S. The weatherGrids object provides detailed information about each of the individual grids involved in weather notifications. It can be used to pinpoint the weather conditions at a specific location.
| Name | Type | Description | Sample Value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
routeLine
|
linestring | The full route linestring that passes through the grid. | LINESTRING (-85.376698 40.9453887663768, -85.37472166625525 40.95003) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
weatherGridId
|
integer | The Weather Optics grid ID. | 23452 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
distanceToEvent
|
integer | Distance in miles to the start of a grid. | 23.4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lastUpdateTime
|
dateTime | The last time weather information for the grid was updated. | 2023-12-05T15:00:00+00:00 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
estimatedImpactTime
|
dateTime | Estimated time the driver or asset will intersect with the grid weather event. | 2023-12-05T17:53:01.0586646+00:00 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
roadRisk
|
string | The amount of risk recorded in the grid weather event: None, Low, Moderate, High, Extreme | Low | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
roadIndex
|
number | The index value of the grid weather event.
|
weatherAlerts issued by National Weather Service
Weather alerts are any alerts issued by the National Weather Service (NWS) that impact the route.
| Name | Type | Description | Sample Value |
|---|---|---|---|
id
|
string | The ID of the weather alert. | 600805f1-c94c-d70c-11c8-ddeec4fab0a0 |
routeLine
|
linestring | The full route linestring that passes through the alert. | “LINESTRING (-85.376698 40.9453887663768, -85.37472166625525 40.95003)” |
weatherAlertReferences
|
object | This object provides a full description of the NWS alert, identified by its id.
| See below |
"weatherAlertReferences": [
{
"id": "600805f1-c94c-d70c-11c8-ddeec4fab0a0",
"url": "https://alerts.weather.gov/example",
"alertEvent": "Flood Warning",
"title": "Flood Warning issued May 31 at 9:13PM CDT until June 04 at 3:34AM CDT by NWS",
"summary": "...FLOOD WARNING IN EFFECT UNTIL 915 AM CDT WEDNESDAY... * WHAT...Flooding caused by excessive rainfall is expected. * WHERE...A portion of South Central Kansas, including the following counties, Butler, Harvey, Kingman and Sedgwick. * WHEN...Until 915 AM CDT Wednesday. * RiskS...Flooding of rivers, creeks, streams, and other low-lying",
"urgency": "Expected",
"severity": "Moderate",
"certainty": "Likely",
"areaDesc": "Sedgwick",
"countryCode": "US",
"dispEffective": "2022-05-31T21:13:00-05:00",
"dispExpires": "2022-06-04T03:34:00-05:00",
"expired": true
}
]