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 alerts and events during a trip:

ETA
Stop status
Out-of-corridor (OoC)
Out-of-route (OoR)
Traffic incidents
Approaching
Dwell Exceeded
Unplanned Stops

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 or webhook 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

WebSocket

In order to connect, the integration should use a WebSocket client. Registration requires the following URL to establish the connection:

wss://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.

Webhook

The notification system also supports webhooks, allowing seamless integration with your existing infrastructure. In order to connect using webhook functionality, provide your webhook URL with authentication credentials, and Trip Management will send real-time notifications directly to your specified endpoint.

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("wss://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();

Notification Fields

All notifications from the service adhere to a common wrapper structure. The specific event data is found within the arguments[0].properties object.

Field	Description	Type
type	Indicates the message type, typically 1 for an invocation message.	Integer
target	The name of the method being invoked, which identifies the type of notification (e.g., “notificationMessage”, “eta”).	String
arguments	An array containing the arguments for the target method. For notifications, this array typically contains a single object.	Array of Objects
[0].properties	Contains the actual notification data specific to the `target` type.	Object

ETA Alert

As GPS positions are received for a specific trip, the service is checking whether there is an impact against the current ETA. An ETA alert 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 earliestArrivalTime and latestArrivalTime for a stop.
If only a plannedETA for a stop is set when the trip is planned, an ETA notification is sent if the currentETA is later than the plannedETA.

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)

plannedETA is 2:20 p.m.
Based on the vehicle’s GPS location, the service estimates the actual ETA is 2:30.
An ETA alert is triggered and a notification is sent.
The plannedETA is now 2:30.
15 minutes later, the service checks the estimated ETA again. It’s now 2:40, versus the plannedETA of 2:30.
Another ETA alert is triggered and a notification is sent.

Example Notification

{
  "type": 1,
  "target": "eta",
  "arguments": [
    {
      "properties": {
        "tripId": 140859211,
        "tmsTripId": "123344558",
        "tripStatus": "InProgress",
        "tspDriverId": "Trimble_user@trimble.com",
        "notificationType": "eta",
        "estimatedArrivalInfo": {
          "stopInfo":{
              "plannedETA":"2024-10-03T17:38:53+00:00",
              "currentETA":"2024-10-03T17:37:08+00:00",
              "earliestArrivalTime":"2024-10-03T11:34:00+00:00",
              "latestArrivalTime":"2024-10-03T11:34:00+00:00",
              "stopId":1792575310,
              "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",
            "metadata": "12345678"
          },
          "publishedOn": "06/01/2022 15:09:27+00:00",
          "deviceDT": "2022-06-01T15:09:25+00:00"
        }
      }
    }
  ]
}

ETA Field Definitions

Field	Description	Type
tripId	The internal Trimble Maps Trip ID.	Integer
tmsTripId	The trip ID (Load ID or Order number) in the TMS system.	String
tripStatus	Current status of the trip (e.g., “InProgress”, “Completed”).	String
tspDriverId	The ID of the driver associated with the trip.	String
notificationType	Specific type of notification (e.g., “eta”).	String
Estimated Arrival Information (estimatedArrivalInfo)
Stop Information (stopInfo)
plannedETA	Planned estimated time of arrival (ISO 8601) for this stop.	String
currentETA	Current estimated time of arrival (ISO 8601) for this stop.	String
earliestArrivalTime	Earliest possible arrival time (ISO 8601) at this stop.	String
latestArrivalTime	Latest possible arrival time (ISO 8601) at this stop.	String
stopId	Unique identifier for the stop.	Integer
stopArrivalStatus	Status indicating if the stop arrival is “Early”, “OnTime”, or “Late”.	String
Location Details (location)
Address (address)
streetAddress	Street address of the stop.	String
city	City of the stop.	String
state	State of the stop.	String
zip	Zip code of the stop.	String
county	County of the stop.	String
country	Country of the stop.	String
Coordinates (coords)
lat	Latitude of the stop location.	String
lon	Longitude of the stop location.	String
label	Label for the stop location.	String
stopSequence	The sequence number of the stop in the trip.	Integer
stopType	Type of stop (e.g., “Work”, “Delivery”).	String
metadata	Additional metadata associated with the stop.	String
publishedOn	Timestamp (ISO 8601) when the ETA notification was published.	String
deviceDT	The device date and time (ISO 8601) when the ETA event was detected.	String

