Smart Driving

These endpoints are intended for customers who use ViriCiti's Smart-Driving tool. All requests require an x-api-key header containing an api-key. Additionally when making POST requests the user needs to have admininstrative rights.

Access Control List

Exposes a user's current access to driver groups and optionally the group's drivers

GET https://sdk.viriciti.com/api/v1/smart-driving/config

Query Parameter	Description
full	When true, driverGroups will be populated with the group's drivers (optional)

Examples

GET https://sdk.viriciti.com/api/v1/smart-driving/config?full=true

Response:

{
  "userType": "administrator|user|driver",
  "driverId": "driverId"|null,
  "driverGroups": [
    {
      "_id": UID,
      "title": "Driver Group 1",
      "drivers": [
        "123456"
        ...
      ]
    },
    ...
  ]
}

Drivers

GET /drivers

GET https://sdk.viriciti.com/api/v1/smart-driving/drivers

Query Parameter	Description
firstName	Query drivers with this first-name (optional)
lastName	Query drivers with this last-name (optional)
email	Query drivers with this email (optional)

Returns an array of drivers

GET /drivers/:driverId

GET https://sdk.viriciti.com/api/v1/smart-driving/drivers/:driverId

URL Parameter	Description
driverId	Unique identifier of the driver.

Returns a single driver

PATCH /drivers/:driverId

PATCH https://sdk.viriciti.com/api/v1/smart-driving/drivers/:driverId

Body	Description
firstName	Driver's first name (optional)
lastName	Driver's last name (optional)
email	Driver's email (optional)
language	Driver's language. If a user account exists, the users language will be changed as well (user needs to log out and back in for the changes to take effect). One of [de, en, fr, nl] (optional)

Returns the updated driver

Drivergroups

These endpoints allow for retrieving information about the drivergroup entities. All endpoints use the current state of drivers unless stated otherwise.

GET /drivergroups

GET https://sdk.viriciti.com/api/v1/smart-driving/drivergroups

Query Parameter	Description
driver	Query driversgroups that contain this driverId.

Returns an array of driver groups

GET /drivergroups/:_id

GET https://sdk.viriciti.com/api/v1/smart-driving/drivergroups/:_id

URL Parameter	Description
_id	Unique identifier of the drivergroup, please be aware that this is not the title of the group as seen in the web-application.

Returns a single driver group

Dynamic Driver Composition

POST /driver-upload/:type

This endpoint enables clients to upload driver information together with which groups they are currently in. Important: The upload will overwrite the current state of your drivers and groups. Drivers are always inserted and never deleted through this endpoint. Driver-groups will be deleted, when not present in an upload. Currently we do not support emptying driver groups through this endpoint. To reiterate, the endpoint expects the user to always upload the complete current state of drivers and their driver-groups. It is possible to change driver fields through this endpoint. E.g. change the email or name field. The reasoning for this behavior is that this allows for one single upload containing all state, Instead of having to make multiple requests to get to the same state e.g. using CRUD REST endpoints.

User provisioning

This API allows for simple user provisioning. When loginType is "password" a ViriCiti user account will be created and an activation email will be sent to the user in the same way as would happen when an administrator creates a user through the ViriCiti Portal UI. When loginType is "sso" a ViriCiti user account will be created, the user will not receive an activation email, but is now directly able to log in through a connected single sign on mechanism. E.g. SAML. Important!: This API does not support the deletion of ViriCiti user accounts.

Endpoint

POST https://sdk.viriciti.com/api/v1/smart-driving/driver-upload/:type

Path Parameter	Description
type	Format of upload, supported types are json and csv (required)

Important! The correct use of a Content-Type header (application/json or text/csv) is required. Additionally the maximum request body size is limited to 10MB.
Important! The API expects UTF-8 encoded content.

Query Parameter	Description
timeZone	The time-zone that will be linked to the drivers, input is validated (required)
language	The language that will be linked to the drivers, supported values are en or nl (required)
execute	By default the API will do a dry-run, as result the API will return a JSON object representing a list of drivers, driverGroups and their structure. This allows for validation of how the input is parsed before it is inserted into ViriCiti's System. Opposed to a 'dry-run' the request will be executed if execute=true is provided. In this case the API returns a status of 200 if the insertion was succesful. (optional)

Validations

JSON Schema

Incoming requests will be validated against a (simple) JSON Schema, to guarantee the quality of the data. Errors result in a status code 400 and will be returned to the client. Inside the body will be information about why the input didn't pass validation. CSV requests will internally be parsed to JSON and will be validated against the same schema.

{
  "type":     "array",
  "minItems": 1,
  "items":  [
    {
      "type":       "object",
      "properties": {
        "firstName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "driverId": {
          "type": "string"
        },
        "driverGroup": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "loginType": {
          "type": "string",
          "enum": [ "password", "sso", "none" ]
        }
      },
      "required": [
        "firstName",
        "lastName",
        "driverId",
        "driverGroup"
      ]
    }
  ]
}

Data Integrity

