PTV Drive&Arrive | API Guide > API Description > Journal

Journal

PTV Drive&Arrive creates a protocol of (all) relevant operations.

/journal/ GET - get journal of tour with the assigned token and SCEM-ID

The method call https://driveandarrive-v1.cloud.ptvgroup.com/em/journal?SCEMID=X9X9X9X9X9&token=<25_digit_token>&source=<myProduct_Vx.y> will return a protocol of all recorded operations, subscriptions, events and notifications. If the API call contains the optional source parameter the value is assigned to the event source content --> default = "unknown"

Below you find examples extracted from a /journal/ GET response. "JournalEntries" contains an array of "JournalEntry" with different journalTypes (TOUR_CREATED, SUBSCRIPTION_CREATED, EVENT_CREATED, STATUS_STOP, ETA_INFO, SUBSCRIPTION_REMOVED, TOUR_DELETED). Each JournalEntry can contain an "entry" content that is JSON encoded:

		
{
  "journalEntries":[
    {
      "ts":"YYYY-MM-DDThh:mm:ss.0000000+01:00", // time stamp of tour creation API call
      "journalType": "TOUR_CREATED",            // type of journal entry. Can be TOUR_CREATED, TOUR_UPDATED, SUBSCRIPTION_CREATED, EVENT_CREATED, STATUS_STOP, ETA_INFO, SUBSCRIPTION_REMOVED, TOUR_DELETED
      "description": "Tour created",            // description of journal entry
      "entry": "{ ... }",                       // The content depends on the "journalType".
      "scemid": "X9X9X9X9X9",                   // SCMEM-ID of this tour, stop or event
      "source": "customer specific entry"       // either the given source from API call, or if not set as default "unknown"
    },
    {
      ... all other journal entries ...
    }
  ]
}
The following section contains several examples for possible journal entries.

TOUR_CREATED

This journal entry informs about a created tour.

		
{
  "ts":"YYYY-MM-DDThh:mm:ss.0000000+01:00", // time stamp of tour creation API call
  "journalType": "TOUR_CREATED",            // type of journal entry.
  "description": "Tour created",            // description of journal entry
  "scemid": "X9X9X9X9X9",                   // SCMEM-ID of this tour
  "entry" : "{ ... }",                      // the tour as json 			
  "source": "customer specific entry"       // either the given source from API call, or if not set as default "unknown"
}

TOUR_UPDATED

This journal entry informs about an updated tour.

		
{
  "ts":"YYYY-MM-DDThh:mm:ss.0000000+01:00", // time stamp of tour update API call
  "journalType": "TOUR_UPDATED",            // type of journal entry.
  "description": "Tour Updated",            // description of journal entry
  "scemid": "X9X9X9X9X9",                   // SCMEM-ID of this tour
  "entry" : "{ ... }",                      // the updated tour as json 					
  "source": "customer specific entry"       // either the given source from API call, or if not set as default "unknown"
}

STOP_UPDATED

This journal entry informs about an updated stop in the tour.

		
{
  "ts":"YYYY-MM-DDThh:mm:ss.0000000+01:00", // time stamp of stip update API call
  "journalType": "STOP_UPDATED",            // type of journal entry.
  "description": "Stop updated",            // description of journal entry
  "scemid": "X9X9X9X9X9",                   // SCMEM-ID of this tour
  "entry" : "{ ... }",                      // the updated stop object
}

STOP_DELETED

This journal entry informs about a deleted stop in the tour.

		
{
  "ts":"YYYY-MM-DDThh:mm:ss.0000000+01:00", // time stamp of stop delete API call
  "journalType": "STOP_DELETED",            // type of journal entry.
  "description": "Stop deleted",            // description of journal entry
  "scemid": "X9X9X9X9X9",                   // SCEM-ID of the deleted stop
  "entry" : "{ ... }",                      // the deleted stop scemid
}

ETA_INFO

RefRoute ETA infos

