Mobile SDK

iOS or Android

SDK Features - Trips

Info: Stellantis Mobile SDK is not publicly available.

Security: Trips require the following security schemes to be valid

Connectivity: this feature is available usingBluetooth connectivity

  • πŸ”— The vehicle & the device must be paired with Bluetooth.
  • 🚘 The user must stand inside or close to the vehicle.

References: check-out πŸ“ Trips component list of APIs.

Within Stellantis Connected Vehicles SDK, Trips are records of the vehicle activity during a navigation πŸ—Ί

You can subscribe to Trips when the mobile phone is connected to the vehicle through Bluetooth. Then, when a navigation will end in the vehicle infotainment system, a record of the Trip will be saved in a dedicated local database of the mobile phone.

These records include information about navigation (start, end, destination), alerts, maintenance, autonomy, and consumption.

navigation-system

Features #

  • πŸ”” First of all, you need to subscribe to Trips:
    • This is mandatory in order to receive ending navigation as Trips in the local database of the mobile phone.
    • An event will also be received each time a Trips is received in the mobile phone database.
  • πŸ’Ύ Then, you will be able to work with this local database using the following APIs:
  • πŸ”‹ It’s also possible to set default energy price.
  • πŸ›  Statistics APIs allow retrieving figures about vehicle use during a period of time.

Subscribe to new Trips #

If the mobile phone is connected with the vehicle using Bluetooth, it’s possible to subscribe to Trips. Once the service is enabled, when a navigation ends in the vehicle infotainment system:

  • The Trip will be stored in the mobile phone local database.
  • You’ll receive an event with the Trip data.

Follow this tutorial to subscribe to vehicle Trips:

1 - Subscribe: Connection Info #

First of all, you should subscribe to pims.vehicle.connection. This api does not connect the vehicle with the device, but is made to subscribe to upcoming connection events.

It will send events when the vehicle connect/disconnect, see subscribe - pims.vehicle.trips.

Note: Starting from SDK version 2.3, this API has been transferred from Trips to Bluetooth Connectivity component. Check-out the changelog.

1
2
3
4
5
6
/* Subscribe, see unsubscribe below */
pims.subscribe("pims.vehicle.connection"
) { message -> /* handle message */ }

/* Unsubscribe */
pims.unsubscribe( "pims.vehicle.connection" /* no params */ )
1
2
3
4
5
6
/* Subscribe, see unsubscribe below */
pims.subscribe(api: "pims.vehicle.connection"
) { (message) in /* handle message */ }

/* Unsubscribe */
pims.unsubscribe( api: "pims.vehicle.connection" /* no params */ )
1
2
3
4
5
6
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": { }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
// representation of the `result` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "RESULT",
  "result": {
    "vin": "VR1AB12C3D4567890",
    "status": "Connected",
    "protocol": "CEA",
    "model": "NAC",
    "version": "1.0.2",
    "privacy": "Full"
  }
}

false

2 - Subscribe: Errors #

Then, you should subscribe to pims.vehicle.event - tripNDrive. It’s not mandatory, but this API will trigger events when an error occurs during the reception of a Trip.

Again, this api does not connect the vehicle with the device, but is made to subscribe to upcoming events.

1
2
3
4
5
6
7
8
9
/* Subscribe, see unsubscribe below */
pims.subscribe("pims.vehicle.event",
  mapOf( /* parameters */
  Pair("actionType", "tripNDrive")
  )
) { message -> /* handle message */ }

/* Unsubscribe */
pims.unsubscribe( "pims.vehicle.event" /* no params */ )
1
2
3
4
5
6
7
8
9
/* Subscribe, see unsubscribe below */
pims.subscribe(api: "pims.vehicle.event", 
  parameters: [
  "actionType": "tripNDrive"
  ]
) { (message) in /* handle message */ }

/* Unsubscribe */
pims.unsubscribe( api: "pims.vehicle.event" /* no params */ )
1
2
3
4
5
6
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": { }
}
1
2
3
4
5
6
7
8
// representation of the `result` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "RESULT",
  "result": {
    "event": "CEAError <error_code>-<error_subcode> : <error_text>"
  }
}

false

3 - Start Service #

Before subscribing to Trips, it’s mandatory to activate bluetooth service using the following API:

1
2
3
4
5
6
7
8
9
10
11
pims.set("pims.vehicle.service",
  mapOf( /* parameters */
  Pair("action", "start"),
  Pair("service", "bluetooth"),
  Pair("vins", listOf(
    mapOf<String, Boolean>("VR1AB12C3D4567890", true),
    mapOf<String, Boolean>("VR1AB12C3D4567891", false)
  )
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
pims.set(api: "pims.vehicle.service", 
  parameters: [
  "action": "start",
  "service": "bluetooth",
  "vins": [
    {
      "vin": "VR1AB12C3D4567890",
      "gdpr": true
    },
    {
      "vin": "VR1AB12C3D4567891",
      "gdpr": false
    }
  ]
  ]
) { (message) in /* handle message */ }
1
2
3
4
5
6
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": { }
}

false

Note: This API has been released in SDK version 2.3. Before v2.3, subscribe-pims.vehicle.trips would include a VIN parameter. Check-out the changelog.

4 - Subscribe: Trips #

Once subscribed to pims.vehicle.connection & pims.vehicle.event and pims.vehicle.service has been activated, you can subscibe to pims.vehicle.trips. Subscribing to this API will:

  • Populate the Trip local database. Navigation that ends will be stored in the local database as Trips. You can access the database using the dedicated APIs.
  • Trigger a new event with information about the Trip each time a navigation ends.

This API allows subscribing to multiples VINs. If you need to add more VIN to this subscribe, you should unsubscribe first and make a new API request with the updated list.

Trip reception error: when the trip is not successfully received right away after being emitted by the vehicle. The vehicle behavior depends on the gdpr parameter:

  • false: the trip is stored in the vehicle memory. The vehicle will retry to send the trip each time the device is connected, until the trip is successfully received.
  • true: the trip is deleted right away.

Trip type: the type field 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 (check-out Trip reception error).

New Phone: any phone connected for the first time to a vehicle will trigger the deletion of all stored Trip(s) in the vehicle memory.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/* Subscribe, see unsubscribe below */
pims.subscribe("pims.vehicle.trips",
  mapOf( /* parameters */
  Pair("vins", mapOf(
    mapOf(
      Pair("vin", "VR1AB12C3D4567890"),
      Pair("gdpr", true))
    ),
    mapOf(
      Pair("vin", "VR1AB12C3D4567891"),
      Pair("gdpr", false)
    )
  )
  )
) { message -> /* handle message */ }

/* Unsubscribe */
pims.unsubscribe( "pims.vehicle.trips" /* no params */ )
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/* Subscribe, see unsubscribe below */
pims.subscribe(api: "pims.vehicle.trips", 
  parameters: [
  "vins": [
    [
      "vin": "VR1AB12C3D4567890",
      "gdpr": true
    ],
    [
      "vin": "VR1AB12C3D4567891",
      "gdpr": false
    ]
  ]
  ]
) { (message) in /* handle message */ }

/* 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": { }
}
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
// 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"
    }
  }
}

false

5 - Subscribe: Check subscribed vins #

If you want to retrieve the list of VINs subscribed to Subscribe pims.vehicle.trips in the previous step, you can use the following API:

1
2
3
pims.get("pims.vehicle.vins"
) { message -> /* handle message */ }
1
2
3
pims.get(api: "pims.vehicle.vins"
) { (message) in /* handle message */ }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": [
    {
      "vin": "VR1AB12C3D45678908",
      "gdpr": true
    },
    {
      "vin": "VR1AB12C3D45678909",
      "gdpr": false
    }
  ]
}

false

Retrieve Local Trips #

Once the Trip is stored in the mobile’s local storage, you can access using the following methods:

Trip ID

Retrieve Trip one by one using Trip unique ID.

1
2
3
4
5
6
7
8
pims.get("pims.vehicle.trip",
  mapOf( /* parameters */
  Pair("vin", "VR1AB12C3D4567890"),
  Pair("action", "id")
  Pair("id", "<trip_id>")
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
8
pims.get(api: "pims.vehicle.trip", 
  parameters: [
  "vin": "VR1AB12C3D4567890",
  "action": "id",
  "id": "<trip_id>"
  ]
) { (message) in /* handle message */ }
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
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": {
    "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"
    }
  }
}

false

Trip Range

Retrieve Trip one by one using range (first or last trip).

1
2
3
4
5
6
7
8
pims.get("pims.vehicle.trip",
  mapOf( /* parameters */
  Pair("vin", "VR1AB12C3D4567890"),
  Pair("action", "range"),
  Pair("range", "last")
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
8
pims.get(api: "pims.vehicle.trip", 
  parameters: [
  "vin": "VR1AB12C3D4567890",
  "action": "range",
  "range": "last"
  ]
) { (message) in /* handle message */ }
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
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": {
    "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"
    }
  }
}