If the input passes the schema validation, the integrity of the data itself will be inspected. We do the following checks:

• email The email field is a unique field. This will not be validated by the JSON schema, but will be instead validated on database insertion.
• loginType When loginType == "passord" || loginType == "sso" the email field must not be empty

Examples

JSON

POST https://sdk.viriciti.com/api/v1/smart-driving/driver-upload/json?timeZone=Europe/Amsterdam&language=nl

Payload:

    [{
        "firstName": "John",
        "lastName": "Doe",
        "driverId": "12345",
        "email": "j.doe@driver.nl",
        "driverGroup": "Amsterdam",
        "loginType": "password"
    }, {
        "firstName": "Chris",
        "lastName": "Smith",
        "driverId": "12346",
        "email": "c.smith@driver.nl",
        "driverGroup": "Amsterdam",
        "loginType": "sso"
    }, {
        "firstName": "Jane",
        "lastName": "Doe",
        "driverId": "12347",
        "driverGroup": "Utrecht"
    }]

POST https://sdk.viriciti.com/api/v1/smart-driving/driver-upload/csv?timeZone=Europe/Amsterdam&language=nl

CSV

Payload:

driverId,firstName,lastName,driverGroup,email,loginType
12345,John,Doe,Amsterdam,j.doe@driver.nl,password
12346,Chris,Smith,Amsterdam,c.smith@driver.nl,sso
12347,Jane,Doe,Utrecht,,none

Response:

{
    "totalDriverGroups": 2,
    "totalDrivers": 3,
    "drivers": [
        {
            "driverId": "12345",
            "firstName": "John",
            "lastName": "Doe",
            "language": "nl",
            "timeZone": "Europe/Amsterdam",
            "operatorId": "57189721e2ee7876362f9e7c",
            "email": "d.john@driver.nl"
        },
        {
            "driverId": "12346",
            "firstName": "Chris",
            "lastName": "Smith",
            "language": "nl",
            "timeZone": "Europe/Amsterdam",
            "operatorId": "57189721e2ee7876362f9e7c",
            "email": "c.smith@driver.nl"
        },
        {
            "driverId": "12347",
            "firstName": "Jane",
            "lastName": "Doe",
            "language": "nl",
            "timeZone": "Europe/Amsterdam",
            "operatorId": "57189721e2ee7876362f9e7c"
        }
    ],
    "driverGroups": {
        "Amsterdam": [
            "12345",
            "12346"
        ],
        "Utrecht": [
            "12347"
        ]
    },
    "message": "Run this query with query param 'execute=true' if this seems alright."
}

Trips

GET /sd-sessions

Retrieve smart driving sessions within a certain time frame. Note this endpoint only returns sessions that have been "evaluated", i.e. contain a metrics field.

GET https://sdk.viriciti.com/api/v1/smart-driving/sd-sessions

Query Parameter	Description
start	Either a unix time in microseconds, or an ISO8601 date formatted string. Note that when supplying a time zone in an ISO8601 string e.g. +0100, the + character needs to be url encoded to %2B, this is often done automatically.
end	Either a unix time in microseconds, or an ISO8601 date formatted string.
driverGroupIds	A comma seperated list of driver groups ids. Retrieve these using the /api/v1/config endpoint. Note that the result will only contain sessions that were driven when the driver was in these groups.
driverId	The driver id to get the sessions for.

Examples

GET https://sdk.viriciti.com/api/v1/smart-driving/sd-sessions?start=2020-02-20T21:00:00.000%2B0100&end=2020-02-20T21:05:00.000%2B0100&driverId=123456&driverGroupIds=UID

Response:

[
  {
      "_id": UID,
      "start": "2020-02-20T20:02:00.000Z",
      "end": "2020-02-20T20:20:00.000Z",
      "driverId": "123456",
      "route": String,
      "asset": {
          "name": String
      },
      "metrics": {
          "start": "2020-02-20T20:02:00.000Z",
          "end": "2020-02-20T20:20:00.000Z",
          "energyUsedPerKm": Number|null,   // In kWh    Electric only
          "energyConsumed": Number|null,    // In kWh    Electric only
          "energyRecovered": Number|null,   // In kWh    Electric only
          "energyUsed": Number|null,        // In kWh    Electric only
          "fuelUsed": Number|null,          // In liters Diesel only
          "fuelUsedPerKm": Number|null,     // In liters Diesel only
          "harshBrakingCount": Number,
          "odo": Number,                    // In km
          "recouped": Number|null,          // In kWh    Electric only
          "scoring": {
              "score": Number
          },
          "timeTotal": Number,              // In seconds
          "timeDriven": Number              // In seconds
      },
      "vehicleModel": {
        "energyType": "Electric|Diesel"
      }
  }
]

Notes - Some fields might be null because of the different energy types. - The time range query is being done on metrics.start

POST /trips-upload/:type

This endpoint allows for users to upload a set of trips. These trips will then be scheduled for calculation and scoring, which will result in Smart Driving Sessions.

