RESTful APIs

Event Notifications

Contents

(This API has been deprecated and replaced by the Notifications Service.)

The event notifications service delivers notifications generated by other Trip Management APIs in an easy-to-understand JSON format. The service can be used to get notifications when a vehicle goes Out of Route (OoR) or Out of Corridor (OoC), makes and unplanned stop, is at risk of missing an Estimated Arrival Time (ETA), or when a stop status changes in the trip. It can also retrieve weather events along a route.

These notifications include a URL so you can view the event location on a map.

Event notifications are all notifications associated with a particular account, based on that account’s API key. See the Trip Notifications API for details on how to retrieve notifications for a specific trip, based on its tripId.

Read about the differences between Trip Notifications and Event Notifications.

Getting Started

To use the event notification service, you must request access from your sales representative. You will be given an API key, and this key must be passed in the authorization header of every request to the notification service.

This is a polling service that must be called each time you want to retrieve notifications. It will return current notifications associated with your API key. Alerts expire after four days and are removed from your queue once they are retrieved.

The event notification service is available through the following URL:

https://notifications.trimblemaps.com/api/v1/{event type}

The event type endpoints are /outofcorridorevent, /outofrouteevent, /estimatedarrivalevent, /weatherevent, /stopevent, /trafficevent, and unplannedstopevent. (See details for each endpoint below.)

Sample Request

To use the service, you call the endpoint you want to poll and provide your API key.

Example 

curl --location --request GET 'https://notifications.trimblemaps.com/api/v1/outofcorridorevent' \
--header 'Authorization: {Your API Key}' \

Response Fields

These fields are shared by all Event Notifications endpoints. See below for sample responses for each type of event.

Field Description Type
outOfCorridorInfo An object that contains all of the information about an Out of Corridor event.
estimatedArrivalInfo An object that contains all of the information about the ETA event.
weatherInfo An object that contains all of the information about a weather event.
coords The location at which the event occurred or the location of a stop. 
coordinates object
publishedOn The date and time of the event. 
date
driverId The user-created identifier of the driver. 
string
vehicleId The user-created identifier of the vehicle. 
string
destination The trip’s destination. 
location object
origin The trip’s origin. 
location object
oocDistance The distance the vehicle went out-of-corridor to generate that event. 
integer
oorDistance The total distance the vehicle went out-of-route for the trip. 
integer
tripId The trip id issued by the service when the trip was created. 
integer
tripStatus The current status of the trip. For the initial response, the value will be Planned. As the trip gets executed/modified, the values may change to InProgress, Canceled, Completed, or Declined. 
string
stopStatus The status of the stop for which an ETA event is issued. Options are Open, Arrived, Completed and Canceled. 
string
stopArrivalStatus The type of ETA event. Events are issued for Late and TooEarly. 
string
notificationType The notification event type. Possible values are OutOfCorridor, OutOfRoute, EstimatedArrival, Weather, ArrivedStop and DepartedStop. 
string
status Used primarily in Out of Corridor Events to specify “Left Route” or “Rejoined Route” event 
string
url For ETA and weather events, this links to a web page showing the event on a map.
stopLocationInfo An object that contains details about an unplanned stop event. 
stopLocationInfo object
trafficIncidentInfo An object that contains all of the information about a traffic incident event, including IDs for the event and a short description. 
trafficIncidentInfo object
Location Object
Field Type
Address 
address object
Coords 
coordinates object
Coordinates Object
Field Type
Lat 
string
Lon 
string
DeviceDT 
string
Address Object
Field Type
StreetAddress 
string
City 
string
State 
string
Zip 
string
County 
string
StopLocationInfo object
Field Type
label 
string
latitude 
string
longitude 
string
trafficIncidentInfo object
Field Type
notificationType 
string
eventId 
string
incidentId 
string
shortDesc 
string

Endpoints

GET /outofcorridorevent

An Out of Corridor (OoC) event is generated when a driver deviates from the planned route beyond a mileage threshold. The threshold is set up at the account level when the API key is created, with a default of 1 mile. An OoC notification is issued each time a vehicle’s GPS position is detected to be beyond the mileage threshold.

