API Reference - pims.vehicle.trips

Edit

Info: Stellantis Mobile SDK for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall) is not publicly available for now.

Available since: v2.0.X

Component: TripNDrive

Security: Authentication is required.

Operation:

This API allows to receive events when a trip ends in the vehicle.

Subscribing to this API allows to receive an event when a new trips ends in the head-unit (destination reached or trip canceled).

It launch discover under VINs passed as parameters to connect and receive notifications about trips.

The unsubscribe api stop current connections and discover proccess and removes registration on trips notifications.

Input Parameter
Param name	Description	Type	Unit/Values	Example	Required
vins	List of vehicle’s VIN to subscribe with the GDPR rule.	Array of Objects	/	/
vins .vin	Vehicle Identification Number.	String	`n/a`	`VR1AB12C3D4567890`	`true`
vins .gdpr	GDRP setting for the associated vehicle’s vin. If `false`, when a trip is not receive it will be received until success when the device connect with the vehicle, if `true` the trip is lost.	boolean	`n/a`	`true`	`true`

Output Data
Data name	Description	Type	Unit/Values	Example
type	Inform if this Trip has been received just after a navigation ends in the vehicle (`Current`), or if the Trip is received after beeing `Stored` in the vehicle memory.	Enum of Strings	`- Current` `- Stored` `- Unknown`	`Current`
trip	Trip informations.	Object	/
trip .alerts	List of JDA alerts actives during trip	List	`n/a`	`25970`
trip .category	Trip Category	String	`n/a`	`WORK`
trip .createdAt	Date (on UTC) of trip recovery	String	`date yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`	`2021-03-30T08:18:20.143Z`
trip .daysUntilNextMaintenance	Day until next maintenance alert	Number	`n/a`	`27`
trip .destination	Location setted on the Navigation system.	Object	/
trip .destination .altitude	Altitude elevation.	Number	`m`	`1034`
trip .destination .city	City name.	String	`n/a`	`Paris`
trip .destination .country	Country name.	String	`n/a`	`France`
trip .destination .date	Date when the location has been recovered.	String	`date yyyy-MM-dd’T’HH:mm:ss.SSS’Z’`	`2020-11-02T02:50:12.208Z`
trip .destination .intersection	Intersection.	String	`n/a`	`Rue de Rennes, Boulevard Saint-Germain`
trip .destination .latitude	Latitude.	Number	`n/a`	`8.74301`
trip .destination .longitude	Longitude.	Number	`n/a`	`8.74301`
trip .destination .mileage	Mileage at moment location has been recovered.	Number	`km`	`10762`
trip .destination .postalCode	Postal code.	String	`n/a`	`75019`
trip .destination .quality	GPS signal quality.	Number	`n/a`
trip .destination .street	Street name.	String	`n/a`	`Rue de Rennes`
trip .destination .streetNumber	Street number.	String	`n/a`	`16 Bis`
trip .distance	Trip distance.	Number	`km`	`42`
trip .distanceToNextMaintenance	Distance until next maintenance alert.	Number	`km`	`596`
trip .end	Location at the end of the trip.	Object	/
trip .end .altitude	Altitude elevation.	Number	`m`	`1034`
trip .end .city	City name.	String	`n/a`	`Paris`
trip .end .country	Country name.	String	`n/a`	`France`
trip .end .date	Date when the location has been recovered.	String	`date yyyy-MM-dd’T’HH:mm:ss.SSS’Z’`	`2020-11-02T02:50:12.208Z`
trip .end .intersection	Intersection.	String	`n/a`	`Rue de Rennes, Boulevard Saint-Germain`
trip .end .latitude	Latitude.	Number	`n/a`	`8.74301`
trip .end .longitude	Longitude.	Number	`n/a`	`8.74301`
trip .end .mileage	Mileage at moment location has been recovered.	Number	`km`	`10762`
trip .end .postalCode	Postal code.	String	`n/a`	`75019`
trip .end .quality	GPS signal quality.	Number	`n/a`
trip .end .street	Street name.	String	`n/a`	`Rue de Rennes`
trip .end .streetNumber	Street number.	String	`n/a`	`16 Bis`
trip .fuelAutonomy	Automony for fuel engine.	Number	`km`	`150`
trip .fuelConsumption	Consumption for fuel engine in mm3 (10e6 mm3 = 1 liter).	Number	`mm3`	`3242500`
trip .fuelLevel	Percentage of fuel engine level.	Number	`%`	`84`
trip .id	Trip identifier (generated by the database).	Number	`n/a`	`71`
trip .maintenancePassed	Maintenance indicators (days or distance) have been exceeded.	Boolean	`n/a`	`true`
trip .mergedIds	List of trips composing the merged trip. Field present only if `source` is `Merged`.	List of Number	`n/a`	`[2, 59, 70]`
trip .otherEnergyAutonomy	Automony for electric engine.	Number	`km`	`98`
trip .otherEnergyConsumption	Consumption for electric engine.	Number	`n/a`	`817`
trip .otherEnergyDistance	Distance done with electric engine.	Number	`km`	`48`
trip .otherEnergyLevel	Percentage of electric engine level.	Number	`%`	`20`
trip .otherEnergyType	Energy Type used for the trip.	Enum of Number	`- 0: Trip was done with a vehicle without electric engine.` `- 1: Trip was done with a vehicle with electric engine.`	`1`
trip .priceElectric	Price set for electricity.	Number	`n/a`	`0.85`
trip .priceFuel	Price set for fuel.	Number	`n/a`	`1.27`
trip .source	Source of the trip.	Enum of String	`- BTA` `- Altran` `- CEA` `- Merge` `- Unknown`	`CEA`
trip .start	Location at the begining of the trip.	Object	/
trip .start .altitude	Altitude elevation.	Number	`m`	`1034`
trip .start .city	City name.	String	`n/a`	`Paris`
trip .start .country	Country name.	String	`n/a`	`France`
trip .start .date	Date when the location has been recovered.	String	`date yyyy-MM-dd’T’HH:mm:ss.SSS’Z’`	`2020-11-02T02:50:12.208Z`
trip .start .intersection	Intersection.	String	`n/a`	`Rue de Rennes, Boulevard Saint-Germain`
trip .start .latitude	Latitude.	Number	`n/a`	`8.74301`
trip .start .longitude	Longitude.	Number	`n/a`	`8.74301`
trip .start .mileage	Mileage at moment location has been recovered.	Number	`km`	`10762`
trip .start .postalCode	Postal code.	String	`n/a`	`75019`
trip .start .quality	GPS signal quality.	Number	`n/a`
trip .start .street	Street name.	String	`n/a`	`Rue de Rennes`
trip .start .streetNumber	Street number.	String	`n/a`	`16 Bis`
trip .travelTime	Duration on seconds of the trip.	Number	`n/a`	`748`
trip .tripNumber	Trip number on the vehicle.	Number	`n/a`	`7`
trip .updatedAt	Date (on UTC) of trip update.	String	`Date UTC yyyy-MM-dd’T’HH:mm:ss.SSS’Z’`	`2021-03-31 18:07:01 +0000`
trip .user	User’s email.	String	`email`	`uzumaqui.naruto@stellantis.com`
vin	Vehicle Identification Number	String	`n/a`	`VR1AB12C3D4567890`

