RESTful APIs

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:

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 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)

  1. plannedETA is 2:20 p.m.
  2. Based on the vehicle’s GPS location, the service estimates the actual ETA is 2:30.
  3. An ETA alert is triggered and a notification is sent.
  4. The plannedETA is now 2:30.
  5. 15 minutes later, the service checks the estimated ETA again. It’s now 2:40, versus the plannedETA of 2:30.
  6. Another ETA alert 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 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,
        "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 Alert

A weather alert is triggered 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 alert. This check is run every 60 minutes, and any weather 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 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": 39441256,
            "lon": -87512693
          },
          "publishedOn": "08/30/2022 20:00:11 +00:00"
        }
      }
    }
  ]
}

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":"”06-01-2022T15":"09":"26+00":00”
            }
         }
      }
   ]
}

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"
         }
      }
   ]
}
Last updated October 6, 2023.
Contents