Mobile SDK

iOS or Android

    API Reference - pims.vehicle.trips-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:
    GET
    pims.vehicle.trips - trips
    Edit

    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"
  }
}