Error
Error Code	Error Label
2001	Facade not initialized
2005	Duplicate command
2101	Missing [PARAMETER] parameter
2102	Invalid [PARAMETER] parameter
2344	[Component] not configured

          
              
                
              
              Request Kotlin
            

              
                
              
              Request Swift
            

        
/* Subscribe, see unsubscribe below */
pims.subscribe("pims.vehicle.trips",
  mapOf( /* parameters */  
    Pair("vins", "")
  ) 
) { message -> when (message["status"] as? String) {
      "SUCCEEDED" -> { }                          // handle succeeded status
      "FAILED" ->    { }                          // handle failed status
      "RESULT" ->    {
        if(message["error"] != null) { }            // handle error event code
        else { }                                 // handle result event code
      }
  } }

/* Unsubscribe */
pims.unsubscribe( "pims.vehicle.trips" /* no params */ )
/* Subscribe, see unsubscribe below */
pims.subscribe(api: "pims.vehicle.trips",
  parameters: [  
  "vins": ""
  ]
  ) { (message) in 
    if message["status"] == "SUCEEDED"    { }    // handle succeeded status
    else if message["status"] == "FAILED" { }    // handle failed status
    else if status == "RESULT" {
      if !message["error"].isEmpty { }            // handle error event code
      else { }                                    // handle result event code
    }
  } 