Out of Corridor Event Sample Response 

{
  "outOfCorridorInfo": {
    "driverId": "",
    "vehicleId": "",
    "destination": {
      "Address": {
        "StreetAddress": "4900 Marie P Debartolo Way",
        "City": "Santa Clara",
        "State": "CA",
        "Zip": "95054",
        "County": "Santa Clara",
        "Country": "",
        "SPLC": null,
        "CountryPostalFilter": "US",
        "AbbreviationFormat": "FIPS",
        "StateName": null,
        "StateAbbreviation": null,
        "CountryAbbreviation": null
      },
      "Coords": {
        "Lat": "37.403072",
        "Lon": "-121.969608",
        "DeviceDT": "2017-09-19T19:19:19"
      },
      "Region": "NA",
      "Label": "Levi's Stadium",
      "PlaceName": "Levi's Stadium"
    },
    "origin": {
      "Address": {
        "StreetAddress": "4 Jersey Street",
        "City": "Boston",
        "State": "MA",
        "Zip": "02215",
        "County": "Suffolk",
        "Country": "",
        "SPLC": null,
        "CountryPostalFilter": "US",
        "AbbreviationFormat": "FIPS",
        "StateName": null,
        "StateAbbreviation": null,
        "CountryAbbreviation": null
      },
      "Coords": {
        "Lat": "42.346689",
        "Lon": "-71.09886"
      },
      "Region": "NA",
      "Label": "Fenway Park",
      "PlaceName": "Fenway Park"
    },
    "url": "https://tripmanagement.trimblemaps.com/trip-viewer/angular-site/#routeViewer/token/q5cwn5hzn7nbssx3ddhxe4z4qq3mhrheshb3wrrkkw/details/48745287?ooc=10539153",
    "tspVehicleId": "user@example.com",
    "eventId": 10539153,
    "coords": {
      "Lat": "42.335243",
      "Lon": "-73.311519"
    },
    "oocDistance": 50.08,
    "status": "Left Route",
    "publishedOn": "2020-11-24T13:53:46+00:00"
  },
  "tripId": "48745287",
  "tripStatus": "InProgress",
  "notificationType": "OutOfCorridor",
  "tmsUserId": ""
}

GET /outofrouteevent

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.

Out of Route Event Sample Response 

{
  "outOfRouteInfo": {
    "driverId": "fred",
    "vehicleId": "",
    "destination": {
      "Address": {
        "StreetAddress": "958 South Union Avenue",
        "City": "Los Angeles",
        "State": "CA",
        "Zip": "90015",
        "County": "Los Angeles",
        "Country": "United States",
        "SPLC": null,
        "CountryPostalFilter": "US",
        "AbbreviationFormat": "FIPS",
        "StateName": null,
        "StateAbbreviation": null,
        "CountryAbbreviation": null
      },
      "Coords": {
        "Lat": "34.049881",
        "Lon": "-118.273503"
      },
      "Region": "NA",
      "Label": "",
      "PlaceName": ""
    },
    "origin": {
      "Address": {
        "StreetAddress": "Gowanus Expressway  (I-278)",
        "City": "Brooklyn",
        "State": "NY",
        "Zip": "11228",
        "County": "Kings",
        "Country": "United States",
        "SPLC": null,
        "CountryPostalFilter": "US",
        "AbbreviationFormat": "FIPS",
        "StateName": null,
        "StateAbbreviation": null,
        "CountryAbbreviation": null
      },
      "Coords": {
        "Lat": "40.620047",
        "Lon": "-74.023084"
      },
      "Region": "NA",
      "Label": "",
      "PlaceName": ""
    },
    "url": "https://tripmanagement.trimblemaps.com/trip-viewer/angular-site/#routeViewer/token/isimntsgg4t4frwdcryekyyj8qxihs3yvgb7q6aw3p/details/4039704?oor=210413",
    "tspVehicleId": "1111111",
    "eventId": 210413,
    "oorDistance": 2158.64,
    "publishedOn": "2019-10-29T16:20:13+00:00"
  },
  "tripId": "4039704",
  "tripStatus": "Completed",
  "notificationType": "OutOfRoute",
  "tmsUserId": "joe_user"
}

