RESTful APIs

Get Trip Notifications

Contents

The Get Trip Notifications service delivers notifications generated by a specific tripId in an easy-to-understand JSON format. The service can be used to get notifications when a vehicle goes Out of Route (OoR), Out of Corridor (OoC), is at risk of missing an Estimated Arrival Time (ETA) or when a stop status changes in the trip. It can also retrieve weather alerts (North America only) and traffic incident events along a route.

Getting Started

To use the Get Trip Notifications 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 the tripId passed. 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://tripmanagement.alk.com/api/trip/{tripId}/events

Read about the differences between Trip Notifications and Event Notifications.

Response Fields

Field Description Type
tripId The unique id issued by the service when the trip was created. 
integer
outOfCorridorEvents An object that contains all of the information about an Out-of-Corridor event.
etaEvents An object that contains all of the information about an ETA event.
outOfRouteEvent An object that contains all of the information about an Out-of-Route event.
weatherEvents An object that contains all of the information about a weather event.
stopStatusEvents An object that contains all of the information about Arrival and Departure events for a trip.
trafficIncidentEvents An object that contains all of the information about traffic incident events—construction, road closures, congestion or accidents—along the route.
eventId The unique id assigned to each event that occurred. 
integer
coords The location at which the event occurred or the location of a stop. 
coordinates object
publishedOn The date and time of the alert. 
date
oocDistance The distance the vehicle went out-of-corridor to generate that alert. 
integer
oorDistance The total distance the vehicle went out-of-route for the trip. 
integer
stopStatus The status of the stop for which an ETA alert is issued. Options are Open, Arrived, Completed, and Canceled. 
string
stopArrivalStatus The type of ETA alert received. Alerts are issued for Late and TooEarly. 
string
retreivedOn The date and time the Trip Event call was received. 
date
status Used primarily in Out of Corridor Events to specify “Left Route” or “Rejoined Route” event 
string

stopStatusEvents Object

Field Description Type
stopId The unique ID associated with that specific stop. 
integer
stopSequence The sequence of the stop in the associated trip. 
integer
notificationType The type of event delivered, either ArrivedAtStop or DepartedStop 
string
stopLocation Address and Coordinates of the stop event location

Location Object

Field Type
Address 
address object
Coords 
coordinates object

Coordinates Object

Field Type
Lat 
string
Lon 
string

Address Object

Field Type
StreetAddress 
string
City 
string
State 
string
Zip 
string
County 
string

Sample Response for ETA and Weather Notifications

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