This journal entry contains the EtaInfo for each stop in the tour. Both creation and updating a tour force an ETA calculation.

		
{
  "ts": "2016-06-06T07:00:05.4585799+00:00",
  "journalType": "ETA_INFO",
  "description": "RefRoute ETA info´s",
  "entry": "[
    {
        "scemid": "X9X9X9X9X9",
        "planned": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "refroute": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "estimated": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "notification": true,
        "uniqSeqId": "d7f5204ed6424a1f9fe7a626008dce22",
        "trafficTimeLoss": 1158,
        "breakTimeLoss": 0,
        "info": "Tour Create/Update"
    },
    {
	  .... for each stop in the tour an entry ....
    },
    {
        "scemid": "X8X8X8X8X8",
        "planned": "2016-06-15T16:46:00.0000000+02:00",
        "refroute": "2016-06-15T23:43:59.0000000+02:00",
        "estimated": "2016-06-15T23:43:59.0000000+02:00",
        "notification": true,
        "uniqSeqId": "d7f5204ed6424a1f9fe7a626008dce22",
        "trafficTimeLoss": 1158,
        "breakTimeLoss": 0,
        "info": "Tour Create/Update"
    }
  ]",
  "scemid": "X1X1X1X1X1"
}

ETA_INFO

This journal entry contains the EtaInfo if the (position) event was used for an ETA calculation. For each stop exists a single journal entry.

		
{
    "ts": "YYYY-MM-DDThh:mm:ss.0000000+01:00"
    "journalType": "ETA_INFO",
    "description": "ETA info",
    "scemid": "X9X9X9X9X9",
    "entry": {
        "uniqSeqId": "01234567890123456789012345678901",      // unique sequence identifier of API call
        "originator": {                                       // original event that has forced ETA calculation
            "coordinate": {
                "locationX": 11.000000,
                "locationY": 49.000000
            },
            "heading": 145.23,
            "timeStamp": "YYYY-MM-DDThh:mm:ss.0000000+01:00"
        },
        "planned": "YYYY-MM-DDThh:mm:ss.0000000+01:00",       // customer planned time of selected stop
        "estimated": "YYYY-MM-DDTmm:hh:ss.0000000+01:00",     // time of current ETA
        "refroute": "YYYY-MM-DDTmm:hh:ss.0000000+01:00",      // time of calculated route at tour start
        "scemid": "X9X9X9X9X9",                               // SCEM-ID of selected stop
        "notification": false,
        "trafficTimeLoss": 14,                                // current delays due to traffic incidents or patterns in seconds
        "breakTimeLoss": 0,                                   // already detected breaks in seconds
        "waitingPeriod": 0,                                   // waiting period on route
        "info": ""PositionEvent - Route cannot be calculated"  // an info text is set, e.g. if the route cannot be calculated
    },
}

entry.info also contains useful information on how the ETA was calculated based on current traffic information.

		
{
    "ts": "YYYY-MM-DDThh:mm:ss.0000000+01:00"
    "description": "ETA info",
    "journalType": "ETA_INFO",
    "scemid": "X9X9X9X9X9",                                   // SCEM-ID of selected stop
    "entry": {
        "trafficTimeLoss": 14,
        "breakTimeLoss": 0,                                   // current delays due to traffic incidents or patterns in seconds
        "waitingPeriod": 0                                    // waiting period on route
        "notification": false,
        "planned": "YYYY-MM-DDThh:mm:ss.0000000+01:00",       // customer planned time of selected stop
        "estimated": "YYYY-MM-DDTmm:hh:ss.0000000+01:00",     // time of current ETA
        "refroute": "YYYY-MM-DDTmm:hh:ss.0000000+01:00",      // time of calculated route at tour start
        "scemid": "X9X9X9X9X9",
        "uniqSeqId": "01234567890123456789012345678901",      // unique sequence identifier of API call
        "info": "PositionEvent - (traffic information excluded due to inaccessible route sections)",
    },
}

ETA_FAILED_INFO

Similar to ETA_INFO, this journal entry is created on routing error, where no ETA can be calculated.

{
    "ts": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
    "journalType": "ETA_INFO",
    "description": "ETA failed info",
    "entry": {
        "scemid": "X8X8X8X8X8",
        "planned": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "refroute": "0001-01-01T00:00:00.0000000+00:00",
        "estimated": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "notification": true,
        "uniqSeqId": "948a141f-2a5a-4f2e-ac27-aac000c05d38",
        "trafficTimeLoss": 0,
        "breakTimeLoss": 0,
        "info": "PositionEvent - Route cannot be calculated."
     },
    "scemid": "X8X8X8X8X8"
}

EVENT_CREATED

Position