GET /estimatedarrivalevent

An ETA event is generated when a vehicle is expected to miss an estimated arrival time window for a stop. The service checks the vehicle’s GPS position and issues any estimated arrival notifications at a time interval that is set up at the account level when the API key is created. An ETA notification will only be issued once per stop on a trip. The notification also includes a web link to view the alert on a map.

ETA Event Sample Response 

{
  "estimatedArrivalInfo": {
    "driverId": "",
    "vehicleId": "",
    "destination": {
      "Address": {
        "StreetAddress": "2000 E Gene Autry Way",
        "City": "Anaheim",
        "State": "CA",
        "Zip": "92806",
        "County": "Orange",
        "Country": "United States",
        "SPLC": null,
        "CountryPostalFilter": "US",
        "AbbreviationFormat": "FIPS",
        "StateName": null,
        "StateAbbreviation": null,
        "CountryAbbreviation": null
      },
      "Coords": {
        "Lat": "33.799925",
        "Lon": "-117.883194"
      },
      "Region": "NA",
      "Label": "Angel Stadium of Anaheim",
      "PlaceName": "Angel Stadium of Anaheim"
    },
    "origin": {
      "Address": {
        "StreetAddress": "24 Jersey Street",
        "City": "Boston",
        "State": "MA",
        "Zip": "02215",
        "County": "Suffolk",
        "Country": "United States",
        "SPLC": null,
        "CountryPostalFilter": "US",
        "AbbreviationFormat": "FIPS",
        "StateName": null,
        "StateAbbreviation": null,
        "CountryAbbreviation": null
      },
      "Coords": {
        "Lat": "42.346689",
        "Lon": "-71.09886"
      },
      "Region": "NA",
      "Label": "Fenway Park",
      "PlaceName": "Fenway Park"
    },
    "url": "https://tripmanagement.trimblemaps.com/trip-viewer/angular-site/#routeViewer/token/4cj76b4pte7ru58x374abtctv5mw5qej2pceni8bei/details/690117?eta=12496",
    "tspVehicleId": "11111",
    "eventId": 12496,
    "stopInfo": {
      "plannedETA": "2019-03-28T22:06:14-04:00",
      "currentETA": "2019-03-28T22:06:14-04:00",
      "earliestArrivalTime": "2017-09-19T16:45:00-04:00",
      "latestArrivalTime": "2017-09-19T18:00:00-04:00",
      "plannedDuration": 60,
      "actualDuration": 0,
      "plannedDepartureTime": "2019-03-28T23:06:13-04:00",
      "stopStatus": "Open",
      "stopArrivalStatus": "Late",
      "atRiskThreshold": 15,
      "tooEarlyThreshold": null,
      "legDistance": 4.961,
      "legDriveDuration": 15,
      "metadata": null,
      "amenities": null,
      "truckServices": false,
      "alternateRestStops": null,
      "poiId": 0,
      "setId": 0,
      "persistentId": 0,
      "activeDriver": 1,
      "Location": {
        "Address": {
          "StreetAddress": "24 Jersey Street",
          "City": "Boston",
          "State": "MA",
          "Zip": "02215",
          "County": "Suffolk",
          "Country": "United States",
          "SPLC": null,
          "CountryPostalFilter": "US",
          "AbbreviationFormat": "FIPS",
          "StateName": null,
          "StateAbbreviation": null,
          "CountryAbbreviation": null
        },
        "Coords": {
          "Lat": "42.346689",
          "Lon": "-71.09886"
        },
        "Region": "NA",
        "Label": "Fenway Park",
        "PlaceName": null
      },
      "Waypoint": false,
      "stopSequence": 0,
      "stopType": "Origin"
    },
    "publishedOn": "2019-03-29T01:51:01-04:00"
  },
  "tripId": "690117",
  "tripStatus": "Planned",
  "notificationType": "EstimatedArrival",
  "tmsUserId": ""
}

GET /weatherevent

