PTV Drive&Arrive | API Guide > API Description > /event/_POST

Events

Events have following functions in PTV Drive&Arrive:

/event/ POST - create an event for ..

This section contains the base information for every event.

Call to API to trigger an event. The originator can be an OBU (telematic) or a web application (planner).

{
 "source": "MYPRODUCT_V2.8",	// User defined value that describes the originator of the event. e.g. "mytmsweb", "our_Software", "BestAppV1.2" ...
 "event": {
  "eventType": "POSITION",	// Type of the event defined in  ..ServiceModel\Types\EMEnums.EventType (POSITION, OBUTACHO, STATUS_STOP..)
  "eventSubtype": "GPS",	// The eventSubtype is an optional parameter depending on the eventType. e.g. STATUS_STOP -> ARRIVED
  "visibility": true,		// Visibility of coordinates (true = visible, false = is not visible to dispatcher or ramp )
  "scemid": "X9X9X9X9X9",	// SCEM-ID on which the event refers to (can be a tour or a stop SCEM-ID)
  "eventPayLoad": {
   ....				// This eventPayLoad depends on the given eventType. Please refer to the depending descriptions.
  }
 }
}

The following sections contain only the available eventPayLoads.

Exceptions

validation / message errorCode
eventSubtype must be GPS for eventType POSITION and OBUTACHO and ARRIVED or DEPARTED for STATUS_STOP INVALID_EVENTSUBTYPE
time stamp must be in UTC format, e.g. YYYY-MM-DDThh:mm:ss.0000000+01:00 TIMESTAMP_INVALID
Position information has an invalid coordinate format, a geodecimal format is expected. INVALID_COORDINATE_FORMAT
SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour or stop. SCEMID_INVALID
Too many source characters. Source parameter is limited to 30 characters. SOURCE_LENGTH_EXCEEDED
Tour has expired. Eta will not be refreshed for [<STOP_SCEMID>]* EVENT_TO_EXPIRED_TOUR
Maximum allowed tour duration of n days from [YYYY-MM-DDThh:mm:ss.0000000+01:00] has been exceeded.** TOUR_DURATION_EXCEEDED
Position information has an invalid speed format, a geodecimal format is expected. INVALID_EVENTPAYLOAD_SPEED_FORMAT
Position information has an invalid heading format, a geodecimal format is expected. INVALID_EVENTPAYLOAD_HEADING_FORMAT
Position information has an invalid accuracy format, a geodecimal format is expected. INVALID_EVENTPAYLOAD_ACCURACY_FORMAT

* A tour is expired if the latest departure time in the stops has already been reached. An event to such a tour stop will result in an error response EVENT_TO_EXPIRED_TOUR and will not be processed

** This error code with message is returned when the actual duration for the tour to complete, is longer than the maximum allowed duration per token. By default, the maximum allowed duration for a tour is set to 7 days.

Skipped events

Some events are skipped without raising an error response. Event requests for example are limited to 1 event per 2 seconds. Any excess events sent within this 2 seconds limit are ignored. However a success response is returned for these requests, and there is also no journal entry for such an event. You can check the meta dictionary of the response, which indicates whether an event is ignored.

{  
  "responseStatus": {  
    "errorCode": "SUCCESS",
    "meta": {  
      "SKIPPED_OVERUSE": "An event with SCEMID X9X9X9X9X9 has already been received 2s ago. This event will not be processed."
    }
  }
}
validation / message meta code
An event with SCEMID X9X9X9X9X9 has already been received 2s ago. This event will not be processed. SKIPPED_OVERUSE
Received event with SCEMID X9X9X9X9X9 is duplicate and will not be processed. SKIPPED_DUPLICATE
Received event with SCEMID X9X9X9X9X9 is older than last event and will not be processed. SKIPPED_OBSOLETE

Sending positions with stop-prediction feature: EXPERIMENTAL.

If you do not know to which stop of the multi-stop tour you want to send your position to or just want to use the automatic detection of states (APPROACHING, ARRIVED, DEPARTED), you can send the positions using the tour-SCEMID. In this case, Drive&Arrive will predict to which stop the driver is driving currently and manage all the stop states automatically without any further interaction.

/event/ POST - create a POSITION (GPS, ...) event for ETA tracking

Will be sent by telematics or from PTV Drive&Arrive iOS or Android Driver App 1.x to transmit current position of truck.

