Journeys

The Journey module is used to record journey details, of most direct use within the API are the speed records.

The usual authentication requirements apply to all areas of this module.

 

 

GPX File Import

The API supports import of GPS eXchange (GPX) files. In order to provide a file for import, a request must be made using POST to

/journey/import/{vehicle identifier}

All journeys must be recorded against a specific vehicle.

Note: Due to the intensive nature of this function, The GPX file will not be imported at the time of the request, but an import task will be queued.

The response will therefore confirm whether or not the task was successfully queued and provide the JobID. See the Queue submodule documentation for information on checking the status of a Queued task.

The GPX file should be submitted as a HTML form field, the field in question should be 'subfile'.

The request should therefore be of the type 'multipart/form-data'.

Data Filtering and Manipulation

By default, the system will use 'SmartTrack'. If a trackpoint occurs more than 1 hour (3600 seconds) after the previous trackpoint, a new GPS track will automatically be started.

To disable this, the JSON request should include the key/value

smartTrack: false

The smartTrack threshold can also be adjusted, the value should be passed in seconds, so to set to 2 hours, we'd send

smartTrackThreshold: 7200

It is also possible to suppress certain information. For example, if the user does not want their GPS position to be recorded within the system, it can be suppressed. To suppress any of the following, an array called suppress should be submitted as part of the request

Valid values are;

  • speed
  • location
  • elevation

Although GPXIngest supports suppression of dates, the Database schema doesn't allow for this, therefore any attempts to suppress date will lead to the import being rejected.

Example Call

# curl -F "subfile=@importfile.gpx;type=text/xml" \
-H "X-VEHMAN-KEY: Test: `echo {mykey} | sha1sum | awk -F\ '{print $1}'`" \
-H "X-VEHMAN-USER: {myuserkey}" \
{apiurl}/journey/import/{vehicleidentifier}



Example Response

{
"timestamp":1378824115,
"response":{
"status":"Queued",
"JobNumber":4
},
"errors":null,
"error":0
}

 

 

JSON File Import

When the API receives a GPS eXchange (GPX) file, it processes it and creates a GPXIngest Object (See https://github.com/bentasker/PHP-GPX-Ingest/).

If preferred, (for example because you intend to suppress location data and don't want to send that data across the network at all) a JSON encapsulate GPXIngest object can be submitted instead. The necessary JSON can be extracted from GPXIngest with the method getJSON().

The JSON string should be written to a file, inclusion in the request is NOT supported.
In order to provide a file for import, a request must be made using POST to

/journey/importjson/{vehicle identifier}

All journeys must be recorded against a specific vehicle.

Note: Due to the intensive nature of this function, The JSON file will not be imported at the time of the request, but an import task will be queued.

The response will therefore confirm whether or not the task was successfully queued and provide the JobID. See the Queue submodule documentation for information on checking the status of a Queued task.

The JSON file should be submitted as a HTML form field, the field in question should be 'subfile'.

The request should therefore be of the type 'multipart/form-data'.

Example Call

# curl -F "subfile=@importfile.json;type=text/json" \
-H "X-VEHMAN-KEY: {mykey}" \
-H "X-VEHMAN-USER: {myuserkey}" \
{apiurl}/journey/importjson/{vehicleidentifier}

 

Example Response

{
"timestamp":1378824216,
"response":{
"status":"Queued",
"JobNumber":5
},
"errors":null,
"error":0
}

 

 

List Journeys

To retrieve of all journeys recorded for a specific vehicle, place a call to

/journey/listjourneys/{vehicle identifier}

A record will be returned for every track recorded (as 'journeys' may include more than one track).

Example Response

Note: The list of stats returned may vary from those shown below - new statistics are being implemented

{
"timestamp":1378830060,
"response":{
"row0":{
"journeyID":"1",
"trackID":"2",
"journeyDuration":"5190",
"start":"1377581448",
"end":"1377586638",
"avgSpeed":"55.83",
"maxSpeed":"70",
"minSpeed":"0",
"modalSpeed":"68",
"map":"http:\/\/example.com\/chart\/journeymap\/1\/1\/2"
}
},
"errors":null,
"error":0
}

 

Journey Path Details

Use this section of the module to retrieve full details for a specific journey. Depending on the parameters used when the source GPX file was ingested, this will include all or some of the following

  • latitude
  • longitude
  • Speed
  • Elevation
  • Time
  • Journey Track ID

In order to place a request to this function, you must provide both the correct vehicle identifier and a valid Journey ID

/journey/journeytrack/{vehicle identifier}/{journey id}/{track id} - Optional

So both of the following would be valid requests to retreive the track points for a full journey

/journey/journeytrack/1/1
/journey/journeytrack/A123%20DAL/1


Whilst the following would be valid requests to retrieve track points for a Track with an ID of 6 within journey 1.

/journey/journeytrack/1/1/6 /journey/journeytrack/A123%20DAL/1/6

Note: Track ID's are completely independant of Journey ID's, so no two journeys will contain a segment with the same ID.

 

Example Response

{
"timestamp":1378830787,
"response":{
"row0":{
"TrackPtID":"1",
"segmentID":"1",
"JourneyID":"1",
"VehicleID":"1",
"lat":"52.129725",
"lon":"1.415779",
"time":"1377581448",
"speed":"0 mph",
"speedint":"0",
"elevation":"62"
},
"row1":{
"TrackPtID":"2",
"segmentID":"1",
"JourneyID":"1",
"VehicleID":"1",
"lat":"52.129744",
"lon":"1.415823",
"time":"1377581457",
"speed":"0 mph",
"speedint":"0",
"elevation":"68"
},
},
"errors":null,
"error":0
}