(The legacy weather alert service described below has been deprecated and replaced by our premium predictive hyperlocal weather notifications service.)

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, and any weather event notifications are issued, at a time interval that is set up at the account level when the API key is created. The notification also includes a web link to view the event on a map.

Weather Event Sample Response 

{
  "weatherInfo": {
    "driverId": "",
    "vehicleId": "",
    "destination": {
      "Address": {
        "StreetAddress": "2000 E Gene Autry Way",
        "City": "Anaheim",
        "State": "CA",
        "Zip": "92806",
        "County": "Orange",
        "Country": "United States",
        "SPLC": null,
        "CountryPostalFilter": "US",
        "AbbreviationFormat": "FIPS",
        "StateName": null,
        "StateAbbreviation": null,
        "CountryAbbreviation": null
      },
      "Coords": {
        "Lat": "33.799925",
        "Lon": "-117.883194"
      },
      "Region": "NA",
      "Label": "Angel Stadium of Anaheim",
      "PlaceName": "Angel Stadium of Anaheim"
    },
    "origin": {
      "Address": {
        "StreetAddress": "Clovis Highway  (US-70)",
        "City": "Elida",
        "State": "NM",
        "Zip": "88116",
        "County": "Roosevelt",
        "Country": "United States",
        "SPLC": null,
        "CountryPostalFilter": "US",
        "AbbreviationFormat": "FIPS",
        "StateName": null,
        "StateAbbreviation": null,
        "CountryAbbreviation": null
      },
      "Coords": {
        "Lat": "33.743226",
        "Lon": "-103.961864"
      },
      "Region": "NA",
      "Label": "Rest Stop",
      "PlaceName": "Rest Stop"
    },
    "url": "https://tripmanagement.trimblemaps.com/trip-viewer/angular-site/#routeViewer/token/uxpdf25x7sb3v4w5vct2h7wrgmczi6abcsajrtqgxd/details/659955?weather=236",
    "tspVehicleId": "my_vehicle",
    "eventId": 236,
    "enterTime": "2019-02-19T12:46:08-05:00",
    "exitTime": "2019-02-19T13:27:08-05:00",
    "enterLocation": {
      "Address": {
        "StreetAddress": "276 Sky Ranch Road",
        "City": "Rodeo",
        "State": "NM",
        "Zip": "88056",
        "County": "Hidalgo",
        "Country": null,
        "SPLC": null,
        "CountryPostalFilter": "US",
        "AbbreviationFormat": "FIPS",
        "StateName": null,
        "StateAbbreviation": null,
        "CountryAbbreviation": null
      },
      "Coords": {
        "Lat": "31.790978",
        "Lon": "-109.049192"
      },
      "Region": "NA",
      "Label": null,
      "PlaceName": null
    },
    "weatherAlert": {
      "id": "https://alerts.weather.gov/cap/wwacapget.php?x=NM125CE6D6FC04.SpecialWeatherStatement.125CE6D80D10NM.EPZSPSEPZ.eeed05df6c1d8d99540d2de1d0dc5742",
      "dispUpdated": "2019-02-19T07:01:00-07:00",
      "dispPublished": "2019-02-19T07:01:00-07:00",
      "title": "Special Weather Statement issued February 19 at 7:01AM MST by NWS",
      "summary": "...A BRIEF SHOT OF WINTER WEATHER CONDITIONS EXPECTED ACROSS SOUTHERN NEW MEXICO AND FAR WEST TEXAS TODAY... A powerful Pacific storm system will pass over the Borderland region today, spreading isolated to scattered rain and snow showers across the area. Cold air is in place and snow levels are down to the desert floor elevations, meaning all areas that",
      "alertEvent": "Special Weather Statement",
      "dispEffective": "2019-02-19T07:01:00-07:00",
      "dispExpires": "2019-02-19T14:00:00-07:00",
      "status": "Actual",
      "category": "Met",
      "urgency": "Expected",
      "severity": "Minor",
      "certainty": "Observed",
      "areaDesc": "Central Tularosa Basin; East Slopes Sacramento Mountains Below 7500 Feet; Eastern Black Range Foothills; Lowlands of the Bootheel; Northern Dona Ana County; Otero Mesa; Sacramento Mountains Above 7500 Feet; Sierra County Lakes; Southern Dona Ana County, Mesilla Valley; Southern Gila Foothills, Mimbres Valley; Southern Gila Highlands, Black Range; Southern Tularosa Basin; Southwest Desert, Lower Gila River Valley; Southwest Desert, Mimbres Basin; Uplands of the Bootheel; Upper Gila River Valley; West Slopes Sacramento Mountains Below 7500 Feet",
      "countryCode": "US"
    },
    "publishedOn": "2019-02-19T16:44:16-05:00"
  },
  "tripId": "659955",
  "tripStatus": "InProgress",
  "notificationType": "Weather",
  "tmsUserId": ""
}