{
 "source": "MYPRODUCT_V2.8",			// User defined value that describes the originator of the event. e.g. "mytmsweb", "our_Software", "BestAppV1.2" ...
 "event": {
  "eventType": "POSITION",			// Type of the event POSITION
  "eventSubtype": "GPS",			// optional: for eventType POSITION it can be GPS or NETWORK etc.
  "visibility": true,				// Visibility of coordinates (true = visible, false = is not visible to dispatcher or ramp )
  "scemid": "X9X9X9X9X9",			// SCEM-ID on which the event refers to (can be a tour or a stop SCEM-ID)
  "eventPayLoad": {
   "coordinate": {				// LatLon of a geographic position in WGS84
    "locationX": 8.61656234754918,		// longitude of coordinate in WGS 84, e.g. 13.4261419 for Berlin / mandatory
    "locationY": 49.8182790029665		// latitude of coordinate in WGS 84, e.g. 52.5075419 for Berlin / mandatory 
   },
   "timeStamp": "YYYY-MM-DDThh:mm:ss.000+01:00"	// time stamp of event generation on side of the event sender in UTF-Format
   "heading": 360,                              // optional: degree (0=North 90=East 0-360), use 360 for 0 deg
   "accuracy": 0.0,                             // optional: accuracy in meter 
   "speed": 0.0                                 // optional: meter/seconds, 0.0 = no speed
  }
 }
}

Results

/event/ POST - create an OBUTacho event for ETA tracking including rest and service times additionally

Will be sent by OBU via TMS to transmit position as well as current rest and service times concerning break or driver change.

{
  "source": "MYPRODUCT_V2.8",                      // User defined value that describes the originator of the event. e.g. "mytmsweb", "our_Software", "BestAppV1.2" ...
  "event": {
    "eventType": "OBUTACHO",                       // Type of the event OBUTACHO
    "eventSubtype": "GPS",                         // optional: for eventType OBUTACHO it can be GPS or NETWORK etc.
    "visibility": true,                            // Visibility of coordinates (true = visible, false = is not visible to dispatcher or ramp )
    "scemid": "X9X9X9X9X9",                        // SCEM-ID on which the event refers to (can be a tour or a stop SCEM-ID)
    "eventPayLoad": {
      "driverReference": "driver 1",               // optional: driver information depending of the provider
      "raSTime": {                                 // rest and service time information
        "periodDrivenSinceLastBreak": 0,           // The amount of time the driver has spent operating the vehicle since the last break
        "periodDrivenSinceLastRest": 0,            // The amount of time the driver has spent operating the vehicle since the last rest
        "currentIdlePeriod": 0,                    // The amount of time the driver has spent idle right before the reference time
        "isSplitBreak": false,                     // True if  the driver has already completed the first part of his split break. Since then he has operated his vehicle or performed active service.
        "isSplitRest": false                       // True if  the driver has already completed the first part of his split rest. Since then he has operated his vehicle or performed active service.
      },
      "coordinate": {                              // LatLon of a geographic position in WGS84
        "locationX": 8.61656234754918,             // longitude of coordinate in WGS 84, e.g. 13.4261419 for Berlin / mandatory
        "locationY": 49.8182790029665              // latitude of coordinate in WGS 84, e.g. 52.5075419 for Berlin / mandatory 
      },
      "timeStamp": "2013-03-07T10:00:00.000+01:00" // time stamp of event generation on side of the event sender in UTF format
      "heading": 360,                              // optional: degree (0=North 90=East 0-360), use 360 for 0 deg
      "accuracy": 0.0,                             // optional: accuracy in meter 
      "speed": 0.0                                 // optional: meter/seconds, 0.0 = no speed
    }
  }
}

Results

/event/batch POST - sending multiple events at once

This API call allows users to send multiple events belonging to a same tour or to stops in a same tour. Events can be of any existing eventType. The originator can be an OBU (telematic) or any web/mobile application.

This API call can be made by calling https://driveandarrive-v1.cloud.ptvgroup.com/em/event/batch?source=myproduct_v2.8

Example POST data:

{
  "events": [
    {
      "eventType": "POSITION",
      "eventSubtype": "GPS",
      "visibility": true,
      "eventPayLoad": {
        "heading": 18.43496718915071,
        "coordinate": {
          "locationX": 7.482548394,
          "locationY": 51.466587636
        },
        "timeStamp": "YYYY-MM-DDThh:mm:ss.000+01:00"
      },
      "scemid": "X9X9X9X9X9"
    },
    {
      "eventType": "POSITION",
      "eventSubtype": "GPS",
      "visibility": true,
      "eventPayLoad": {
        "heading": 353.99098752334834,
        "coordinate": {
          "locationX": 7.4806452506,
          "locationY": 51.470305967
        },
        "timeStamp": "YYYY-MM-DDThh:mm:ss.000+01:00"
      },
      "scemid": "X9X9X9X9X9"
    },
    {
      "eventType": "STATUS_STOP",
      "eventSubtype": "SUSPENDED",
      "visibility": true,
      "eventPayLoad": {
        "heading": 326.3100829908429,
        "coordinate": {
          "locationX": 7.4793476529,
          "locationY": 51.480220034
        },
        "timeStamp": "YYYY-MM-DDThh:mm:ss.000+01:00"
      },
      "scemid": "X9X9X9X9X9"
    }
  ]
}

