Event Notifications

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 alerts along a route.

Weather and ETA alerts also include a URL so you can view the event location on a map.

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

FieldDescriptionType
outOfCorridorInfoAn object that contains all of the information about an Out of Corridor event.
estimatedArrivalInfoAn object that contains all of the information about the ETA event.
weatherAlertInfoAn object that contains all of the information about a weather alert.
coordsThe location at which the event occurred or the location of a stop.coordinates object
publishedOnThe date and time of the alert.date
driverIdThe user-created identifier of the driver.string
vehicleIdThe user-created identifier of the vehicle.string
destinationThe trip’s destination.location object
originThe trip’s origin.location object
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
tripIdThe trip id issued by the service when the trip was created.integer
tripStatusThe 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
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. Alerts are issued for Late and TooEarly.string
notificationTypeThe notification event type. Possible values are OutOfCorridor, OutOfRoute, EstimatedArrival, Weather, ArrivedStop and DepartedStop.string
urlFor ETA and weather alerts, this links to a web page showing the event on a map.
Location Object
FieldType
Addressaddress object
Coordscoordinates object
Coordinates Object
FieldType
Latstring
Lonstring
Address Object
FieldType
StreetAddressstring
Citystring
Statestring
Zipstring
Countystring

Endpoints

GET /outofcorridor

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 Alert Sample Response

({
  "outOfCorridorInfo": {
    "coords": {
      "Lat": "41.476319",
      "Lon": "-74.416344"
    },
    "publishedOn": "2018-07-12T19:36:25.207Z",
    "driverId": "",
    "vehicleId": "123456",
    "destination": {
      "Address": {
        "StreetAddress": "4900 Marie P Debartolo Way",
        "City": "Santa Clara",
        "State": "CA",
        "Zip": "95054",
        "County": "Santa Clara"
      },
      "Coords": {
        "Lat": "37.404006",
        "Lon": "-121.968766"
      }
    },
    "origin": {
      "Address": {
        "StreetAddress": "24 Yawkey Way",
        "City": "Boston",
        "State": "MA",
        "Zip": "02215",
        "County": "Suffolk"
      },
      "Coords": {
        "Lat": "42.346689",
        "Lon": "-71.09886"
      }
    },
    "oocDistance": 3.09,
    "url": null,
    "status": "o"
  },
  "tripId": "285567",
  "tripStatus": "InProgress",
  "notificationType": "OutOfCorridor"
},
{
  "outOfCorridorInfo": {
    "coords": {
      "Lat": "41.476319",
      "Lon": "-74.305344"
    },
    "publishedOn": "2019-03-04T19:38:51.285Z",
    "driverId": "",
    "vehicleId": "123456",
    "destination": {
      "Address": {
        "StreetAddress": "4900 Marie P Debartolo Way",
        "City": "Santa Clara",
        "State": "CA",
        "Zip": "95054",
        "County": "Santa Clara"
      },
      "Coords": {
        "Lat": "37.404006",
        "Lon": "-121.968766"
      }
    },
    "origin": {
      "Address": {
        "StreetAddress": "24 Yawkey Way",
        "City": "Boston",
        "State": "MA",
        "Zip": "02215",
        "County": "Suffolk"
      },
      "Coords": {
        "Lat": "42.346689",
        "Lon": "-71.09886"
      }
    },
    "oocDistance": 0.042,
    "url": null,
    "status": "i"
  },
  "tripId": "285567",
  "tripStatus": "InProgress",
  "notificationType": "OutOfCorridor"
})

GET /outofroutemileage

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 Alert 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-qa.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 Alert 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 /weatheralert

A weather alert 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 alert 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 alert on a map.

Weather Alert 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 November 13, 2019.