Mobile SDK

iOS or Android

API Reference - pims.vehicle.trips-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 retrieve trips from the local storage.

See SUBSCRIBE pims.vehicle.trips for more informations about receiving trips in local storage.

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

Action name, in this case trips.

String

trips

trips true
vin

Vehicle Identification Number

String

n/a

VR1AB12C3D4567890 true
limit

Number of results (maximum). Required if offset != null.

Int

n/a

100 false
offset

Position of the first result. Required if limit != null.

Int

n/a

10 false
from

Trip’s with start datetime greater or equals

String

date time

2020-04-06T17:15:00Z false
to

Trip’s with end datetime less or equals

String

date time

2020-04-06T17:36:00Z false
category

Category to filter (from user custom categories).

String

n/a

daily false
query

Custom SQL query using trips fields.

String

n/a

endmileage IS NOT NULL false
orderBy

Select a field from the trip format to order the list of results. See response for available fileds. By default order is id.

String

Fields of Trip.

date false
order

Sorts the records in descending or ascending order, asc by default.

String

- asc

- desc
asc false
Output Data
Data name Description Type Unit/Values Example
trips

Trips informations.

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

Code Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
pims.get("pims.vehicle.trips",
  mapOf( /* parameters */  
    Pair("action", "trips"),
    Pair("", ""),
    Pair("limit", "100"),
    Pair("offset", "10"),
    Pair("from", "2020-04-06T17:15:00Z"),
    Pair("to", "2020-04-06T17:36:00Z"),
    Pair("category", "daily"),
    Pair("query", "endmileage IS NOT NULL"),
    Pair("orderBy", "date"),
    Pair("order", "asc")
  ) 
) { 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
12
13
14
15
16
17
18
pims.get(api: "pims.vehicle.trips",
  parameters: [  
  "action": "trips",
  "": "",
  "limit": "100",
  "offset": "10",
  "from": "2020-04-06T17:15:00Z",
  "to": "2020-04-06T17:36:00Z",
  "category": "daily",
  "query": "endmileage IS NOT NULL",
  "orderBy": "date",
  "order": "asc"
  ]
  ) { (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
// 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"
  }
}