false

List of Trips

Retrieve a List of Trips that meet the following parameters:

  • from: include Trip starting after this date.
  • to: include Trip ending before this date.
  • offset: position of the first Trip.
  • limit: postition of the latest Trip.
  • category: filter based on the user categories.
  • query: sql query on Trip fields.

Then you can select the order:

  • orderBy: select on which field ordering the resut. Default is id.
  • order: select ascending or descending order. Default is asc.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
pims.get("pims.vehicle.trips",
  mapOf( /* parameters */
  Pair("vin", "VR1AB12C3D4567890"),
  Pair("action", "trips"),
  Pair("limit", "20"),
  Pair("offset", "40"),
  Pair("from", "2020-04-06T17:15:00Z"),
  Pair("to", "2020-04-06T17:36:00Z"),
  Pair("category", "<custom_user_category>"),
  Pair("query", "<sql_request>")
  Pair("orderBy", "daysUntilNextMaintenance")
  Pair("order", "desc")
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
pims.get(api: "pims.vehicle.trips", 
  parameters: [
  "vin": "VR1AB12C3D4567890",
  "action": "trips",
  "limit": "20",
  "offset": "40",
  "from": "2020-04-06T17:15:00Z",
  "to": "2020-04-06T17:36:00Z",
  "category": "<custom_user_category>",
  "query": "<sql_request>,
  "orderBy": "daysUntilNextMaintenance,
  "order": "desc
  ]
) { (message) in /* handle message */ }
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
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": {
    "trips": [ // The Response is a List of 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": 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"
      },
      {  // Second 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"
      }
    ]
  }
}

false

Edit & Remove Local Trips #

Edit

Editing a Trip will modify it in the local storage. This is the data you can edit:

  • Trip category
  • Price of fuel
  • Price of electricity
1
2
3
4
5
6
7
8
9
10
11
12
13
pims.set("pims.vehicle.trips",
  mapOf( /* parameters */
  Pair("vin", "VR1AB12C3D4567890"),
  Pair("action", "edit"),
  Pair("ids", mapOf(3, 9, 67)),
  Pair("data", mapOf(
    Pair("category", "WORK"),
    Pair("priceFuel", 1.25),
    Pair("priceElectric", 0.89),
  ))
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
8
9
10
11
12
13
pims.set(api: "pims.vehicle.trips", 
  parameters: [
  "vin": "VR1AB12C3D4567890",
  "action": "edit",
  "ids": [3, 9, 12],
  "data": [
    "category": "WORK",
    "priceFuel": 1.25,
    "priceElectric": 0.89,
  ]
  ]
) { (message) in /* handle message */ }
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
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": {
    "trips": [ // The Response is a List of 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": 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"
      },
      {  // Second 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"
      }
    ]
  }
}

false

Remove

Remove Trips from the mobile phone local storage using their ID(s):

1
2
3
4
5
6
7
8
pims.set("pims.vehicle.trips",
  mapOf( /* parameters */
  Pair("vin", "VR1AB12C3D4567890"),
  Pair("action", "remove"),
  Pair("ids", mapOf(3, 9, 67))
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
8
pims.set(api: "pims.vehicle.trips", 
  parameters: [
  "vin": "VR1AB12C3D4567890",
  "action": "remove",
  "ids": [3, 9, 12]
  ]
) { (message) in /* handle message */ }
1
2
3
4
5
6
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": { }
}

false

This API always return result: null.

Import & Export Local Trips #

Import

Import Trips from a file to the local storage of the mobile phone. This feature is useful in case of changing device.

1
2
3
4
5
6
7
pims.set("pims.vehicle.trips",
  mapOf( /* parameters */
  Pair("action", "import"),
  Pair("file", "<file_name>")
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
pims.set(api: "pims.vehicle.trips", 
  parameters: [
  "action": "remove",
  "file": "<file_name>"
  ]
) { (message) in /* handle message */ }
1
2
3
4
5
6
7
8
9
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": {
    "total": 42,
    "imported": 23
  }
}

false

Export

Export Trips from the local storage of the mobile phone to a file:

1
2
3
4
5
6
7
pims.set("pims.vehicle.trips",
  mapOf( /* parameters */
  Pair("action", "export"),
  Pair("ids", mapOf(3, 9, 67))
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
pims.set(api: "pims.vehicle.trips", 
  parameters: [
  "action": "export",
  "ids": [3, 9, 12]
  ]
) { (message) in /* handle message */ }
1
2
3
4
5
6
7
8
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": {
    "file": "<data of exported trips>"
  }
}

false

Merge & Unmerge Local Trips #

Merge

Merge Trips in the local storage of the mobile phone. The Trip resulting from the merge will look like the following:

  • start of the first trip of the list
  • end & destination of the last trip of the list
  • an average of distance, travelTime & fuelConsumption
  • weighted average by distance of priceFuel & priceElectric
  • other values: last trip of the list
1
2
3
4
5
6
7
8
pims.set("pims.vehicle.trips",
  mapOf( /* parameters */
  Pair("vin", "VR1AB12C3D4567890"),
  Pair("action", "merge"),
  Pair("ids", mapOf(3, 9))
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
8
pims.set(api: "pims.vehicle.trips", 
  parameters: [
  "vin": "VR1AB12C3D4567890",
  "action": "merge",
  "ids": [3, 9]
  ]
) { (message) in /* handle message */ }
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
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": {
    "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"
    }
  }
}