POST https://sdk.viriciti.com/api/v1/smart-driving/trips-upload/:type

Path Parameter	Description
type	Format of upload, supported types are json and csv (required)

Query Parameter	Description
execute	By default this API performs a dry-run, this can be overruled by providing execute=true. (required)

Important! The correct use of a Content-Type header (application/json or text/csv) is required. Additionally the maximum request body size is limited to 10MB.

Validations

JSON Schema

Incoming requests will be validated against a (simple) JSON Schema, to guarantee the quality of the data. Errors result in a status code 400 and will be returned to the client. The response body will contain information about why the input did not pass validation. CSV requests will internally be parsed to JSON and validated against the same schema.

{
    "type":     "array",
    "minItems": 1,
    "items":    [
        {
            "type":       "object",
            "properties": {
                "start": {
                    "type":   "string",
                    "format": "date-time"
                },
                "end": {
                    "type":   "string",
                    "format": "date-time"
                },
                "route": {
                    "type":      "string",
                    "minLength": 1
                },
                "driverId": {
                    "type":      "string",
                    "minLength": 1
                },
                "vehicleId": {
                    "type":      "string",
                    "minLength": 1
                },
                "sessionType": {
                    "type": "string",
                    "enum": [ "in_service", "deadhead" ]
                }
            },
            "required": [
                "start",
                "end",
                "route",
                "driverId",
                "vehicleId"
            ]
        }
    ]
}

Field	Description
start	Either a unix time in microseconds, or an ISO8601 date formatted string. Be mindful of time zone offsets when using ISO8601. Note that when supplying a time zone in an ISO8601 string e.g. +0100, the + character needs to be url encoded to %2B, this is often done automatically.
end	Either a unix time in microseconds, or an ISO8601 date formatted string.
route	Line reference of which the vehicle was driving on.
driverId	Unique identifier of the driver. For this session to show up in the dashboard this driverId needs to be known within ViriCiti's system, ánd the driver needs to be linked to a driverGroup.
vehicleId	Vehicle identifier of the trip. Needs to be known to ViriCiti's System.
sessionType	Used to indicate if this is an in service trip, or a deadhead. Defaults to "in_service"

Data Integrity

If the input passes the schema validation the integrity of the data itself will be inspected. Currently we do the following checks:

• VehicleId All provided vehicle-identifiers will be cross-checked with ViriCiti's system to make sure this is a known vehicle to us.
• Duration The maximum allowed duration of a trip is 24h.
• Overlap For each trip the system checks if there are already sessions for either the vehicle or driver that overlap with this time-period.

If any of the check above fail the API will return a 400 with a descriptive error message.

Examples

JSON

POST https://sdk.viriciti.com/api/v1/smart-driving/trips-upload/json

Payload:

  [
    {
      "driverId": "12345",
      "start": "2020-07-24T11:00:00.000+0000",
      "end": "2020-07-24T13:00:00.000+0000",
      "route": "line 2",
      "vehicleId": "1033",
      "sessionType": "in_service"
    },
    {
      "driverId": "12345",
      "start": "2020-07-24T11:00:00.000+0000",
      "end": "2020-07-24T13:00:00.000+0000",
      "route": "line 3",
      "vehicleId": "1034",
      "sessionType": "deadhead"
    }
  ]

CSV

POST https://sdk.viriciti.com/api/v1/smart-driving/trips-upload/csv

Payload:

 start,end,route,driverId,vehicleId,sessionType
 2020-07-24T11:00:00.000+0000,2020-07-24T13:00:00.000+0000,line 2,12345,1033,in_service
 2020-07-24T11:00:00.000+0000,2020-07-24T13:00:00.000+0000,line 3,23456,1034,deadhead

Response:

{
    "sessions": [
        {
            "driverId": "12345",
            "route": "line 2",
            "start": "2020-07-24T11:00:00.000Z",
            "end": "2020-07-24T13:00:00.000Z",
            "externalVehicleId": "1033",
            "operatorId": "deadb33fdeadb33f01",
            "sourceType": "trips-upload",
            "sourceId": "deadb33fdeadb33f02",
            "vid": "vid_001",
            "vehicleModel": {
                "energyType": "Diesel"
            },
            "sessionType": "in_service"
        },
        {
            "driverId": "23456",
            "route": "line 3",
            "start": "2020-07-24T11:00:00.000Z",
            "end": "2020-07-24T13:00:00.000Z",
            "externalVehicleId": "1034",
            "operatorId": "deadb33fdeadb33f01",
            "sourceType": "trips-upload",
            "sourceId": "deadb33fdeadb33f02",
            "vid": "vid_002",
            "vehicleModel": {
                "energyType": "Diesel"
            },
            "sessionType": "deadhead"
        }
    ],
    "message": "Run this query with query param 'execute=true' if this seems alright." // Or "Success" when uploading with execute=true
}

The reponse does not contain the scoring/grading of each session, as mentioned these are added to a calculation queue instead. A benefit of this that this allows for future sessions (planning data) to be uploaded, which will be calculated once they are finished.