Notifications

Subscribers will get notifications about multiple events, they will be informed even about small deviations. If clients want to inform their customer only about a specific deviation time, clients must filter notifications and inform their users only about deviation of, e.g. more than 15 minutes late or 30 minutes too early.

{
  "notificationContentType": "ETA_INFO",                   // ETA_INFO, SUBSCRIPTION_CONFIRMATION, 
  "topicType": "ETA",
  "notificationPayLoad":[{
    "scheduledTime":"YYYY-MM-DDThh:mm:ss.0000000+01:00",   // user planned time for truck arrival
    "estimatedTime":"YYYY-MM-DDThh:mm:ss.0000000+01:00",   // expected time when truck will arrive,
    "relatedTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",    // time at which this ETA was calculated
    "uniqSeqId": "07210517-a3f8-4637-8b6d-aa7900b41238",
    "info": "PositionEvent",
    "trafficTimeLoss": 241,                                // total time lost due to traffic
    "breakAndRestPeriod": 870,                             // total break and rest period on road and at stop
    "waitingPeriod": 0,
    "scemid":"X9X9X9X9X9"                                  // SCEM-ID of concerned stop
  }],
  "subscriptionID": "9b2902977a7b455ca793aa7900b5544c"
}

Immediately after subscription to a tour SCEM-ID notifications will be sent of all stops that belong to the specified tour:

{
  "notificationContentType":"SUBSCRIPTION_CONFIRMATION",
  "topicType": "ETA",
  "notificationPayLoad":[{
    "scheduledTime":"YYYY-MM-DDThh:mm:ss.0000000+01:00",   // user planned time for truck arrival
    "estimatedTime":"YYYY-MM-DDThh:mm:ss.0000000+01:00",   // expected time when truck will arrive,
    "relatedTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
    "uniqSeqId": "07210517-a3f8-4637-8b6d-aa7900b41238",
    "info": "Confirmation",
    "trafficTimeLoss": 241,
    "breakAndRestPeriod": 870,
    "waitingPeriod": 0,
    "scemid": "X8X8X8X8X8"
  }, {
    "scheduledTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
    "estimatedTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
    "relatedTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
    "uniqSeqId": "07210517-a3f8-4637-8b6d-aa7900b41238",
    "info": "Confirmation",
    "trafficTimeLoss": 241,
    "breakAndRestPeriod": 1800,
    "waitingPeriod": 0,
    "scemid": "X9X9X9X9X9"
  }],
  "subscriptionID": "d2dac125bec94e248e80aa7900b8f91c"
}

The info field in the notificationPayload can contains useful information regarding how the ETA was calculated.

{
{
    "notificationContentType": "ETA_INFO",
    "notificationPayLoad": [{
            ...
            "info": "PositionEvent - (traffic information excluded due to inaccessible route sections)",
        }
    ],
    "subscriptionID": "9b2902977a7b455ca793aa7900b5544c",
    "topicType": "ETA"
}
		

Subscription to stops will be notified as following:

{
  "notificationContentType":"ETA_INFO",
  "topicType": "ETA",
  "notificationPayLoad":[{
    "scheduledTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
    "estimatedTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
    "relatedTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
    "uniqSeqId": "07210517-a3f8-4637-8b6d-aa7900b41238",
    "info": "Confirmation",
    "trafficTimeLoss": 241,
    "breakAndRestPeriod": 1800,
    "waitingPeriod": 0,
    "scemid": "X9X9X9X9X9"
  }],
  "subscriptionID": "d2dac125bec94e248e80aa7900b8f91c"
}

STATUS_STOP events with one of the event subtypes ARRIVED, DEPARTED, SUSPENDED or CANCELLED also trigger notification(s) when the stop to which the event is sent has subscription(s). A subscribed tour also receives the notification.

Such notifications have one of the notificationContentType:

STOP_ARRIVED,

STOP_DEPARTED,

STOP_CANCELLED or

STOP_SUSPENDED.

{
  "notificationContentType": "STOP_ARRIVED",
  "topicType": "ETA",
  "notificationPayLoad": [
    {      
      "coordinate": {
        "locationX": "7.4406359857",
        "locationY": "51.529677327"
      },
      "addInfo": "...",
      "distanceToStop": 0,
      "timeStamp": "YYYY-MM-DDThh:mm:ss.000000+00:00",	// time of STATUS_STOP -> CANCELLED event sent
      "scemid": "X9X9X9X9X9"				// stop being suspended with event sent
    }
  ],
  "subscriptionID": "00000000000000000000000000000000"	// subscription id to which this notification will be sent
}

Tour update notifications with PUSH_MOBILE

Following notification is pushed on subscription over PUSH_MOBILE.

SUBSCRIPTION_CONFIRMATION

{
    "notificationContentType": "SUBSCRIPTION_CONFIRMATION",  // SUBSCRIPTION_CONFIRMATION, TOUR_UPDATE
    "topicType": "TOUR_UPDATE",                              // TOUR_UPDATE, ETA_INFO
    "notificationPayLoad": [
    {
        "info": "Tour update subscription confirmation",
        "source": "MY_APP_V1.2",
        "scemid": "X9X9X9X9X9"                               // Tour SCEMID
    }],
    "subscriptionID": "00000000000000000000000000000000"     // subscription id to which this notification was sent
}

On tour changes, following notification is created and pushed to mobile/web applications.

TOUR_UPDATE

{
    "notificationContentType": "TOUR_UPDATE",                // SUBSCRIPTION_CONFIRMATION, TOUR_UPDATE
    "topicType": "TOUR_UPDATE",                              // TOUR_UPDATE, ETA_INFO
    "notificationPayLoad": [
    {
        "info": "Tour X9X9X9X9X9 was updated",
        "source": "MY_APP_V1.2",
        "scemid": "X9X9X9X9X9"                               // Tour SCEMID
    }],
    "subscriptionID": "00000000000000000000000000000000"     // subscription id to which this notification was sent
}

NotificationContentType

• ETA_INFO
• SUBSCRIPTION_CONFIRMATION
• STOP_APPROACHING
• STOP_ARRIVED
• STOP_DEPARTED
• STOP_CANCELLED
• STOP_SUSPENDED
• TOUR_UPDATE

Notification on error

D&A users with a valid subscription to the tour or a stop for topic type ETA will be notified on any routing error.

Such notification has the type : ETA_FAILED_INFO

An error payload included in the notification contains:

• stopIndex - stop index in tour (none 0 index)
• errorCode - a defined code for the occured error
• errorMessage - detailed message occured during the error
• relatedTime - time related to error
• scemid - subscribed stop / tour
• info - additional info

Defined ErrorCodes:

• STOP_UNROUTABLE - Concerning leg error, stop cannot be routed due to various restrictions
• STOP_UNREACHABLE - Linking error, stop cannot be linked due to malformed or unreachable coordinates

Example

{
    "notificationContentType": "ETA_FAILED_INFO",
    "topicType": "ETA"
    "notificationPayLoad": [
    {
        "errorCode": "STOP_UNROUTEABLE",
        "errorMessage": "cannot calculate route (concerning leg 11)",
        "info": "RefRoute - Route cannot be calculated.",
        "relatedTime": "YYYY-MM-DDThh:mm:ss.000000+00:00",
        "scemid": "X9X9X9X9X9",
        "stopIndex": 11
    }],
    "subscriptionID": "00000000000000000000000000000000",
}