Stop Status Event

A stop status event is triggered 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,
        "tmsTripId": "12385857",
        "tripStatus": "InProgress",
        "tspDriverId": "fred",
        "notificationType": "stop_status_update",
        "stopStatusEvents": {
          "stopId": 1270093363,
          "stopSequence":0,
          "earliestArrivalTime":"10/03/2024 08:30:00 -04:00",
          "latestArrivalTime":"10/03/2024 08:30:00 -04:00",
          "eventType":"ArrivedAtStop",
          "updateSource":"Automatic",
          "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"
        }
      }
    }
  ]
}

Stop Status Field Definitions

Field	Description	Type
tripId	The internal Trimble Maps Trip ID.	Integer
tmsTripId	The trip ID (Load ID or Order number) in the TMS system.	String
stopId	The unique ID of the stop being updated.	Integer
stopSequence	The sequence number of the stop in the trip.	Integer
eventType	The type of stop event (e.g., “ArrivedAtStop”, “DepartedFromStop”).	String
deviceDT	The device date and time (ISO 8601) when the event occurred.	String
Stop Location Details (stopLocation)
Address (address)
streetAddress	Street address of the stop.	String
city	City of the stop.	String
state	State of the stop.	String
zip	Zip code of the stop.	String
country	Country of the stop.	String
Coordinates (coords)
lat	Latitude of the stop location.	String
lon	Longitude of the stop location.	String
publishedOn	Timestamp (ISO 8601) when the stop status update notification was published.	String

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 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"
        }
      }
    }
  ]
}

OoR Field Definitions

Field	Description	Type
tripId	The internal Trimble Maps Trip ID.	Integer
tripStatus	Current status of the trip (e.g., “Completed”).	String
notificationType	Specific type of notification (e.g., “OutOfRoute”).	String
Out of Route Information (outOfRouteInfo)
driverId	The ID of the driver associated with the out-of-route event.	String
oorDistance	The total distance in miles the vehicle traveled off of the planned route path	Number
publishedOn	Timestamp (ISO 8601) when the out-of-route event was published.	String

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 if you would like to change the mileage threshold.)

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"
        }
      }
    }
  ]
}

OoC Field Definitions

Field	Description	Type
tripId	The internal Trimble Maps Trip ID.	Integer
tripStatus	Current status of the trip (e.g., “InProgress”, “Completed”).	String
tspDriverId	The ID of the driver associated with the trip.	String
notificationType	Specific type of notification (e.g., “out_of_corridor”).	String
Out of Corridor Information (outOfCorridorInfo)
Coordinates (coords)
lat	Latitude of the out-of-corridor location.	String
lon	Longitude of the out-of-corridor location.	String
oocDistance	The distance the vehicle is out of the corridor in miles	Number
status	Status of the out-of-corridor event (e.g., “LeftRoute”, “EnteredRoute”).	String
publishedOn	Timestamp (ISO 8601) when the out-of-corridor event was published.	String
deviceDT	The device date and time (ISO 8601) when the out-of-corridor event was detected.	String

Traffic Incident Alert

A traffic incident alert is triggered 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. 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 tripStatus changes to InProgress
When an ETA alert 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": "39.441256",
            "lon": "-87.512693"
          },
          "publishedOn": "08/30/2022 20:00:11 +00:00"
        }
      }
    }
  ]
}

Traffic Incident Field Definitions

Field	Description	Type
tripId	The internal Trimble Maps Trip ID.	Integer
tripStatus	Current status of the trip (e.g., “Planned”, “InProgress”).	String
driverId	The ID of the driver associated with the trip.	String
notificationType	Specific type of notification (e.g., “traffic_incident_planned”).	String
Traffic Incident Information (trafficIncidentInfo)
incidentId	Unique identifier for the traffic incident.	Integer
shortDesc	A short description of the traffic incident.	String
Address (address)
streetAddress	Street address near the incident.	String
city	City where the incident is located.	String
state	State where the incident is located.	String
zip	Zip code where the incident is located.	String
county	County where the incident is located.	String
country	Country where the incident is located.	String
Coordinates (coords)
lat	Latitude of the incident location.	String
lon	Longitude of the incident location.	String
publishedOn	Timestamp (ISO 8601) when the traffic incident was published.	String

