In 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.