{
  "tripId": 41852987,
  "outOfCorridorEvents": null,
  "etaEvents": [
    {
      "eventId": 12655766,
      "stopInfo": {
        "plannedETA": "2020-07-14T10:56:08-04:00",
        "currentETA": "2020-07-15T06:05:31-04:00",
        "earliestArrivalTime": null,
        "latestArrivalTime": null,
        "plannedDuration": 0.0,
        "actualDuration": 0.0,
        "stopStatus": "Open",
        "stopArrivalStatus": "Late",
        "atRiskThreshold": 0,
        "tooEarlyThreshold": 0,
        "legDistance": 1175.735,
        "legDriveDuration": 1149.517,
        "metadata": "",
        "amenities": null,
        "truckServices": false,
        "alternateRestStops": null,
        "poiId": 0,
        "setId": 0,
        "persistentId": 0,
        "activeDriver": 0,
        "stopId": 657746850,
        "location": {
          "address": {
            "streetAddress": null,
            "city": "Griffithville",
            "state": "AR",
            "zip": "72060",
            "county": "White",
            "country": null
          },
          "coords": {
            "lat": "35.14",
            "lon": "-91.52"
          },
          "label": "latlong from pcmws with weather alert event"
        },
        "stopSequence": 0,
        "stopType": "Work"
      },
      "publishedOn": "2020-07-14T14:56:32+00:00"
    }
  ],
  "outOfRouteEvent": null,
  "weatherEvents": [
    {
      "eventId": 10747035,
      "enterTime": "2020-07-14T14:56:21+00:00",
      "exitTime": "2020-07-14T14:56:21+00:00",
      "enterLocation": {
        "address": {
          "streetAddress": "",
          "city": "Griffithville",
          "state": "AR",
          "zip": "72060",
          "county": "White",
          "country": null
        },
        "coords": {
          "lat": "35.143667",
          "lon": "-91.517999"
        },
        "label": null
      },
      "weatherAlert": {
        "id": "https://alerts.weather.gov/cap/wwacapget.php?x=AR125F58620178.FloodWarning.125F587145ACAR.LZKFLSLZK.e27d543ba536c16e4fcb5f1bd1a3482e",
        "dispUpdated": null,
        "dispPublished": null,
        "title": null,
        "summary": null,
        "alertEvent": null,
        "dispEffective": null,
        "dispExpires": null,
        "status": null,
        "category": null,
        "urgency": null,
        "severity": null,
        "certainty": null,
        "areaDesc": null,
        "countryCode": null
      },
      "publishedOn": "2020-07-14T14:56:33+00:00"
    },
    {
      "eventId": 10747036,
      "enterTime": "2020-07-14T14:56:21+00:00",
      "exitTime": "2020-07-14T14:56:21+00:00",
      "enterLocation": {
        "address": {
          "streetAddress": "I-40, US-63",
          "city": "Wheatley",
          "state": "AR",
          "zip": "72392",
          "county": "St. Francis",
          "country": null
        },
        "coords": {
          "lat": "34.917824",
          "lon": "-91.152284"
        },
        "label": null
      },
      "weatherAlert": {
        "id": "https://alerts.weather.gov/cap/wwacapget.php?x=AR125F58638A70.HeatAdvisory.125F58713FD0AR.LZKNPWLZK.ffe3a68a6c4aa9e838deaaf6e110ea44",
        "dispUpdated": null,
        "dispPublished": null,
        "title": null,
        "summary": null,
        "alertEvent": null,
        "dispEffective": null,
        "dispExpires": null,
        "status": null,
        "category": null,
        "urgency": null,
        "severity": null,
        "certainty": null,
        "areaDesc": null,
        "countryCode": null
      },
      "publishedOn": "2020-07-14T14:56:33+00:00"
    }
  ],
  "retrievedOn": "2020-07-14T16:51:30+00:00"
}

Sample Response for OoR, OoC, and ETA Events 

{
  "tripId": 41852986,
  "outOfCorridorEvents": [
    {
      "eventId": 10405466,
      "coords": {
        "lat": "44.191268",
        "lon": "-117.094649"
      },
      "oocDistance": 643.42,
      "status": "Left Route",
      "publishedOn": "2020-07-14T14:55:09+00:00"
    }
  ],
  "etaEvents": [
    {
      "eventId": 12655764,
      "stopInfo": {
        "plannedETA": "2016-07-01T11:00:08-04:00",
        "currentETA": "2020-07-16T01:55:03-04:00",
        "earliestArrivalTime": null,
        "latestArrivalTime": null,
        "plannedDuration": 0.0,
        "actualDuration": 0.0,
        "stopStatus": "Open",
        "stopArrivalStatus": "Late",
        "atRiskThreshold": 0,
        "tooEarlyThreshold": 0,
        "legDistance": 2547.877,
        "legDriveDuration": 2340.05,
        "metadata": "",
        "amenities": null,
        "truckServices": false,
        "alternateRestStops": null,
        "poiId": 0,
        "setId": 0,
        "persistentId": 0,
        "activeDriver": 0,
        "stopId": 657746846,
        "location": {
          "address": {
            "streetAddress": "Gowanus Expressway  (I-278)",
            "city": "Brooklyn",
            "state": "NY",
            "zip": "11228",
            "county": "Kings",
            "country": null
          },
          "coords": {
            "lat": "40.620047",
            "lon": "-74.023084"
          },
          "label": ""
        },
        "stopSequence": 0,
        "stopType": "Origin"
      },
      "publishedOn": "2020-07-14T14:55:09+00:00"
    },
    {
      "eventId": 12655765,
      "stopInfo": {
        "plannedETA": "2016-07-03T03:38:17-07:00",
        "currentETA": "2020-07-15T22:50:10-07:00",
        "earliestArrivalTime": null,
        "latestArrivalTime": null,
        "plannedDuration": 0.0,
        "actualDuration": 0.0,
        "stopStatus": "Open",
        "stopArrivalStatus": "Late",
        "atRiskThreshold": 0,
        "tooEarlyThreshold": 0,
        "legDistance": 2436.391,
        "legDriveDuration": 2278.167,
        "metadata": "",
        "amenities": null,
        "truckServices": false,
        "alternateRestStops": null,
        "poiId": 0,
        "setId": 0,
        "persistentId": 0,
        "activeDriver": 0,
        "stopId": 657746847,
        "location": {
          "address": {
            "streetAddress": "958 South Union Avenue",
            "city": "Los Angeles",
            "state": "CA",
            "zip": "90015",
            "county": "Los Angeles",
            "country": null
          },
          "coords": {
            "lat": "34.049881",
            "lon": "-118.273503"
          },
          "label": ""
        },
        "stopSequence": 1,
        "stopType": "Destination"
      },
      "publishedOn": "2020-07-14T14:55:17+00:00"
    }
  ],
  "outOfRouteEvent": {
    "eventId": 10173703,
    "oorDistance": 3062.3,
    "publishedOn": "2020-07-14T14:55:39+00:00"
  },
  "weatherEvents": null,
  "retrievedOn": "2020-07-14T16:50:09+00:00"
}