Approaching Alert

An approaching alert is triggered when an asset is within 15 minutes of the stop. This alert messages the back office that the asset is approaching a certain stop and it includes how many minutes the driver is away from arriving. The timing of the alert varies based on the first GPS ping received once the vehicle is within 15 minutes of the stop. The approaching notification is sent separately from an arrival notification.

Example Notification

{
   "type":1,
   "target":"approachingStop",
   "arguments":[
      {
         "properties":{
            "message":"Asset {tspDriverId} is approaching Stop {stopLabel} and is currently {xx} minutes away",
            "tripId":140859022,
            "tspDriverId":"fred",
            "notificationType":"approachingStop",
            "stopDetails":{
               "stopId":1270093363,
               "stopSequence":1,
               "stopArrivalStatus":"OnTime",
               "currentETA":"2022-06-01T15:00:00+00:00",
               "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"
               },
               "publishedDateTime":"06-01-2022T15:09:27+00:00",
               "deviceDateTime":"2022-06-01T15:09:26+00:00"
            }
         }
      }
   ]
}

Approaching Field Definitions

Field	Description	Type
message	A human-readable message about the approaching stop.	String
tripId	The internal Trimble Maps Trip ID.	Integer
tspDriverId	The ID of the driver associated with the trip.	String
notificationType	Specific type of notification (e.g., “approachingStop”).	String
Stop Details (stopDetails)
stopId	Unique identifier for the stop.	Integer
stopSequence	The sequence number of the stop in the trip.	Integer
stopArrivalStatus	Status indicating if the stop arrival is “Early”, “OnTime”, or “Late”.	String
currentETA	Current estimated time of arrival (ISO 8601) for this stop.	String
Stop Location Details (stopLocation)
Address (address)
streetAddress	Street address of the stop.	String
city	City of the stop.	String
state	State of the stop.	String
zip	Zip code of the stop.	String
county	County of the stop.	String
country	Country of the stop.	String
Coordinates (coords)
lat	Latitude of the stop location.	String
lon	Longitude of the stop location.	String
label	Label for the stop location.	String
publishedDateTime	Timestamp (ISO 8601) when the stop details were published.	String
deviceDateTime	The device date and time (ISO 8601) when the stop event was detected.	String

Dwell Exceeded Alert

A dwell exceeded alert is a mechanism to alert the back office based on the planned duration of a stop. If a stop dwell time is exceeded by more than 10 percent, based on the plannedDuration for the stop, an alert is triggered. For example, if your driver has a planned 60 minutes of dwell time, and they have been detained for more than 66 minutes, an alert will be triggered.

Example Notification

{
   "type":1,
   "target":"excessiveDwell",
   "arguments":[
      {
         "properties":{
            "message":"{tspDriverId} has exceeded the planned Dwell time for {stopLabel}",
            "tripId":140859211,
            "tspDriverId":"Trimble_user@trimble.com",
            "notificationType":"excessiveDwell",
            "stopDetails":{
               "plannedETA":"2022-06-01T12:03:33-04:00",
               "actualArrivalTime":"2022-06-01T12:13:33-04:00",
               "plannedDuration":30,
               "currentDuration":45,
               "stopId":1270094413,
               "stopArrivalStatus":"Late",
               "stopType":"Work",
               "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
            },
            "publishedOn":"06/01/2022 15:09:27+00:00",
            "deviceDT":"2022-06-01T15:09:25+00:00"
         }
      }
   ]
}

Dwell Field Definitions