GET /trafficEvent

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 tripStatus changes to InProgress
  • When an ETA event is detected
  • When an arrival or departure is detected for any of the stops in a trip

Traffic Incident Event Sample Response 

{
  "tripId": 6879052,
  "driverId": "zach_januik@trimble.com",
  "notificationType": "TrafficIncident",
  "trafficIncidentInfo": {
    "eventId": 736113,
    "publishedOn": "2022-08-30T20:00:15+00:00",
    "incidentId": -2091161001,
    "shortDesc": "I-70: restrictions between Exit 21 and Exit 32",
    "address": {
      "StreetAddress": "Ramp",
      "City": "Dayton",
      "State": "OH",
      "Zip": "45414",
      "County": "Montgomery",
      "Country": "United States",
      "SPLC": null,
      "CountryPostalFilter": "US",
      "AbbreviationFormat": "FIPS",
      "StateName": null,
      "StateAbbreviation": null,
      "CountryAbbreviation": null
    },
    "coords": {
      "Lat": "39.86527",
      "Lon": "-84.222015"
    }
  }
}

GET /stopevent

A stop event notification is created whenever there is an update of a stop status to “Arrived” or “Departed” irrespective of whether the stop status change is automatic or manual. The notificationtype field in the notification will specify whether the status change was to “Arrived” or “Departed”. This feature is available to all licensed Trip Management users.

Arrived Stop Event Sample Response 

{
  "eventId": 143,
  "tripId": "123456",
  "tmstripId": "test_stop_status_worker",
  "notificationType": "ArrivedStop",
  "driverId": "Test123",
  "vehicleId": "",
  "destination": {
    "Address": {
      "StreetAddress": "3075 Collier Drive Northwest",
      "City": "Atlanta",
      "State": "GA",
      "Zip": "30318",
      "County": "Fulton",
      "Country": "United States",
      "SPLC": null,
      "CountryPostalFilter": "US",
      "AbbreviationFormat": "FIPS",
      "StateName": null,
      "StateAbbreviation": null,
      "CountryAbbreviation": null
    },
    "Coords": {
      "Lat": "33.767836",
      "Lon": "-84.490644"
    },
    "Region": "NA",
    "Label": "Atlanta",
    "PlaceName": "Atlanta"
  },
  "origin": {
    "Address": {
      "StreetAddress": "6351 Blue Lagoon Drive",
      "City": "Miami",
      "State": "FL",
      "Zip": "33126",
      "County": "Miami-Dade",
      "Country": "United States",
      "SPLC": null,
      "CountryPostalFilter": "US",
      "AbbreviationFormat": "FIPS",
      "StateName": null,
      "StateAbbreviation": null,
      "CountryAbbreviation": null
    },
    "Coords": {
      "Lat": "25.782545",
      "Lon": "-80.299498"
    },
    "Region": "NA",
    "Label": "Miami Beach",
    "PlaceName": "Miami Beach"
  },
  "stopLocationInfo": {
    "Address": {
      "StreetAddress": "6351 Blue Lagoon Drive",
      "City": "Miami",
      "State": "FL",
      "Zip": "33126",
      "County": "Miami-Dade",
      "Country": "United States",
      "SPLC": null,
      "CountryPostalFilter": "US",
      "AbbreviationFormat": "FIPS",
      "StateName": null,
      "StateAbbreviation": null,
      "CountryAbbreviation": null
    },
    "Coords": {
      "Lat": "25.782545",
      "Lon": "-80.299498"
    },
    "Region": "NA",
    "Label": "Miami Beach",
    "PlaceName": "Miami Beach"
  },
  "url": "https://tripmanagement.trimblemaps.com/trip-viewer/angular-site/#routeViewer/token/c8a8gu4bnnvkqjka8gmmqvqnkr63ivfyksf3xvtwre/details/30797922",
  "publishedOn": "2019-10-29T19:09:50+00:00"
}

