Good to know > About > Trip Monitoring

Trip Monitoring

This section will explain how the different kind of trips will be monitored and what is expected as result.

 Trip starts at depot and we assume the trip will be executed in planned order and driver will send positions regularly.

Since all drivers will send events regularly, a trip starts with the first event to a stop.

Trip starts from a location other than a depot and we assume the trip will executed in planned order and driver will send position regularly.
e.g. driver start from home (has already loaded goods the day before)

Since trip starts from a location other than a first depot we could already check ETA for the first depot if driver sends events to stop[0]. All following stations will be informed about ETA violations in this case.

Driver will start with stop[0] and continue with stop[2] and stop[3] and finally go to stop[1], then stop[1] will only be monitored during events to stop[0] and events to stop[1] and certainly notify an ETA violation. The transport service provider can avoid this ETA violation by changing the tour via tour UPDATE method.

If driver sends only positions near arrival, incidents or other traffic related events will force (Nicht definierte Variable:Variables.Product)e to calculate an approximated position based on internal assumptions. If the internal calculated position leads to an ETA violation all subscriber will be informed.

 

Why I need a "token"?

A transport service provider has a trip planned with another trip planning system. This trip should have several stops (at least one) and for each stop there are coordinates available and time intervals given to monitor.

In order to transmit a trip to (Nicht definierte Variable:Variables.Product) you need a token. A token gives you the permission to create new monitoring orders in (Nicht definierte Variable:Variables.Product). You can buy a token from PTV Group. You will be billed per trip monitored.

Calling the method https://driveandarrive-v1.cloud.ptvgroup.com/em/tour?Token=<token> will transmit a trip to (Nicht definierte Variable:Variables.Product). Please refer to "/tour/ POST - create a tour (relevant to billing)" to get a detailed descriptions of the JSON object, including all necessary parameters. Example with three stops

{
  "tour": {
    "stops": [
    {
      "_stopDescription": "station 1 or depot",
      "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 kg"
    },
    {
      "_stopDescription": "station 2",
      "coordinate": {
      "locationX": 8.565,
      "locationY": 49.966111111111104
      },
      "earliestArrivalTime": "2013-03-07T08:29:20.000+01:00",
      "latestDepartureTime": "2013-03-07T08:44:20.000+01:00",
      "serviceTimeAtStop": 900,
      "useServicePeriodForRecreation": true,
      "weightWhenLeavingStop": "6835,772 kg"
    },
    {
      "_stopDescription": "station 3",
      "coordinate": {
        "locationX": 8.56861111111111,
        "locationY": 49.97972222222221
      },
      "earliestArrivalTime": "2013-03-07T08:49:10.000+01:00",
      "latestDepartureTime": "2013-03-07T09:04:10.000+01:00",
      "serviceTimeAtStop": 900,
      "useServicePeriodForRecreation": true,
      "weightWhenLeavingStop": "6790,496 kg"
    }
    ],
  "vehicle": {
      "vehicleProfileID": "mg-truck-40t"
    },
    "drivers": [
      {
        "driverDescription": "driver 57754",
        "raSTime": {
          "remainingDrivingTime": 7200,
          "nextBreakPeriod": 900,
          "drivingTimeFollowingNextBreak": 16200
        }
      }
    ],
    "customData": {
      "your_attribute" : "your_data"
    }
  }
}

What parameters each stop must have

This tour object can have multiple stops. Each stop has information about

Which format do coordinates have

These coordinates have to be in WGS 84 (lon, lat) for (x,y).

 

 

Which format do time stamps have

A time stamp in (Nicht definierte Variable:Variables.Product) has the following format YYYY-MM-DDThh:mm:ss.000+hh:mm in UTC.

In JavaScript you can create this format as follows:

function formatDate(myDate) 
{
   var myYear = myDate.getFullYear();
   var myMonth = myDate.getMonth()+1;
   var myDay = myDate.getDate();
   var myH = myDate.getHours();
   var myMin = myDate.getMinutes();
   var mySec = myDate.getSeconds();
   return myYear+'-'+(myMonth<10?('0'+myMonth):myMonth)+'-'+(myDay<10?('0'+myDay):myDay)+'T'+(myH<10?('0'+myH):myH)+':'+(myMin<10?('0'+myMin):myMin)+':'+(mySec<10?('0'+mySec):mySec)+'.000+0100'
}

In Java you can use SimpleDateFormat with a pattern "yyyy-MM-dd'T'HH:mm:ss.SSSZ"

In C# you can use a ToString("yyyy-MM-ddTHH\:mm\:ss.fffzzz")

Which vehicle profiles could be used

To specify a vehicle, the definition of an vehicle profile "vehicle" is needed. The following "vehicleProfileID"'s are possible:

If the Token got the WORLD mapCLuster configured, the following VehicleProfiles are available too.

The parameter "customData" should not be used for any personal related data as vehicle number or driver name to ensure the highest level of data protection. customData can be ciphered, but an API filtered on customData in forthcoming releases cannot be delivered.

Can vehicle profiles be changed

Currently there are no customer specific changes, e.g. "avoid toll" possible. Please contact support for further information.

Are there any details about vehicle profiles available

Vehicle profiles have a lot of parameters. These parameters must be coordinated each other. Please contact support for further information.

What information in response is important

As a response, you will get back an enriched object with (Nicht definierte Variable:Variables.Product) identifiers (SCEMID) you need later to send stop related data or to get stop related information via subscription. Please store these SCEMID's. For a tour with three stops, this would look like this: 

{
   "tour": {
      "stops": [
      {
         "coordinate": {
            "locationX": 8.000000,
            "locationY": 50.000000
         },
         "earliestArrivalTime": "2014-03-07T07:00:00.0000000+00:00",
         "latestDepartureTime": "2014-03-07T07:00:00.0000000+00:00",
         "serviceTimeAtStop": 0,
         "useServicePeriodForRecreation": true,
         "weightWhenLeavingStop": 0,
         "scemid": "S57SAAEKNH"
      },
      {
         "coordinate": {
            "locationX": 9.000000,
            "locationY": 49.000000
         },
         "earliestArrivalTime": "2014-03-07T07:29:20.0000000+00:00",
         "latestDepartureTime": "2014-03-07T07:44:20.0000000+00:00",
         "serviceTimeAtStop": 900,
         "useServicePeriodForRecreation": true,
         "weightWhenLeavingStop": 0,
         "scemid": "P27SAAEKNH"
      },
      {
         "coordinate": {
            "locationX": 8.000000,
            "locationY": 50.000000
         },
         "earliestArrivalTime": "2014-03-07T07:49:10.0000000+00:00",
         "latestDepartureTime": "2014-03-07T08:04:10.0000000+00:00",
         "serviceTimeAtStop": 900,
         "useServicePeriodForRecreation": true,
         "weightWhenLeavingStop": 0,
         "scemid": "PJ7SAAEKNH"
      },
      ],
      "vehicle": {
         "vehicleProfileID": "mg-truck-40t"
      },
      "drivers": [
      {
         "driverDescription": "driver 1",
         "raSTime": {
            "remainingDrivingTime": 7200,
            "nextBreakPeriod": 900,
            "drivingTimeFollowingNextBreak": 16200
         }
      }
      ],
      "customData": {
         "your_attribute" : "your_data"
      },
      "scemid": "KL7SAAEKNH"
   },
   "responseStatus":{
      "errorCode":"SUCCESS",
      "message":"000000000000"
   }
}

At the end you have 4 SCEMIDs for a 3-stop tour:

 

 

© 2022 PTV Planung Transport Verkehr GmbH | Imprint

Get in Contact