Field	Description	Type
message	A human-readable message about the excessive dwell.	String
tripId	The internal Trimble Maps Trip ID.	Integer
tspDriverId	The ID of the driver associated with the trip.	String
notificationType	Specific type of notification (e.g., “excessiveDwell”).	String
Stop Details (stopDetails)
plannedETA	Planned estimated time of arrival (ISO 8601) for this stop.	String
actualArrivalTime	Actual arrival time (ISO 8601) at this stop.	String
plannedDuration	Planned duration of the stop in minutes.	Integer
currentDuration	Current duration of the dwell in minutes.	Integer
stopId	Unique identifier for the stop.	Integer
stopArrivalStatus	Status indicating if the stop arrival was “Early”, “OnTime”, or “Late”.	String
stopType	Type of stop (e.g., “Work”, “Delivery”).	String
Location Details (location)
Address (address)
streetAddress	Street address of the stop.	String
city	City of the stop.	String
state	State of the stop.	String
zip	Zip code of the stop.	String
county	County of the stop.	String
country	Country of the stop.	String
Coordinates (coords)
lat	Latitude of the stop location.	String
lon	Longitude of the stop location.	String
label	Label for the stop location.	String
stopSequence	The sequence number of the stop in the trip.	Integer
publishedOn	Timestamp (ISO 8601) when the dwell exceeded notification was published.	String
deviceDT	The device date and time (ISO 8601) when the dwell exceeded event was detected.	String

Unplanned Stops

An unplanned stop is a location an asset, driver or vehicle stops at that is not part of the planned stop list. An unplanned stop is based on GPS pings within the same or similar location (0.25 miles) for a configurable amount of time (30 minutes). (Configurations are set with your API key.)

The configuration for enabling unplanned stops has two features:

Alerts for unplanned stops (enable/disable)
Add unplanned stops to the trip (enable/disable)

When an unplanned stop is added to the trip, if it falls within one of the over 5 million Trimble Places, it will be geocoded and named with a stopType of unplannedStop and notificationType of unplanned_stop_update.

If it falls outside of a Trimble Place, the label will be Unplanned Stop. It may make sense to investigate this further as the driver could be broken down on the side of the road or off route.

Example Notification

{
    "type": 1,
    "target": "notificationMessage",
    "arguments": [
        {
            "properties": {
                "tripId": 9721566,
                "tmsTripId": "SO398483",
                "tripStatus": "InProgress",
                "tspDriverId": "fred",
                "tspDriverId2": null,
                "notificationType": "unplanned_stop_update",
                "unplannedStopInfo": {
                    "eventId": 9614,
                    "stopInfo": {
                        "coords": {
                            "lat": "38.232870",
                            "lon": "-80.239645"
                        },
                        "label": "Unplanned Stop",
                        "stopId": 92004285,
                        "stopSequence": 1
                    },
                    "publishedOn": "2024-11-21T16:08:47+00:00"
                }
            }
        }
    ]
}

Unplanned Stop Field Definitions

Field	Description	Type
tripId	The internal Trimble Maps Trip ID.	Integer
tmsTripId	The trip ID (Load ID or Order number) in the TMS system.	String
tripStatus	Current status of the trip (e.g., “InProgress”).	String
tspDriverId	The ID of the driver associated with the trip.	String
tspDriverId2	Optional second driver ID.	String
notificationType	Specific type of notification (e.g., “unplanned_stop_update”).	String
Unplanned Stop Information (unplannedStopInfo)
eventId	Unique identifier for the unplanned stop event.	Integer
Stop Information (stopInfo)
Coordinates (coords)
lat	Latitude of the unplanned stop location.	String
lon	Longitude of the unplanned stop location.	String
label	Label for the unplanned stop location.	String
stopId	Unique identifier for the unplanned stop.	Integer
stopSequence	The sequence number of the unplanned stop in the trip.	Integer
publishedOn	Timestamp (ISO 8601) when the unplanned stop event was published.	String

WEB SDK & APIs

INTERACTIVE MAPS

SOAP APIs (Web Services)

Legacy PC*Miler Libraries

RESTful APIs (Web Services)

MOBILE SDK & APIs

COPILOT NAVIGATION

INTERACTIVE MAPS

Notifications Service

Connecting to push notifications

WebSocket

Webhook

To Disconnect

WebSocket Client Examples

C# WebSocket

C# Sample Code

Notification Fields

ETA Alert

Example Notification

ETA Field Definitions

Stop Status Event

Example Notification

Stop Status Field Definitions

OoR Event

Example Notification

OoR Field Definitions

OoC Event

Example Notification

OoC Field Definitions

Traffic Incident Alert

Example Notification

Traffic Incident Field Definitions

Approaching Alert

Example Notification

Approaching Field Definitions

Dwell Exceeded Alert

Example Notification

Dwell Field Definitions

Unplanned Stops

Example Notification

Unplanned Stop Field Definitions