/* Unsubscribe */
pims.unsubscribe( api: "pims.vehicle.trips" /* no params */ )

          
              
                
              
              Succeeded
            

              
                
              
              Result
            

              
                
              
              Failed
            

        
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": null
}
// representation of the `result` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "RESULT",
  "result": {
    "type": "Current",
    "trip": {
      "alerts": [2, 59, 70],
      "category": "WORK",
      "createdAt": "2021-03-30T08:18:20.143Z",
      "daysUntilNextMaintenance": 27,
      "destination": {
        "altitude": 1034,
        "city": "Paris",
        "country": "France",
        "date": "2020-11-02T02:50:12.208Z",
        "intersection": "Rue de Rennes, Boulevard Saint-Germain",
        "latitude": 8.74301,
        "longitude": 8.74301,
        "mileage": 10762,
        "postalCode": 75019,
        "quality": 1,
        "street": "Rue de Rennes",
        "streetNumber": "16 Bis"
      },
      "distance": 42,
      "distanceToNextMaintenance": 596,
      "end": {
        "altitude": 1034,
        "city": "Paris",
        "country": "France",
        "date": "2020-11-02T02:50:12.208Z",
        "intersection": "Rue de Rennes, Boulevard Saint-Germain",
        "latitude": 8.74301,
        "longitude": 8.74301,
        "mileage": 10762,
        "postalCode": 75019,
        "quality": 1,
        "street": "Rue de Rennes",
        "streetNumber": "16 Bis"
      },
      "fuelAutonomy": 150,
      "fuelConsumption": 3242500,
      "fuelLevel": 84,
      "id": 71,
      "maintenancePassed": true,
      "mergedIds": "[2, 59, 70]",
      "otherEnergyAutonomy": 98,
      "otherEnergyConsumption": 817,
      "otherEnergyDistance": 48,
      "otherEnergyLevel": 20,
      "otherEnergyType": 1,
      "priceElectric": 0.85,
      "priceFuel": 1.27,
      "source": "CEA",
      "start": {
        "altitude": 1034,
        "city": "Paris",
        "country": "France",
        "date": "2020-11-02T02:50:12.208Z",
        "intersection": "Rue de Rennes, Boulevard Saint-Germain",
        "latitude": 8.74301,
        "longitude": 8.74301,
        "mileage": 10762,
        "postalCode": 75019,
        "quality": 1,
        "street": "Rue de Rennes",
        "streetNumber": "16 Bis"
      },
      "travelTime": 748,
      "tripNumber": 7,
      "updatedAt": "2021-03-31T18:07:01.737Z",
      "user": "uzumaqui.naruto@stellantis.com",
      "vin": "VR1AB12C3D45678909"
    }
  }
}
// representation of the `failed` dictionary objects messages as JSON

/* -------- STATUS FAILED: 2001 -------- */
{
  "transactionId": "953cfefb-bc72",
  "status": "FAILED",
  "error": {
    "code": 2001,
    "label": "Facade not initialized"
  }
}
/* -------- STATUS FAILED: 2005 -------- */
{
  "transactionId": "953cfefb-bc72",
  "status": "FAILED",
  "error": {
    "code": 2005,
    "label": "Duplicate command"
  }
}
/* -------- STATUS FAILED: 2101 -------- */
{
  "transactionId": "953cfefb-bc72",
  "status": "FAILED",
  "error": {
    "code": 2101,
    "label": "Missing [PARAMETER] parameter"
  }
}
/* -------- STATUS FAILED: 2102 -------- */
{
  "transactionId": "953cfefb-bc72",
  "status": "FAILED",
  "error": {
    "code": 2102,
    "label": "Invalid [PARAMETER] parameter"
  }
}
/* -------- STATUS FAILED: 2344 -------- */
{
  "transactionId": "953cfefb-bc72",
  "status": "FAILED",
  "error": {
    "code": 2344,
    "label": "[Component] not configured"
  }
}

Mobile SDK

iOS or Android

API Reference - pims.vehicle.trips