Notifications Service
Contents
Trip Management’s notifications service allows you to register your integration to receive real-time notifications as they become available for the following events during a trip:
The service replaces the legacy polling service , which required repeated API calls to pull new notifications.
Once an application that integrates with Trip Management registers and connects with the notifications service, that connection stays open until the integration disconnects it. Registration is done via API key, and notifications are delivered based on an account’s API key settings. You can register with any API key on the account and get all notifications for the accountID under which that API key exists.
This service relies on WebSocket to create a connection between the two systems. Notifications will be delivered in real-time and can be consumed, stored, processed or handled however the integration sees fit. (Separately, you can call the
Trip Notifications API
at any point during or after a trip to retrieve ALL notifications for an individual trip by its tripID.)
Connecting to 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 Examples
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();
ETA Event
As GPS positions are received for a specific trip, the service is checking whether there is an impact against the current ETA. An ETA notification is triggered when:
- The ETA of a stop is outside of its arrival time window. That time window is set when planning the trip by setting an
earliestArrivalTimeandlatestArrivalTimefor a stop. - If only a
plannedETAfor a stop is set when the trip is planned, an ETA notification is sent if thecurrentETAis later than theplannedETA.
The service checks the vehicle’s GPS position and issues any estimated arrival notifications at a time interval that is configured at the account level when the Trip Management API key is created. An ETA alert will be sent at a default maximum frequency of once every 5 minutes IF there was an ETA change. This is dependent on how often updated GPS pings are received.
You can contact Trimble Maps Support to change this threshold.
Example (with a 15-minute time interval)
plannedETAis 2:20 p.m.- Based on the vehicle’s GPS location, the service estimates the actual ETA is 2:30.
- An ETA event is triggered and a notification is sent.
- The
plannedETAis now 2:30. - 15 minutes later, the service checks the estimated ETA again. It’s now 2:40, versus the
plannedETAof 2:30. - Another ETA event is triggered and a notification is sent.
Example Notification
{
"type": 1,
"target": "eta",
"arguments": [
{
"properties": {
"tripId": 140859211,
"tripStatus": "InProgress",
"tspDriverId": "Trimble_user@trimble.com",
"notificationType": "eta",
"estimatedArrivalInfo": {
"stopInfo": {
"plannedETA": "2022-06-01T12:03:33-04:00",
"currentETA": "2022-06-01T12:22:02-04:00",
"earliestArrivalTime": "2022-06-01T11:30:00-04:00",
"latestArrivalTime": "2022-06-01T12:15:00-04:00",
"stopId": 1270094413,
"stopArrivalStatus": "Late",
"location": {
"address": {
"streetAddress": "762 Hylan Boulevard",
"city": "Staten Island",
"state": "NY",
"zip": "10305",
"county": "Richmond",
"country": null
},
"coords": {
"lat": "40.601683",
"lon": "-74.07256"
},
"label": "StopLabel"
},
"stopSequence": 4,
"stopType": "Work"
},
"publishedOn": "06/01/2022 15:09:27+00:00",
"deviceDT": "2022-06-01T15:09:25+00:00"
}
}
}
]
}
Stop Status Event
A stop event notification is created whenever there is an update of a stop status to “Arrived” or “Departed,” regardless of whether the stop status change is automatic or manual. The eventType field in the notification will specify whether the status change was to “Arrived” or “Departed”. Read more about arriving and departing a stop.
Example Notification
{
"type": 1,
"target": "stop_status_update",
"arguments": [
{
"properties": {
"tripId": 140859022,
"tripStatus": "InProgress",
"tspDriverId": "fred",
"notificationType": "stop_status_update",
"stopStatusEvents": {
"stopId": 1270093363,
"stopSequence": 1,
"eventType": "DepartedStop",
"stopLocation": {
"address": {
"streetAddress": "976 South Union Avenue",
"city": "Los Angeles",
"state": "CA",
"zip": "90015",
"county": "Los Angeles",
"country": "United States"
},
"coords": {
"lat": "34.049881",
"lon": "-118.273503"
},
"label": "StopLabel"
},
"publishedOn": "06-01-2022T15:09:27+00:00",
"deviceDT": "2022-06-01T15:09:25+00:00"
}
}
}
]
}
Weather Event
A weather event is generated when the service detects a planned trip is going to be impacted by weather. The service looks at all planned and active routes to see whether they intersect with a weather event. This check is run every 60 minutes, and any weather event notifications are issued.
Example Notification
{
"type": 1,
"target": "weather",
"arguments": [
{
"properties": {
"tripId": 140858769,
"tripStatus": "InProgress",
"tspDriverId": "Trimble_User@trimble.com",
"notificationType": "weather",
"weatherInfo": {
"enterTime": "2022-06-01T15:04:41+00:00",
"exitTime": "2022-06-01T15:45:35+00:00",
"enterLocation": {
"address": {
"streetAddress": "Kingman Road Northeast",
"city": "Nashville",
"state": "KS",
"zip": "67112",
"county": "Kingman",
"country": "United States"
},
"coords": {
"lat": "37.38",
"lon": "-98.46"
},
"label": null
},
"weatherAlert": {
"id": "https://alerts.weather.gov/cap/wwacapget.php?x=KS1263F9BDB374.FloodWarning.1263F9EC6CC8KS.ICTFLWICT.73f3167bd92c0295cc9d75692944123d",
"dispUpdated": "2022-05-31T21:13:00-05:00",
"dispPublished": "2022-05-31T21:13:00-05:00",
"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. * IMPACTS...Flooding of rivers, creeks, streams, and other low-lying",
"alertEvent": "Flood Warning",
"dispEffective": "2022-05-31T21:13:00-05:00",
"dispExpires": "2022-06-04T03:34:00-05:00",
"status": "Actual",
"category": "Met",
"urgency": "Expected",
"severity": "Moderate",
"certainty": "Likely",
"areaDesc": "Sedgwick",
"countryCode": "US"
},
"publishedOn": "06-01-2022T15:05:37+00:00"
}
}
}
]
}
OOR Event
An Out of Route (OoR) mileage event is generated when the total mileage of a trip marked as complete differs from the originally planned mileage of the trip by a certain threshold. The threshold is set up at the account level when the API key is created, with a default of 10 miles. An OoR notification is issued one time, at the end of the trip. (Please contact support@trimblemaps.com if you would like to change the OoR mileage threshold.)
Example Notification
{
"type": 1,
"target": "oor_event",
"Arguments": [
{
"properties": {
"tripId": "4039704",
"tripStatus": "Completed",
"notificationType": "OutOfRoute",
"outOfRouteInfo": {
"driverId": "Driver1",
"oorDistance": 2158.64,
"publishedOn": "2019-10-29T16:20:13+00:00"
}
}
}
]
}
OOC Event
An Out of Corridor (OoC) event is generated when a driver deviates from the planned route beyond a mileage threshold. The threshold can be set at the account level when the API key is created. The default value is 1 mile. An OoC notification is issued each time a vehicle’s GPS position is detected to be beyond the mileage threshold. (Please contact support@trimblemaps.com if you would like to change the mileage threshold.) oocDistanceThreshold
Example Notification
{
"type": 1,
"target": "out_of_corridor",
"arguments": [
{
"properties": {
"tripId": 140858769,
"tripStatus": "InProgress",
"tspDriverId": "aparna_venkata@trimble.com",
"notificationType": "out_of_corridor",
"outOfCorridorInfo": {
"coords": {
"lat": "37.57476",
"lon": "-98.3625"
},
"oocDistance": 211.38,
"status": "LeftRoute",
"publishedOn": null,
"deviceDT": "2022-06-01T15:40:41+00:00"
}
}
}
]
}
Traffic Incident Event
A traffic incident event is generated when the service detects that a trip is going to be impacted by traffic. The service looks at all planned and active routes to see whether they intersect with a traffic incident event. Traffic incidents include:
- Construction
- Road closures
- Congestion
- Accidents
The service checks for traffic incidents in the following scenarios:
- When the trip is planned
- Every 12 hours for all planned trips
- When the
tripStatuschanges toInProgress - When an ETA event is detected
- When an arrival or departure is detected for any of the stops in a trip
Example Notification
{
"type": 1,
"target": "traffic_incident_planned",
"arguments": [
{
"properties": {
"tripId": 6879052,
"tripStatus": "Planned",
"driverId": "zach_januik@trimble.com",
"notificationType": "traffic_incident_planned",
"trafficIncidentInfo": {
"incidentId": -2091160570,
"shortDesc": "I-70: paving repairs from I-70 Exits 11 / IN-46 to Exit 1 National Ave",
"address": {
"streetAddress": "I-70, US-40",
"city": "West Terre Haute",
"state": "IN",
"zip": null,
"county": "Vigo",
"country": "United States"
},
"coords": {
"lat": 39441256,
"lon": -87512693
},
"publishedOn": "08/30/2022 20:00:11 +00:00"
}
}
}
]
}