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 all 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://tripinsight.alk.com/service.svc/trip/{tripId}/events

Response Fields

Field Description Type
tripId The unique id issued by the Trip Management service when the trip was created.
integer
outOfCorridorEvents An object that contains all of the information about an Out-of-Corridor event, which generated when a driver deviates from the planned route beyond a mileage threshold. The object includes the tripID, the location (lat/long) of the event, the date and time and the out of corridor distance.
etaEvents An object that contains all of the information about an ETA event, which is generated when a vehicle is expected to miss an estimated arrival time window for a stop. The object includes all stop/ETA information including location, planned ETA, arrival windows, duration and anything else set within the parameters. It also includes the “Too Early/Late” notification.
outOfRouteEvent An object that contains all of the information about an Out-of-Route event, which is generated when the total mileage of a trip marked as “Completed” differs from the originally planned mileage of the trip by a certain threshold. Out of route distance is the distance between planned trip distance and driven trip distance. It is provided in the distance units defined within the settings of the trip.
weatherEvents An object that contains all of the information about a weather event, which is generated when the service detects a planned trip is going to be impacted by weather. The object includes the start and end time when the route will cross the alert area as well as the type of alert and severity. (North America Only)
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 the alert was generated.
date
oocDistance The distance the vehicle went out-of-corridor (deviated from the calculated route) to generate that alert. A threshold for the minimum OOC distance can be set per account.
integer
oorDistance The difference in total distance between the planned and the driven route.
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. This is derived from the arrival time window and the threshold, both of which are set through parameters when planning the trip.
string
retreivedOn The date and time the Trip Event call was received.
date
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

Trip Events 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"
}

Trip Events 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"
}
Last updated September 14, 2020.