Mobile SDK

iOS or Android

API Reference - pims.vehicle.trips-merge

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 merging trips stored in the head-unit, can be undone using unmerge.

Input Parameter
Param name Description Type Unit/Values Example Required
vin

Vehicle Identification Number

String

n/a

VR1AB12C3D4567890 true
action

Filter mode, in this case merge.

String

merge

merge true
ids

Identifiers of the trips to merge.

List of Numbers

n/a

[418, 419] true
Output Data
Data name Description Type Unit/Values Example
trips

Resultant trips returned after merging.

Object

/
trips
 .alerts

List of JDA alerts actives during trip

List

n/a

25970
trips
 .category

Trip Category

String

n/a

WORK
trips
 .createdAt

Date (on UTC) of trip recovery

String

date yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

2021-03-30T08:18:20.143Z
trips
 .daysUntilNextMaintenance

Day until next maintenance alert

Number

n/a

27
trips
 .destination

Location setted on the Navigation system.

Object

/
trips
 .destination
  .altitude

Altitude elevation.

Number

m

1034
trips
 .destination
  .city

City name.

String

n/a

Paris
trips
 .destination
  .country

Country name.

String

n/a

France
trips
 .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
trips
 .destination
  .intersection

Intersection.

String

n/a

Rue de Rennes, Boulevard Saint-Germain
trips
 .destination
  .latitude

Latitude.

Number

n/a

8.74301
trips
 .destination
  .longitude

Longitude.

Number

n/a

8.74301
trips
 .destination
  .mileage

Mileage at moment location has been recovered.

Number

km

10762
trips
 .destination
  .postalCode

Postal code.

String

n/a

75019
trips
 .destination
  .quality

GPS signal quality.

Number

n/a

trips
 .destination
  .street

Street name.

String

n/a

Rue de Rennes
trips
 .destination
  .streetNumber

Street number.

String

n/a

16 Bis
trips
 .distance

Trip distance.

Number

km

42
trips
 .distanceToNextMaintenance

Distance until next maintenance alert.

Number

km

596
trips
 .end

Location at the end of the trip.

Object

/
trips
 .end
  .altitude

Altitude elevation.

Number

m

1034
trips
 .end
  .city

City name.

String

n/a

Paris
trips
 .end
  .country

Country name.

String

n/a

France
trips
 .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
trips
 .end
  .intersection

Intersection.

String

n/a

Rue de Rennes, Boulevard Saint-Germain
trips
 .end
  .latitude

Latitude.

Number

n/a

8.74301
trips
 .end
  .longitude

Longitude.

Number

n/a

8.74301
trips
 .end
  .mileage

Mileage at moment location has been recovered.

Number

km

10762
trips
 .end
  .postalCode

Postal code.

String

n/a

75019
trips
 .end
  .quality

GPS signal quality.

Number

n/a

trips
 .end
  .street

Street name.

String

n/a

Rue de Rennes
trips
 .end
  .streetNumber

Street number.

String

n/a

16 Bis
trips
 .fuelAutonomy

Automony for fuel engine.

Number

km

150
trips
 .fuelConsumption

Consumption for fuel engine in mm3 (10e6 mm3 = 1 liter).

Number

mm3

3242500
trips
 .fuelLevel

Percentage of fuel engine level.

Number

%

84
trips
 .id

Trip identifier (generated by the database).

Number

n/a

71
trips
 .maintenancePassed

Maintenance indicators (days or distance) have been exceeded.

Boolean

n/a

true
trips
 .mergedIds

List of trips composing the merged trip. Field present only if source is Merged.

List of Number

n/a

[2, 59, 70]
trips
 .otherEnergyAutonomy

Automony for electric engine.

Number

km

98
trips
 .otherEnergyConsumption

Consumption for electric engine.

Number

n/a

817
trips
 .otherEnergyDistance

Distance done with electric engine.

Number

km

48
trips
 .otherEnergyLevel

Percentage of electric engine level.

Number

%

20
trips
 .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
trips
 .priceElectric

Price set for electricity.

Number

n/a

0.85
trips
 .priceFuel

Price set for fuel.

Number

n/a

1.27
trips
 .source

Source of the trip.

Enum of String

- BTA

- Altran

- CEA

- Merge

- Unknown
CEA
trips
 .start

Location at the begining of the trip.

Object

/
trips
 .start
  .altitude

Altitude elevation.

Number

m

1034
trips
 .start
  .city

City name.

String

n/a

Paris
trips
 .start
  .country

Country name.

String

n/a

France
trips
 .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
trips
 .start
  .intersection

Intersection.

String

n/a

Rue de Rennes, Boulevard Saint-Germain
trips
 .start
  .latitude

Latitude.

Number

n/a

8.74301
trips
 .start
  .longitude

Longitude.

Number

n/a

8.74301
trips
 .start
  .mileage

Mileage at moment location has been recovered.

Number

km

10762
trips
 .start
  .postalCode

Postal code.

String

n/a

75019
trips
 .start
  .quality

GPS signal quality.

Number

n/a

trips
 .start
  .street

Street name.

String

n/a

Rue de Rennes
trips
 .start
  .streetNumber

Street number.

String

n/a

16 Bis
trips
 .travelTime

Duration on seconds of the trip.

Number

n/a

748
trips
 .tripNumber

Trip number on the vehicle.

Number

n/a

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

2101

Missing [PARAMETER] parameter

2102

Invalid [PARAMETER] parameter

2301

Need Basic Authentication (to get CVS token)

2371

Can’t merge trips with identifiers: [IDENTIFIERS LIST]

Code Example
1
2
3
4
5
6
7
8
9
10
11
pims.set("pims.vehicle.trips",
  mapOf( /* parameters */  
    Pair("", ""),
    Pair("action", "merge"),
    Pair("ids", "[418, 419]")
  ) 
) { message -> when (message["status"] as? String) {
      "SUCCEEDED" -> { }                          // handle succeeded status
      "FAILED" ->    { }                          // handle failed status
  } }
1
2
3
4
5
6
7
8
9
10
11
pims.set(api: "pims.vehicle.trips",
  parameters: [  
  "": "",
  "action": "merge",
  "ids": "[418, 419]"
  ]
  ) { (message) in 
    if message["status"] == "SUCEEDED"    { }    // handle succeeded status
    else if message["status"] == "FAILED" { }    // handle failed status
  } 
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
78
79
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": {
    "trips": [
      { // First 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":,
          "postalCode": 75019,
          "quality": ,
          "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": ,
          "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":,
          "postalCode": 75019,
          "quality": ,
          "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"
      },
      { /* Another Trip */ }
    ]
  }
}
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: 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: 2301 -------- */
{
  "transactionId": "953cfefb-bc72",
  "status": "FAILED",
  "error": {
    "code": 2301,
    "label": "Need Basic Authentication (to get CVS token)"
  }
}
/* -------- STATUS FAILED: 2371 -------- */
{
  "transactionId": "953cfefb-bc72",
  "status": "FAILED",
  "error": {
    "code": 2371,
    "label": "Can't merge trips with identifiers: [IDENTIFIERS LIST]"
  }
}