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

Response Fields

FieldDescriptionType
tripIdThe unique id issued by the service when the trip was created.
integer
outOfCorridorEventsAn object that contains all of the information about an Out-of-Corridor event.
etaEventsAn object that contains all of the information about an ETA event.
outOfRouteEventAn object that contains all of the information about an Out-of-Route event.
weatherEventsAn object that contains all of the information about a weather event.
eventIdThe unique id assigned to each event that occurred.
integer
coordsThe location at which the event occurred or the location of a stop.
coordinates object
publishedOnThe date and time of the alert.
date
oocDistanceThe distance the vehicle went out-of-corridor to generate that alert.
integer
oorDistanceThe total distance the vehicle went out-of-route for the trip.
integer
stopStatusThe status of the stop for which an ETA alert is issued. Options are Open, Arrived, Completed, and Canceled.
string
stopArrivalStatusThe type of ETA alert received. Alerts are issued for Late and TooEarly.
string
retreivedOnThe date and time the Trip Event call was received.
date
Location Object
FieldType
Address
address object
Coords
coordinates object
Coordinates Object
FieldType
Lat
string
Lon
string
Address Object
FieldType
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 July 14, 2020.