This journal entry informs about a created event.

		
{
  "ts":"YYYY-MM-DDThh:mm:ss.0000000+01:00", // time stamp of event creation
  "journalType": "EVENT_CREATED",           // type of journal entry.
  "description": "Position",                // description of journal entry
  "entry": {
	\"eventType\":\"POSITION\",
	\"eventSubtype\":\"GPS\",
	\"visibility\":true,                    // TRUE if the coordinates are stored in the journal
	\"action\":\"FORCE_XROUTE_CALC\",       // Possible values NONE or if used for calculation FORCE_XROUTE_CALC
	\"eventPayLoad\":
	  {\"coordinate\":
		{
		  \"locationX\":16.22,
		  \"locationY\":58.11
		},
		\"timeStamp\":\"YYYY-MM-DDThh:mm:ss.0000000+01:00\"},
		\"scemid\":\"X9X9X9X9X9\"
	  }
  "scemid": "X9X9X9X9X9",                   // SCEM-ID of the depending stop scemid
  "source": "customer specific entry"       // either the given source from API call, or if not set as default "unknown"
}

EVENT_CREATED

Status stop

This journal entry informs about a created event.

		
{
  "ts":"YYYY-MM-DDThh:mm:ss.0000000+01:00", // time stamp of event creation
  "journalType": "EVENT_CREATED",           // type of journal entry.
  "description": "Status stop",            // description of journal entry
  "entry": {
	"eventType":"STATUS_STOP",
	"eventSubtype":"ARRIVED",          // Possible values ARRIVED, DEPARTED, APPROACHING
	"visibility":true,                   // TRUE if the coordinates are stored in the journal
	"eventPayLoad":
	  {"coordinate":
		{
		  "locationX":16.22,
		  "locationY":58.11
		},
		"timeStamp":"YYYY-MM-DDThh:mm:ss.0000000+01:00"},
		"scemid":"X9X9X9X9X9",
		"heading": 0,                               // optional: degree (0=North 90=East 0-360)
		"accuracy": 0.0,                             // optional: accuracy in meter 
		"speed": 0.0                                 // optional: meter/seconds, 0.0 = no speed
	  }
  "scemid": "X9X9X9X9X9",                   // SCEM-ID of the depending stop scemid
  "source": "customer specific entry"       // either the given source from API call, or if not set as default "unknown"
}

SUBSCRIPTION_CREATED

This journal entry informs about a created subscription.

		
{
  "ts":"YYYY-MM-DDThh:mm:ss.0000000+01:00", // time stamp of subscription creation
  "journalType": "SUBSCRIPTION_CREATED",    // type of journal entry.
  "description": "Subscribe",               // description of journal entry
  "entry": "{ ... }",                       // will be the transmitted subscription object itself. See source description above the code block.
  "scemid": "X9X9X9X9X9",                   // SCEM-ID of this subscription
  "source": "customer specific entry"       // either the given source from API call, or if not set as default "unknown"
}

SUBSCRIPTION_CONFIRMATION

This journal entry informs about confirmation of successfully created subscriptions.

		
{
  "ts":"YYYY-MM-DDThh:mm:ss.0000000+01:00",    // time stamp of subscription confirmation
  "journalType": "SUBSCRIPTION_CONFIRMATION",  // type of journal entry. 
  "description": "SUBSCRIPTION_CONFIRMATION",  // description of journal entry
  "entry": "{ ... }",                          // contains confirmation object with payload containing the subscription id
  "scemid": "X9X9X9X9X9",                      // SCEM-ID of this subscription
  "source": "customer specific entry"          // either the given source from API call, or if not set as default "unknown"
}

SUBSCRIPTION_REMOVED

This journal entry informs about a subscription was deleted.

		
{
  "ts":"YYYY-MM-DDThh:mm:ss.0000000+01:00", // time stamp of subscription removal
  "journalType": "SUBSCRIPTION_REMOVED",    // type of journal entry.
  "description": "Unsubscribe",             // description of journal entry
  "entry": "{ ... }",                       // will be the transmitted subscription object itself. See source description above the code block.
  "scemid": "X9X9X9X9X9",                   // SCEM-ID of this subscription
  "source": "customer specific entry"       // either the given source from API call, or if not set as default "unknown"
}

NOTIFICATION_INFO

This journal entry contains the notification to subscriptions if the ETA to the stop/tour becomes updated.

		
{
  "ts":"YYYY-MM-DDThh:mm:ss.0000000+01:00", // time stamp of the journal creation
  "journalType": "NOTIFICATION_INFO",       // type of journal entry.
  "description": "Notification info",       // description of journal entry
  "entry": "{ ... }",                       // notification object with updated eta info
  "scemid": "X9X9X9X9X9"                    // SCEM-ID of selected stop
}

TOUR_DELETED

This journal entry informs about a tour was deleted, this JournalEntry is never visible for a customer.

		
{
  "ts":"YYYY-MM-DDThh:mm:ss.0000000+01:00", // time stamp of tour delete
  "journalType": "TOUR_DELETED",            // type of journal entry. 
  "description": "Tour deleted",            // description of journal entry
  "entry": "",
  "scemid": "X9X9X9X9X9",                   // SCEM-ID of deleted tour
 "source": "customer specific entry"        // either the given source from API call, or if not set as default "unknown"
}

Exceptions

validation / messageerrorCode
Token does not exist.TOKEN_ERROR
Your token is blocked. Please contact support in order to get further information.TOKEN_BLOCKED
The validation date of the token is expired.TOKEN_EXPIRED
SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour.SCEMID_INVALID

/journal/ GET with paging

To get the journals to a tour more effectively, paging can be applied when calling journals. The method call https://driveandarrive-v1.cloud.ptvgroup.com/em/journal?SCEMID=X9X9X9X9X9&token=<25_digit_token>&startindex=0&itemsperpage=20&source=<myProduct_Vx.y> will return first 20 journals as in "itemsperpage" to the tour scemid. More journals can be asked just changing the StartIndex to next items.

for example, the next call can be with StartIndex=20 for the next 20 items.

/journal/batch

This API method gets the journals from a tour or a stop more effectively using multiple filters and paging options. Following options are available:

  1. SCEMIDs
    • Mandatory
    • comma seperated list of tours or stops scemids, which belong to a single token.
  2. From
    • Optional
    • get journals from this date. Format is YYYY-MM-DDThh:mm:ss
  3. Until
    • Optional
    • get journals till this date. Format as above.
  4. EntryTypes
    • Optional
    • filter journals with journal types. Such as TOUR_CREATED, EVENT_CREATED, ETA_INFO and more
  5. EventTypes
    • Optional
    • filter further journals with event types. This should be combined with EVENT_CREATED EntryTypes option. Available EventTypes are POSITION, OBUTACHO and STATUS_STOP.
  6. SortOrder
    • Optional
    • set the sorting option for returned journals. Sorting can be used for all available fields. For example: entryCreateTime|DESC for latest journals on top.
  7. StartIndex
    • Optional
    • Paging: set the start index of the return journals
  8. ItemsCount
    • Optional
    • Paging: set maximum journal returns at a time

Some example calls made using above filters:

  1. Get all journals of a tour

    https://driveandarrive-v1.cloud.ptvgroup.com/em/journal/batch?SCEMID=<TOUR_SCEMID>&token=<25_digit_token>&source=<myProduct>

  2. Get all journals of a stop

    https://driveandarrive-v1.cloud.ptvgroup.com/em/journal/batch?SCEMID=<STOP_SCEMID>&token=<25_digit_token>&source=<myProduct>

  3. Get events to a stop

    https://driveandarrive-v1.cloud.ptvgroup.com/em/journal/batch?SCEMID=<STOP_SCEMID>&entryTypes=EVENT_CREATED&token=<25_digit_token>&source=<myProduct>

  4. Get status events sent to all stops

    https://driveandarrive-v1.cloud.ptvgroup.com/em/journal/batch?SCEMID=<STOP_SCEMID>&entryTypes=EVENT_CREATED&eventTypes=STATUS_STOP&token=<25_digit_token>&source=<myProduct>

  5. Get journals descending (sort with time stamp)

    https://driveandarrive-v1.cloud.ptvgroup.com/em/journal/batch?SCEMID=<TOUR_SCEMID>&sortOrder=entryCreateTime|DESC&token=<25_digit_token>&source=<myProduct>


The method call https://driveandarrive-v1.cloud.ptvgroup.com/em/journal/batch?SCEMID=X9X9X9X9X9&token=<25_digit_token>&startindex=0&itemsperpage=20&source=<myProduct_Vx.y> will return first 20 journals as in "itemsperpage" to the scemid. More journals can be asked just changing the StartIndex to next items.

Here, for example, next call can be with StartIndex=20 for the next 20 items.

 

 

© 2022 PTV Planung Transport Verkehr GmbH | Imprint

Get in Contact