Monitoring trips in real-time – last part of the report

In yesterday’s article we informed about authentication and billing – and you got code, code, code …

What’s the great thing about this approach?

Our API is process-agnostic concerning your own tool chain and logistics processes. For example, it doesn’t matter where the positioning event comes from: directly from a mobile device, via a Fleet Management System or from a desktop client like a Travel Management or Tour Planning System. You are free to choose the best way how to integrate PTV Drive&Arrive in your existing architecture. Of course, creating a trip should take place where the trip was created, i.e. where the Token owner is located.

With this approach, you are able to get an integrated ETA ( = Estimated Time of Arrival) management for a fleet even if it uses different types of telematic systems and other different tools among all the stakeholders of the transport chain.

How can I test PTV Drive&Arrive without implementing anything?

We will provide a web portal for demo purposes during the next weeks. It enables you to create trips for free. In addition, you can find an iOS and an Android app that is able to send positions to PTV Drive&Arrive for a given SCEMID (no navigation, no map, simply sending positions and displaying ETA).

Please have a look at our online documentation at https://driveandarrive-v1.cloud.ptvgroup.com/ where you can find demo capabilities for developers, a detailled API description and some code samples. This is also the URL for the API end points!

If you have an further technical questions, do not hesitate to contact our technical support at driveandarrive.support@ptvgroup.com .

Real-time sequel: A report from the source

DriverAppIn yesterday’s article we introduced how PTV Drive&Arrive is working. Let’s dive into today’s topic:

What about authentication and billing?

You pay per trip. We count the number of trips and bill you accordingly. As we have to make sure that you are allowed to create a trip in our system for monitoring and in order to identify you, you need a so called “Token”. You have to order such a Token from us before creating your first trip.
Therefore, creating a trip in our system is the only API operation that has an impact on costs. All other operations are free. Costs are per trip: it doesn’t matter how many stops your trip has, how many ETA ( = Estimated Time of Arrival) subscribers there are per SCEMID, how many ETA calculations or notifications you will have etc.
If you got a SCEMID from somewhere (without Token), you can immediatly implement your own application on the PTV Drive&Arrive API without registering or anything like that. Just start to use the whole API (that does not require a Token) for free and withour access limitations.

Sounds great? Wanna see code?

Voilà: you can download code samples here  – this is an extract for you:

Creating a trip requires at least one stop. This is a JavaScript/node.js sample for creating a trip with two stops:

// define a trip with two stops
var tourData = {
   "tour": {
      "stops": [{            
            "coordinate": {"locationX": 8.61638888888889,
               "locationY": 49.81833333333333
            },
            "earliestArrivalTime": "2013-03-07T08:00:00.000+01:00",            
            "latestDepartureTime": "2013-03-07T08:00:00.000+01:00",           
            "serviceTimeAtStop": 0,
            "useServicePeriodForRecreation": true,
            "weightWhenLeavingStop": "6908,272",
            "customData": {}
         },
         {            
            "coordinate": {
               "locationX": 8.565,
               "locationY": 49.966111111111104
            },
            "earliestArrivalTime": "2013-03-07T08:29:08.000+01:00",
            "latestDepartureTime": "2013-03-07T08:44:08.000+01:00",
            "serviceTimeAtStop": 900,
            "useServicePeriodForRecreation": true,
            "weightWhenLeavingStop": "6835,772",
            "customData": {}
         }
      ],
      "vehicle": {
         "vehicleProfileID": "mg-truck-40t"
      },
      "drivers": [
         {
            "driverDescription": "driver 1",
            "raSTime": {
               "referenceTime": "2013-03-07T07:00:00.000+01:00",  
                    "periodDrivenSinceLastBreak": 0,
                    "periodDrivenSinceLastRest": 0,   
                    "currentIdlePeriod": 0,           
                    "isSplitBreak": false,         
                    "isSplitRest": false
            }
         }
      ],
      "customData": {
         "user": "node.js_test",
         "myid": "1"
      }
   }
};


// display response as JSON when response for Tour Create comes back
var callbackTourCreated = function (error, response, body) {
   console.log(JSON.stringify(body,null,1));   
};

var token = "<PUT YOUR TOKEN HERE>"; 