false

Unmerge

Unmerge Trip in the local storage of the mobile phone, the Trip should have been merged before using the previous API.

1
2
3
4
5
6
7
8
pims.set("pims.vehicle.trips",
  mapOf( /* parameters */
  Pair("vin", "VR1AB12C3D4567890"),
  Pair("action", "unmerge"),
  Pair("id", 3)
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
8
pims.set(api: "pims.vehicle.trips", 
  parameters: [
  "vin": "VR1AB12C3D4567890",
  "action": "unmerge",
  "ids": 3
  ]
) { (message) in /* handle message */ }
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
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": {
    "trips": [ // The Response is a List of 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": 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"
      },
      {  // Second 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"
      }
    ]
  }
}

false

Energy Price #

In the Trip data, the price of the energy is taken in account.

Before accessing working on trip energy price with get-pims.vehicle.price and set-pims.vehicle.price, you must select vehicle using this API:

1
2
3
4
5
6
pims.set("pims.vehicle.vin",
  mapOf( /* parameters */
  Pair("vin", "VR1AB12C3D45678909")
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
pims.set(api: "pims.vehicle.vin", 
  parameters: [
  "vin": "VR1AB12C3D45678909"
  ]
) { (message) in /* handle message */ }
1
2
3
4
5
6
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": { }
}

false

Note: This API has been released in SDK version 2.3. Before v2.3, get-pims.vehicle.price and set-pims.vehicle.price would include a VIN parameter. Check-out the changelog.

Read energy Price

The following api allows reading the energy price:

1
2
3
pims.get("pims.vehicle.price"
) { message -> /* handle message */ }
1
2
3
pims.get(api: "pims.vehicle.price"
) { (message) in /* handle message */ }
1
2
3
4
5
6
7
8
9
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": { 
    "priceFuel": 1.27,
    "priceElectric": 0.85
  }
}

false

Change energy Price

The following api allows changing the energy price:

1
2
3
4
5
6
7
pims.set("pims.vehicle.price",
  mapOf( /* parameters */
  Pair("priceFuel", 1.27),
  Pair("priceElectric", 0.85)
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
pims.set(api: "pims.vehicle.price", 
  parameters: [
  "priceFuel": 1.27,
  "priceElectric": 0.85
  ]
) { (message) in /* handle message */ }
1
2
3
4
5
6
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": { }
}

false

Statistics #

Trips component allows retrieving sum of data about trips available in the local database, you can request the following figures:

  • πŸ›’ Consumption of energy.
  • πŸ“ Distance traveled.
  • πŸ•› Duration of the Trips.

Theses API will calculate the sum of requested data during a certain period of time (day, week, month, year, beginning), it can help in creating user statistics.

Example for Trips Consumption:

1
2
3
4
5
6
7
8
pims.get("pims.vehicle.statistics",
  mapOf( /* parameters */
  Pair("action", "consumption"),
  Pair("vin", "VR1AB12C3D4567890"),
  Pair("period", "begining")
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
8
pims.get(api: "pims.vehicle.statistics", 
  parameters: [
  "action": "consumption",
  "vin": "VR1AB12C3D4567890",
  "period": "begining"
  ]
) { (message) in /* handle message */ }
1
2
3
4
5
6
7
8
9
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": { 
    "fuelConsumtion": 3600,
    "otherEnergyConsumtion": 3600
  }
}

false