Quickstart Guide | PTV Drive&Arrive

Welcome to Drive&Arrive,

You will find everything you need to start Drive&Arrive as quickly as possible right here.

What is Drive&Arrive?
How can I test it without being a developer?
Where can I get free test access for development?
Under which server address can I access the Drive&Arrive services?
Where can I get support for development issues?
How do I create a trip?
How do I send positions on a trip?
How do I send status notifications on a trip?
How do I request the ETA of trips?
What else?

Reading time approximately 15 min

What is Drive&Arrive?

Drive&Arrive is a cloud service for calculating ETA – estimated time of arrival. Arrival times are needed in logistics to inform all participants in the supply chain and to be able to make optimisations during the trip.

In addition to ETA calculation, Drive&Arrive also provides correct handling of the rights of various participants, status management and support for integrating position information, as well as in distributing arrival information.

How can I test Drive&Arrive without being a developer?

You can start the test using the PTV Trip Creator on the homepage or directly at https://eta-viewer-trip-creator.ptvgroup.com.

This defines a test trip with up to 6 stops. You will then be able to:

Track the calculated ETA for the trip in the trip viewer. As long as no position has arrived, you can see the expected arrival time for the first stop, and subsequent times based on it;
Download a free app from one of the App Stores that sends positions. You can either enter the trip code via the app or by directly clicking on the link of the trip on your smartphone.

This creates a closed loop in which you can easily test how good the calculated ETA is for different vehicle types or driving and rest periods.

Where can I get a free test account for development?

If you wish to develop it by yourself using an interactive Swagger interface, or you want to program the interface, you will need a token. This is an authorisation to use the interface, required for many of the functions.

Test tokens for a limited time period are available, so if you would like one please contact us at:

Germany, Austria, Swiss:
For clients: vertrieb@ptvgroup.com
For partners: partnermanagement@ptvgroup.com

Under which server address can I access the Drive&Arrive services?

You can find them under

https://driveandarrive-v1.cloud.ptvgroup.com/

e.g. https://driveandarrive-v1.cloud.ptvgroup.com/stop/batch/eta?SCEMIDs=x1x1x1x1x1

Where can I get support for development issues?

Generally, you will find answers to all questions in our Developerzone. All content is available for free and without restriction at:

https://driveandarrive.cloud.ptvgroup.com/docs/

Here you will find, among other things:

The Drive&Arrive Interface documentation ;
With the interactive Swagger interface you can perform interactive tests and you can download the interface here
The interactive image of the Drive&Arrive ecosystem with many different programs and components to support you in the development process;
Example programs for C#, Javascript and others

How do I create a trip?

Trips are required to determine for which destinations an ETA is calculated and with which settings.

More specifically:

Stops on a trip
Vehicle
Information on driving times and rest periods

The best way to start is with an example:

This is a trip with one vehicle, two stops, each with coordinates, description, time slots and handling time, and without information on the driving time and rest period, i.e. by default, the driver is assumed to start from a rested state.

Show Copy&Paste Code

{
  "tour": {
    "vehicle" : {
      "vehicleProfileID" : "mg-truck-40t"
      }
    },
    "stops" : [
      {
        "coordinate" : {
          "locationX" : 8.424267,
          "locationY" : 49.0116971
        },
        "customData" : {
          "address" : {
             "label" : "76327 Pfinztal, Gewerbestraße 26"
         }
        }
        "useServicePeriodForRecreation" : "false",
        "serviceTimeAtStop": 5400,
        "earliestArrivalTime": "2018-11-10T00:00:00.0000000+01:00",
        "latestDepartureTime": "2018-11-10T23:59:00.0000000+01:00"
      },
      {
        "coordinate" : {
          "locationX" : 8.5887186,
          "locationY" : 48.8817074
        },
        "customData" : {
          "address" : {
            "label" : "75173 Pforzheim, Am Stangenacker 5-7"
        }
        },
        "useServicePeriodForRecreation" : "false",
        "serviceTimeAtStop": 300,
        "earliestArrivalTime": "2018-09-19T12:00:00.0000000+02:00",
        "latestDepartureTime": "2018-09-19T13:00:00.0000000+02:00"
      }
    ],
    "drivers" : [
      {
        "raSTime" : {
          "periodDrivenSinceLastRest" : 0,
          "periodDrivenSinceLastBreak" : 0,
          "currentIdlePeriod" : 0,
          "isSplitBreak" : false,
          "isSplitRest" : false
        }
      }
    ]
  }
}

