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 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/service.svc/trip/{tripId}/events

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.
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 #

{
  "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 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 March 29, 2021.