Event Notifications

Contents

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), 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 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.

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.alk.com/api/v1/

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

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

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 #

{
  "weatherAlertInfo": {
    "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.alk.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 /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.alk.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.alk.com/trip-viewer/angular-site/#routeViewer/token/c8a8gu4bnnvkqjka8gmmqvqnkr63ivfyksf3xvtwre/details/30797922",
  "publishedOn": "2019-10-29T19:09:50+00:00"
}
Last updated March 17, 2021.