The description of the trip as above is consigned as payload (page content) to:

https://driveandarrive-v1.cloud.ptvgroup.com/em/tour?token=<your-token>&source=<myProduct_Vx.y>

Further explanations on options and other possibilities can be found here: /tour POST

How do I send positions on a trip?

Positions of the vehicle for which the ETA is to be calculated are sent with

https://driveandarrive-v1.cloud.ptvgroup.com/em/event

For example, payload is

Show Copy&Paste Code

{
 "source": "MYPRODUCT_V2.8",			
 "event": {
  "eventType": "POSITION",			
  "eventSubtype": "GPS",			
  "visibility": true,								// Visibility of coordinates (true = visible, false = invisible to dispatcher or ramp)
  "scemid": "X9X9X9X9X9",							// SCEM-ID on which the event refers to (can be a trip or a stop SCEM-ID)
  "eventPayLoad": {
   "coordinate": {									// latlong 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": 0,                                	// optional: degree (0=North 90=East 0-360) 
   "accuracy": 0.0,                             	// optional: accuracy in metres 
   "speed": 0.0                                 	// optional: metres/seconds, 0.0 = no speed
  }
 }
}

The following are important:

Always specify the SCEM-ID of the stop you are approaching;
Positions at least every 10 min, preferably 2 min;
If possible, specify positions with accuracy (accuracy of the signal) and heading. If the values are not available, it is better to omit the whole entry.
Further explanations on options and other possibilities can be found here: /event/ POST

How do I send status notifications on a trip?

The status notification "Arrived" does not necessarily have to be sent on a trip. It is necessary for the handling time to be recognised and the handling time to be correctly included in the calculation. If they are not sent, it is not recognised when the handling time starts or ends (this is automatically generated), and during the handling time, the ETA may be a little more optimistic than reality.

Status notifications are also sent with https://driveandarrive-v1.cloud.ptvgroup.com/em/event and Drive&Arrive, e.g. for arrival notifications

Show Copy&Paste Code

{
 "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 = invisible 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"		// time stamp 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": {									// latlong 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 
   }
  }
 }
}

Further information can be found here.

How do I request ETA of trips?

The ETA of trips can be requested in different ways

you pull the information with GET /stop/batch/eta
you subscribe to ETA notifications by http callback
you subscribe to ETA notifications by SSE (notification)
you subscribe to ETA notifications by Onesignal (notification)

With possibility 1) you get the ETA always immediately when you ask for it. You can also ask for multiple ETAs in one call.

Example-Request

GET https://driveandarrive-v1.cloud.ptvgroup.com/em/stop/batch/eta?SCEMIDs=X1X1X1X1X1&source= MYPRODUCT_V2.8

Example-Response

Show Copy&Paste Code

{
  "stopTimeInfos": [
    {
      "stopSCEMID": "X1X1X1X1X1",
      "plannedETA": "YYYY-MM-DDThh:mm:ss.0000000+01:00",   		// PTA as it is specified.
      "eta": "YYYY-MM-DDThh:mm:ss.0000000+01:00",         		// calculated ETA 
      "etaSource": "CALCULATE_REFROUTE_ETA",               		// What triggered calculation
      "relatedTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",  		// Time of the triggering "event"
      "trafficTimeLoss": 8           							// current delays due to traffic incidents or patterns in seconds
    }
  ],
  "responseStatus": {
    "errorCode": "SUCCESS",
    "message": "59be17c35b46472592dda626008e412c"
  }
}

With possibility 2) you subscribe with /subscription/ POST to a notification you receive on the URL you have defined in the subscription. You will receive notifications always directly after a new ETA has been calculated. This method is ideal for app development.

Example-Request

https://driveandarrive-v1.cloud.ptvgroup.com/em/subscription?source=Test

with content (payload):

Show Copy&Paste Code

"subscription": {
   "notificationType": "CALLBACK_URL",					// type of notification channel, here HTTP callback
   "topicType": "ETA",                          		// (optional) ETA orTOUR_UPDATE
   "notificationDescription": {							// notification details
     "callBackURL":"http://requestb.in/x9x9x9x9", 		// URL of your server
     "ident": "your_identifier"							// (optional) your personal identifier, e.g. system-XY - can be used for debugging purposes
   },
   "scemid": "X9X9X9X9X9"								// SCEM-ID of tour or stop you will receive notifications from
 },		
 "source": "MYPRODUCT_V2.8"                     		// Who does request this subscription?
}