Departed Stop Event Sample Response 

{
  "eventId": 144,
  "tripId": "123456",
  "tmstripId": "test_stop_status_worker",
  "notificationType": "DepartedStop",
  "driverId": "Test123",
  "vehicleId": "",
  "destination": {
    "Address": {
      "StreetAddress": "3075 Collier Drive Northwest",
      "City": "Atlanta",
      "State": "GA",
      "Zip": "30318",
      "County": "Fulton",
      "Country": "United States",
      "SPLC": null,
      "CountryPostalFilter": "US",
      "AbbreviationFormat": "FIPS",
      "StateName": null,
      "StateAbbreviation": null,
      "CountryAbbreviation": null
    },
    "Coords": {
      "Lat": "33.767836",
      "Lon": "-84.490644"
    },
    "Region": "NA",
    "Label": "Atlanta",
    "PlaceName": "Atlanta"
  },
  "origin": {
    "Address": {
      "StreetAddress": "6351 Blue Lagoon Drive",
      "City": "Miami",
      "State": "FL",
      "Zip": "33126",
      "County": "Miami-Dade",
      "Country": "United States",
      "SPLC": null,
      "CountryPostalFilter": "US",
      "AbbreviationFormat": "FIPS",
      "StateName": null,
      "StateAbbreviation": null,
      "CountryAbbreviation": null
    },
    "Coords": {
      "Lat": "25.782545",
      "Lon": "-80.299498"
    },
    "Region": "NA",
    "Label": "Miami Beach",
    "PlaceName": "Miami Beach"
  },
  "stopLocationInfo": {
    "Address": {
      "StreetAddress": "6351 Blue Lagoon Drive",
      "City": "Miami",
      "State": "FL",
      "Zip": "33126",
      "County": "Miami-Dade",
      "Country": "United States",
      "SPLC": null,
      "CountryPostalFilter": "US",
      "AbbreviationFormat": "FIPS",
      "StateName": null,
      "StateAbbreviation": null,
      "CountryAbbreviation": null
    },
    "Coords": {
      "Lat": "25.782545",
      "Lon": "-80.299498"
    },
    "Region": "NA",
    "Label": "Miami Beach",
    "PlaceName": "Miami Beach"
  },
  "url": "https://tripmanagement.trimblemaps.com/trip-viewer/angular-site/#routeViewer/token/c8a8gu4bnnvkqjka8gmmqvqnkr63ivfyksf3xvtwre/details/30797922",
  "publishedOn": "2019-10-29T19:09:50+00:00"
}

GET /unplannedstopevent

An unplanned stop event is generated when a driver stops in one location (no movement outside of a 0.5-mile geofence) for a configurable amount of time. The time threshold is set up at the account level when the API key is created, with a default of 30 minutes. (This notification must be enabled by Trimble Maps. Please contact your account representative.)

Unplanned Stop Event Sample Response 

{
  "eventId": 120720,
  "tripId": "6085899",
  "tmsTripId": null,
  "notificationType": "UnplannedStopEvent",
  "stopId": 0,
  "tspDriverId": "DV003",
  "stopLocationInfo": {
    "label": "unplanned stop - 11/23/2021 14:59:37 +00:00",
    "latitude": "47.042175",
    "longitude": "-104.114180"
  },
  "publishedOn": "2021-11-23T15:03:44.157+00:00"
}
Last updated October 22, 2024.
API Endpoint:
AWS Azure
Contents