Note: Only the last event of eventType POSITION in this call will trigger ETA calculation, if the last ETA calculation period has been expired.

Exceptions

validation / message errorCode
eventSubtype must be GPS for eventType POSITION and OBUTACHO and ARRIVED or DEPARTED for STATUS_STOP. INVALID_EVENTSUBTYPE
time stamp must be in UTC format, e.g. YYYY-MM-DDThh:mm:ss.0000000+01:00 TIMESTAMP_INVALID
Position information has an invalid coordinate format, a geodecimal format is expected. INVALID_COORDINATE_FORMAT
SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour or stop. SCEMID_INVALID
Too many source characters. Source parameter is limited to 30 characters. SOURCE_LENGTH_EXCEEDED
Tour has expired. Eta will not be refreshed for [<STOP_SCEMID>]* EVENT_TO_EXPIRED_TOUR
Maximum allowed tour duration of n days from [YYYY-MM-DDThh:mm:ss.0000000+01:00] has been exceeded.** TOUR_DURATION_EXCEEDED
Only events to stops belonging to a single tour is allowed. EVENTS_TO_MULTIPLE_TOURS
Position information has an invalid speed format, a geodecimal format is expected. INVALID_EVENTPAYLOAD_SPEED_FORMAT
Position information has an invalid heading format, a geodecimal format is expected. INVALID_EVENTPAYLOAD_HEADING_FORMAT
Position information has an invalid accuracy format, a geodecimal format is expected. INVALID_EVENTPAYLOAD_ACCURACY_FORMAT

/event/ POST - create a status event (STATUS_STOP - state of stop)

DriveAndArrive API allows users to set certain status to a stop. This can be used to inform a dispatcher or provide customer specific requirements for a specific stop.

Status can be sent from a driver (with coordinate) or from a dispatcher (without coordinate).

Status events do not trigger ETA calculation.

{
 "event": {
  "eventType": "STATUS_STOP",			// Type of the event STATUS_STOP
  "eventSubtype": "ARRIVED",			// The eventSubtype is a MANDATORY parameter, APPROACHING / ARRIVED / DEPARTED / SUSPENDED / CANCELLED for STATUS_STOP
  "visibility": true,				// Visibility of coordinates (true = visible, false = is not visible to dispatcher or ramp)
  "scemid": "X9X9X9X9X9",			// SCEM-ID on which the event refers to (only Stop SCEM-ID)
  "eventPayLoad": {
   "timeStamp": "2013-03-07T10:00:00.000+01:00"// timestamp of event generation on side of the event sender in UTF-format
   "addInfo": "User defined comment",		// comment of sender:  I'm 10 minutes late because of some reason at stop X
   "coordinate": {				// LatLon of a geographic position in WGS84
    "locationX": 8.61656234754918,		// longitude of coordinate in WGS 84, e.g. 13.4261419 for Berlin / mandatory
    "locationY": 49.8182790029665		// latitude of coordinate in WGS 84, e.g. 52.5075419 for Berlin / mandatory 
   }
  }
 }
}

Here, the eventType must be set to STATUS_STOP and the eventSubType should be one of the predefined states.

Drive&Arrive defines 5 such states (stop status):

eventSubtype = APPROACHING

eventSubtype = ARRIVED

eventSubtype = DEPARTED

eventSubtype = SUSPENDED

eventSubtype = CANCELLED

Auto Stop_Status Events generation

Drive&Arrive sets various STATUS described above to the executing tour stops, depending on various conditions. These conditions may relate to

The STATUS Approaching, Departed, Suspended will be set automatically by Drive&Arrive, if not set by the user (Driver).

Approaching STATUS is set to a stop automatically by D&A, if a position event is received to the stop and in following conditions:

  1. The stop has no STATUS previously set to it, or
  2. The stop was set to STATUS Suspended.

Departed STATUS is set to a stop automatically by D&A, if a position event is received to the stop and in following conditions:

  1. The stop has an Arrived STATUS, and
  2. The position received is not within some geofence radius from the stop. (default radius: 400m)

Suspended STATUS is set to a stop automatically by D&A, if a position event is received for another stop in the tour and

  1. The stop has previously an Approaching STATUS

Advised flow of different STATUS states to a stop in Drive and Arrive

The diagram below shows how a status should be used in Drive and Arrive and the correct flow from one status to another. It also shows how some status are generated automatically from Drive and Arrive on different conditions.

 

 

© 2022 PTV Planung Transport Verkehr GmbH | Imprint

Get in Contact