Mobile SDK

iOS or Android

API Reference - pims.vehicle.trips

Info: Stellantis Mobile SDK for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall) is not publicly available yet.
Available since: v2.0
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

Code Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/* 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 */ )
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/* 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 */ )
1
2
3
4
5
6
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
// 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"
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
// 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"
  }
}