Sample Response for Traffic Incident Events 

{
  "tripId": 6879052,
  "outOfCorridorEvents": null,
  "etaEvents": null,
  "outOfRouteEvent": null,
  "weatherEvents": null,
  "stopStatusEvents": null,
  "unplannedStopEvents": null,
  "trafficIncidentEvents": [
    {
      "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"
      }
    }
  ],
  "retrievedOn": "2022-08-30T20:11:48+00:00"
}

Sample Response for Stop Events 

{
   "tripId":51125796,
   "outOfCorridorEvents":null,
   "etaEvents":null,
   "outOfRouteEvent":null,
   "weatherEvents":null,
   "stopStatusEvents":[
      {
         "stopId":730766503,
         "stopSequence":4,
         "notificationType":"ArrivedAtStop",
         "tspDriverId":"",
         "stopLocation":{
            "address":{
               "streetAddress":"1401 Ripley Street",
               "city":"Lake Station",
               "state":"IN",
               "zip":"46405",
               "county":null,
               "country":"United States"
            },
            "coords":{
               "lat":"41.586429",
               "lon":"-87.238164"
            },
            "label":null
         },
         "publishedOn":"2021-01-13T16:40:27+00:00",
         "eventId":1463116
      },
      {
         "stopId":730766502,
         "stopSequence":3,
         "notificationType":"DepartedStop",
         "tspDriverId":"",
         "stopLocation":{
            "address":{
               "streetAddress":"106 Federal Street",
               "city":"Pittsburgh",
               "state":"PA",
               "zip":"15212",
               "county":"Allegheny",
               "country":"United States"
            },
            "coords":{
               "lat":"40.44797",
               "lon":"-80.003972"
            },
            "label":null
         },
         "publishedOn":"2021-01-13T16:40:26+00:00",
         "eventId":1463115
      },
      {
         "stopId":730766502,
         "stopSequence":3,
         "notificationType":"ArrivedAtStop",
         "tspDriverId":"",
         "stopLocation":{
            "address":{
               "streetAddress":"106 Federal Street",
               "city":"Pittsburgh",
               "state":"PA",
               "zip":"15212",
               "county":"Allegheny",
               "country":"United States"
            },
            "coords":{
               "lat":"40.44797",
               "lon":"-80.003972"
            },
            "label":null
         },
         "publishedOn":"2021-01-13T16:40:24+00:00",
         "eventId":1463114
      },
      {
         "stopId":730766501,
         "stopSequence":2,
         "notificationType":"DepartedStop",
         "tspDriverId":"",
         "stopLocation":{
            "address":{
               "streetAddress":"116 Federal Street",
               "city":"Pittsburgh",
               "state":"PA",
               "zip":"15212",
               "county":"Allegheny",
               "country":null
            },
            "coords":{
               "lat":"40.44797",
               "lon":"-80.003972"
            },
            "label":null
         },
         "publishedOn":"2021-01-13T16:40:18+00:00",
         "eventId":1463113
      },

   "retrievedOn":"2021-01-13T16:41:32+00:00"
}
Last updated May 15, 2024.
API Endpoint:
AWS Azure
Contents