Skip to main content

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 support@trimblemaps.com 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 riskSummary object provides a high-level overview of how weather is expected to impact the entire route.
  • The weatherImpact object 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 single weatherImpact.
  • The weatherGrids object 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.
  • None
  • Low - Road conditions due to weather pose a low impact to drivers.
  • Moderate - Road conditions due to weather pose a moderate impact to drivers. Weather-related accidents are possible. Drive with caution.
  • High - Road conditions due to weather pose a high impact to drivers. Weather-related accidents are likely. Some roadways could be impassable.
  • Extreme - Road conditions due to weather pose an extreme impact to drivers. Weather-related accidents are inevitable, although driving at all may be impossible. Widespread road closures are expected.
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.
  • None = 0
  • Low = 1-3
  • Moderate = 4-6
  • High = 7, 8
  • Extreme = 9, 10
5.0
maxCrashRisk
enum
The highest recorded risk of having an accident along the entire route: None, Low, Moderate, High, Extreme High
maxCrashIndex
string
The highest value of recorded accident risk along the entire route. It is directly correlated with maxCrashRisk.
  • None = 0
  • Low = 1-3
  • Moderate = 4-6
  • High = 7, 8
  • Extreme = 9, 10
5
maxDisruptionRisk
string
The highest recorded impact to infrastructure disruption along the route: None, Low, Moderate, High, Extreme Moderate
maxDisruptionIndex
string
The disruptions weather has or could have on the infrastructure of a location such as utilities, structures, and roadways. It is directly correlated with maxDisruptionRisk.
  • None = 0
  • Low = 1-3
  • Moderate = 4-6
  • High = 7, 8
  • Extreme = 9, 10
5.8
maxTippingIndex
number
The highest recorded risk of a truck tipover due to wind along the route. On a scale of 0-10. 7.8
minVisibility
number
Minimum visibility distance in miles along the entire route. 10.0
maxTemperature
number
Maximum temperature in degrees Fahrenheit along the entire route. 95
minTemperature
number
Minimum temperature in degrees Fahrenheit along the entire route. 32

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.
  • None = 0
  • Low = 1-3
  • Moderate = 4-6
  • High = 7, 8
  • Extreme = 9, 10
5.8
impactRouteLine
linestring
The full route linestring that passes through the alert. “LINESTRING (-85.376698 40.9453887663768, -85.37472166625525 40.95003)”
impactMaxCrashRisk
string
The crash risk due to a weather impact event: Low, Moderate, High, and Extreme. Moderate
impactMaxDisruptionRisk
string
The disruption to infrastructure risk due to a weather impact event: Low, Moderate, High, and Extreme. High
impactStartPoint
string
The starting point of the area in the route impacted by weather. 76.393938 115.22002
impactEndPoint
string
The ending point of the area in the route impacted by weather. 76.393938 115.22002
impactLength
number
The length in miles of a weather-impacted area that the route passes through. 15.6
custMsgId
string
The custom message ID for this weather impact area. 1232
impactSummary
array
The types of weather events for this weather impact area. Rain, Snow, FreezingRain, Wind, Visibility, ExtremeWeather
impactMaxTippingIndex
number
The highest recorded risk of a truck tipover due to wind on a scale of 0-10. 7.8
impactMaxWindGust
number
The max predicted gusts of wind along an impact area in MPH. 14.5
impactMaxWindSpeed
number
The max predicted sustained wind along an impact area in MPH. 10.2
impactMaxPrecipitation
number
The predicted precipitation along an impact area in inches. 2.2
impactMaxRainAccumulation
number
The max predicted rain accumulation along an impact area in inches. 2.2
impactMaxSnowAccumulation
number
The max predicted snow accumulation along an impact area in inches. 0
impactMaxFreezingRainAccumulation
number
The max predicted freezing rain accumulation along an impacted area in inches. 1.0
impactMaxRainfall
number
The rainfall in inches expected in the hour that the route passes through an impact area. 5.5
impactMaxSnowFall
number
The snowfall in inches expected in the hour that the route passes through an impact area. 1.2
impactMinVisibility
number
The minimum visibility in the impact area in miles. 0.124274194
impactMaxHeatIndex
number
The maximum heat index (“feels like” temperate) in the impact area in degrees Fahrenheit. 32.4472
impactMaxTemperature
number
The maximum temperature in the impact area in degrees Fahrenheit. 34.5979
impactMinTemperature
number
The minimum temperature in the impact area in degrees Fahrenheit. 22.5979
impactMaxFloodIndex
integer
Index on a 0-10 scale for how much risk of flooding there is in a weather-impact area. 7

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.
  • None = 0
  • Low = 1-3
  • Moderate = 4-6
  • High = 7, 8
  • Extreme = 9, 10
5.8
crashRisk
string
The crash risk due to the grid weather event: Low, Moderate, High, and Extreme. Moderate
crashIndex
number
The index value of the crash risk.
  • None = 0
  • Low = 1-3
  • Moderate = 4-6
  • High = 7, 8
  • Extreme = 9, 10
4.0
disruptionRisk
string
The disruption to infrastructure risk due to the grid weather event: Low, Moderate, High, and Extreme. High
disruptionIndex
number
The index value of the disruption to infrastructure risk.
  • None = 0
  • Low = 1-3
  • Moderate = 4-6
  • High = 7, 8
  • Extreme = 9, 10
3.9
floodIndex
integer
Index on a 0-10 scale for how much risk of flooding there is in an impacted area. 7
tippingIndex
number
The highest recorded risk of a truck tipover due to wind along the route on a scale of 0-10. 7.8
speedReduction
number
Speed reduction percentage per grid. 0 (17 percent)
windGust
number
Max predicted gusts of wind in MPH. 7.7734904
windSpeed
number
Max predicted sustained wind in MPH. 7.7734904
totalPrecipitation
number
The predicted precipitation in inches. 2.2
totalRainfall
number
The rainfall expected in the hour that the route passes through the grid. 0.4
totalSnowFall
number
The snowfall expected in the hour that the route passes through the grid. 1.2
rainAccumulation
number
The max predicted rain accumulation along an impact area in inches. 2.2
snowAccumulation
number
The max predicted snow accumulation along an impact area in inches. 2.5
freezingRainAccumulation
number
The max predicted freezing rain accumulation along an impacted area in inches. 1.0
visibility
number
The minimum visibility in the impact area in miles. 0.124274194
heatIndex
number
The maximum heat index (“feels like” temperate) in the impact area in degrees Fahrenheit. 32.4472

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
        }
    ]
Last updated January 30, 2024.
Contents