Mobile SDK

iOS or Android

    SDK Features - Trips

    Info: Stellantis Mobile SDK for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall) is not publicly available for now.

    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.

    Within Stellantis Connected Vehicles SDK for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall), 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.

    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.

    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": null
    }
    
    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": null
    }
    
    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 - Subscribe: Trips #

    Once subscribed to pims.vehicle.connection & pims.vehicle.event 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": 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
    
    // 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

    4 - 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": null
    }
    

    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.

    Read energy Price

    The following api allows reading the energy price:

    1
    2
    3
    4
    5
    6
    
    pims.get("pims.vehicle.price",
      mapOf( /* parameters */
      Pair("vin", "VR1AB12C3D4567890"),
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    
    pims.get(api: "pims.vehicle.price", 
      parameters: [
      "vin": "VR1AB12C3D4567890",
      ]
    ) { (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
    8
    
    pims.set("pims.vehicle.price",
      mapOf( /* parameters */
      Pair("vin", "VR1AB12C3D4567890"),
      Pair("priceFuel", 1.27),
      Pair("priceElectric", 0.85)
      )
    ) { message -> /* handle message */ }
    
    1
    2
    3
    4
    5
    6
    7
    8
    
    pims.set(api: "pims.vehicle.price", 
      parameters: [
      "vin": "VR1AB12C3D4567890",
      "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": null
    }
    

    false