Example-Response

After subscribing you will get a subscription confirmation, later if ETA was calculated, you will receive ETAs at the URL you specified like:

Show Copy&Paste Code

{
 "notificationContentType":"ETA_INFO",
 "notificationPayLoad":[{
  "scheduledTime":"YYYY-MM-DDThh:mm:ss.0000000+01:00",   // PTA, user planned arrival
  "estimatedTime":"YYYY-MM-DDThh:mm:ss.0000000+01:00",   // ETA, estimated time when truck will arrive
  "scemid":"X9X9X9X9X9"                                  // SCEM-ID of concerned stop
 }]
}

With possibility 3) you subscribe with /subscription/ POST to a notification as SSE-notification. So you receive ETA in a defined SSE notification object, always directly after a new ETA has been calculated. This method also designed for server2server communication. You have to create a SSE connection first in you program (see our example program)

Example-Request

https://driveandarrive-v1.cloud.ptvgroup.com/em/subscription?source=Test

With content (payload)

Show Copy&Paste Code

{{ 
 "subscription": {
  "notificationType": "PUSH_NON_MOBILE_SSE",					// type of notification channel, here SSE
  "topicType": "ETA",											// (optional) ETA or TOUR_UPDATE
  "notificationDescription":{
   "ident" : "<identifier of SSE connection>"					// notificationHandler.GetNotificationHub(...).Ident in C#.net Codesample
  },
  "scemid": "X9X9X9X9X9"										// SCEM-ID of tour or stop that should be get notifications
 },
 "source": "MYPRODUCT_V2.8"										// Who does request this subscription?
}

Example-Response

After subscribing you will get a subscription confirmation, later if ETA was calculated, you will receive notification about calculated ETAs with content like:

Show Copy&Paste Code

{
 "notificationContentType":"ETA_INFO",
 "notificationPayLoad":[{
  "scheduledTime":"YYYY-MM-DDThh:mm:ss.0000000+01:00",   	// PTA, user planned arrival
  "estimatedTime":"YYYY-MM-DDThh:mm:ss.0000000+01:00",   	// ETA, we expect truck will arrive
  "scemid":"X9X9X9X9X9"                                  	// SCEM-ID of concerned stop
 }]
}

With possibility 4), you subscribe with /subscription/ POST to a notification as OneSignal notification. So you receive ETA in a defined SSE notification object, always directly after a new ETA has been calculated. This method is ideal for app development. You have to know a device-id, created on the mobile device side to subscribe

Example-Request

https://driveandarrive-v1.cloud.ptvgroup.com/em/subscription?source=Test

With content (payload)

Show Copy&Paste Code

{
	"subscription": {
	    "notificationType": "PUSH_MOBILE",      		// type of notification channel, here PUSH_MOBILE
	    "topicType" : "TOUR_UPDATE",            		// subscription topic: TOUR_UPDATE or ETA
	    "notificationDescription": {
	        "ident": "your_onesignal_identifier"		// your device identifier acquired after registering to OneSignal
	    },
	    "scemid": "X9X9X9X9X9"                  		// SCEM-ID of tour or stop you will receive notifications from
	},
	"source": "MYPRODUCT_V2.8"                  		// Who does request this subscription?
}

After subscribing you will get a subscription confirmation, later if ETA was calculated, you will receive notification about calculated ETAs with content like:

Example-Response

Show Copy&Paste Code

{
 "notificationContentType":"ETA_INFO",
 "notificationPayLoad":[{
  "scheduledTime":"YYYY-MM-DDThh:mm:ss.0000000+01:00",   	// PTA, user planned arrival
  "estimatedTime":"YYYY-MM-DDThh:mm:ss.0000000+01:00",   	// ETA, we expect truck will arrive
  "scemid":"X9X9X9X9X9"                                  	// SCEM-ID of concerned stop
 }]
}

What else?

Apart from the described functions, there are a lot of additional functionality, that let you

Manage tours and update them
Receive information about tour updates and status updates
Manage locations, (that are defined place e.g. for Arrival boards) and create trips to them
Manage and update stops
More events to informs Drive&Arrive e.g. batch sending of positions
Access the journal to get all historic information about your trips

Get in Contact