// create request object in node (if not available, try "npm install request" in command line before)
var request = require('request');
var options = {      
         url: 'https://driveandarrive-v1.cloud.ptvgroup.com/em/tour?source=PTVNODEJSCSBLOG&token=' + token,         
         method: 'POST',        
         json: tourData,      
         headers: {                       
            "content-type":"application/json"
         } 
      };

// send Tour Create request
request(options, callbackTourCreated);

In the JSON result you can find your SCEMIDs that may like this (extract for first stop)

{            
    "coordinate": {
       "locationX": 8.61638888888889,
       "locationY": 49.81833333333333
    },
    "earliestArrivalTime": "2013-03-07T08:00:00.000+01:00",            
    "latestDepartureTime": "2013-03-07T08:00:00.000+01:00",           
    "serviceTimeAtStop": 0,
    "useServicePeriodForRecreation": true,
    "weightWhenLeavingStop": "6908,272",
    "customData": {},
    "scemid":"X9X9X9X9X9"
},

The SCEMID for your first stop in this example is “X9X9X9X9X9”. No, what’s next? You have to send a positioning event to SCEMID that represents the next stop on your trip.

Given that you now drive to the stop with the SCEMID X9X9X9X9X9, you send a positioning event like that:

var eventData = {
   "event": {
      "eventType": "POSITION",
      "eventSubtype": "GPS",
      "eventSource": "PTVNODEJSCSBLOG",
      "eventPayLoad": {
         "heading": 122,
         "speed": 62.5,
         "accuracy": 23,
         "coordinate": {
            "locationX": 8.61660560080855,
            "locationY": 49.8182790029665
         },
         "timeStamp": "2013-07-03T07:10:31.023+0000"
      },
      "scemid": "X9X9X9X9X9"
   }
}

As you can see, there is no Token required for that operation. After sending the event, PTV Drive&Arrive knows about your position and if you send it regularly, we can re-calculate your ETA by taking rest and break times into account, as well as real-time traffic information, historical traffic information, physical road constraints for trucks and manually curated truck related blockings.

If you want to get informed about ETA on a certain stop, you have to subscrive to the SCEMID of that stop by code snippet like this one:

// create subscription for a callback URL.
// callback URL target is requestb.in 
// please refer to online documentation for this sample to understand the requestb.in URL
var subscriptionData = {
   "subscription": {
      "notificationType": "CALLBACK_URL",
      "notificationDescription": {
         "callBackURL":"http://requestb.in/1cifoit1",
         "ident": 'mytestX9X9X9X9X9'
      },
      "scemid": "X9X9X9X9X9"
   }
};

You can choose how to get notified: by callback URL, by a SignalR message or you can request the current ETA by API (some kind of polling). SignalR is the most flexible way as it works for mobile devices, server backends and for desktop clients.

Please note that the whole system works asynchronously, i.e. you can’t request an ETA calculation per request, but you have to subscribe to it. We will decide when to re-calculate an ETA and notify you if appropriate.

Now, you’re ready to go code-wise. Tomorrow, you can read what’s the great thing about this approach.

A report from the source: Monitoring trips in real-time

You certainly know what an Estimated Time of Arrival (ETA) is. And you thought about how great it would be to share your ETA in real-time with other people. Then, we have a solution for you: PTV Drive&Arrive – it enables you to monitor a trip in real-time concerning the ETA at all the stops. In addition, you can share this information easily among the whole transport chain in order to inform the shipper, your boss, the driver, the dock, the destination, who ever about the ETA in real-time.

How is PTV Drive&Arrive working?

The basic principle is quite straightforward:

  1. You create your trip in PTV Drive&Arrive. The trip consists of your stops with time windows, a vehicle type and some driver information about break and rest timesdave_beispiel_create_trip_SCEMID
  2. You get back IDs for the trip and every stop in the trip. We call these IDs “SCEMID”
  3. With a stop SCEMID, you can do two things:
    1. Send real-time status information to our system, e.g. the position. We need the position in order to update the ETA regularly
    2. Subscribe to notification per SCEMID. This enables you to distribute the SCEMIDs stop-wise so that every stop in your tour can see only the ETA that is related to it.dave_beispiel_optionen_position_senden

Sounds easy, doesn’t it? All this is provided by a simple RESTful JSON API, you can find here: https://driveandarrive-v1.cloud.ptvgroup.com/

We don’t want to flood you with information 🙂  Our tomorrow’s article is about authentication and billing – and you will get code, code, code. Don’t miss it!