Live
Accessing live data from vehicles and incidents can be done via a WebSocket connection to the following URL:
wss://sdk.viriciti.com/api/v2/live?apiKey=<API_KEY> # Yes v2 !
All information — with the exception of some debugging functions — sent back and forth on this socket will be in JSON format.
Request and Response¶
Once connected you can start sending messages regarding what data that should be flowing through the WebSocket connection. WebSocket allows for two ways communication where client can send subscription request and receive data from server using the same socket.
There are three type of data that you can subscribe to: vehicles, chargestations and incidents. All subscription will follow this general guideline like below where domain can be either vehicles, chargestations or incidents. Each domain can be requested simultaneously and/or with separate connections.
{
[domain]: {
[query]
},
[domain..n]: {
[query..n]
}
}
Once a subscription is sent to the server, it will be echoed back to the client to confirm that the new subscription has been received. There are also a few non-JSON calls that you can use to debug such as show acl and show query which will trigger the server to send ACL information or current subscription.
The client will need to send their subscription after each connection event. E.g. after a reconnect event caused by a network change, the subscription needs to be sent again.
Important! Data will not start to flow immediately since the server has to authorize everything on the request.
Every message from the server will follow this pattern below
{
type: [type of message],
payload: [message payload]
}
There are a few types of messages that the server can send:
| Messages | Definition |
|---|---|
error |
Will be sent when there are errors |
acl |
Response for show acl request |
incidents |
Live feed from requested incidents |
vehicles |
Data points for vehicles |
chargestations |
Data points for Charging Stations |
Each domain has different requirements for the query object. These requirements will be explained below, along with the expected results. Note that different domains can be queried at once, with one combined query object.
Vehicles¶
The example below will show how to create subscriptions for vehicle parameters:
{
"vehicles": {
"vehicle_1": ["soc", "voltage", "current"],
"vehicle_2": ["odo"]
}
}
The strings vehicle_1 and vehicle_2 refer to the vehicle's vid (see terminology) while the array contains all parameters for the corresponding vehicle (see parameters)
Once an event triggers for this subscription, the server will send a messages back, for example like this:
{
"type": "vehicles",
"payload": {
"time": 1552665820742, // unix timestamp (in milliseconds)
"value": 88.6,
"label": "soc",
"vid": "vehicle_1"
}
}
Charging Stations¶
The example below will show how to subscribe to real-time Charging Station data. The example query contains the following subscriptions:
alive,statusandpowerforcharger_1socforcharger_2transactionsforcharger_3
The strings charger_1, charger_2 and charger_3 refer to the charger's identity (see terminology) while the array, contains the parameters requested for.
See Charging Station Parameters for a comprehensive over of all existing parameters.
{
"chargestations": {
"charger_1": ["alive", "status", "power"],
"charger_2": ["soc"],
"charger_3": ["transactions"]
}
}
Once an event triggers for this subscription, the server will send a messages back, for example for a change of connector status.
See parameters for more information about a charger's connector status.
{
"type":"chargestations",
"payload": {
"parameter": "status",
"identity": "charger_1",
"connector": 1,
"time": "2019-11-07T09:07:23.006Z", // ISO 8601 datetime
"value": {
"errorCode": "NoError", // OCPP error message created by charger
"status": "Charging"
}
}
}
When a charger loses connection to our back office or reconnects, expect a message like this:
{
"type": "chargestations",
"payload": {
"parameter": "alive",
"identity": "charger_1",
"time": "2019-11-07T09:00:36.258Z", // ISO 8601 datetime
"value": true
}
}
Every time a charging station starts or stops an energy transaction, expect a message looking like this. Mind that the vehicle and vid (see terminology) fields can be missing, in case the mac address did not correspond to one of our vehicle's mac addresses.
{
"type": "chargestations",
"payload": {
"parameter": "transactions",
"identity": "charger_3",
"connector": 1,
"time": "2019-11-07T13:48:19.101Z", // ISO 8601 datetime
"value": {
"transactionId": 7347,
"event": "start",
"mac": "34:5A:7F:01:11:BB:C9:98",
"vehicle": "AMS E0013", // If the vehicle is known
"vid": "vehicle_1", // If the vehicle is known
"vin": "XL901E2TXLF530062", // If the vehicle is known
"idTag": "345A7F0111BBC998",
"meterStart": 0
}
}
}
For power and soc the messages look like these two:
{
"type":"chargestations",
"payload": {
"parameter": "power",
"identity": "charger_1",
"connector": 1,
"time": "2019-11-07T09:11:01.144Z", // ISO 8601 datetime
"value": 149520 // W
}
}
{
"type":"chargestations",
"payload": {
"parameter": "soc",
"identity": "charger_2",
"connector": 2,
"time": "2019-11-07T09:11:01.144Z", // ISO 8601 datetime
"value": 69 // %
}
}
Initial state¶
If you want to have the current/latest values of specific measurands before receiving the live updates, append &initialState=true to the url, like this: wss://sdk.viriciti.com/api/v2/live?apiKey=<API_KEY>&initialState=true.
Please note that this option is only available for chargestations.
Incidents¶
{
"incidents": {
"query": {
"vehicles": [vids], // OPTIONAL, Array of vehicle identifiers (vids)
"incidents": [incidentIds] // OPTIONAL, Array of incidents
}
}
}
In case of an empty query object the server will return all triggered incidents that are linked to the user. If one or more vehicles are provided the server will filter on incidents for these vehicles only. Filtering on incident ids will return only the incidents that match that id. If both filters are present the client will only recieve those specific incidents that triggered for their corresponding vehicles.
All responses follow the same structure. Payload for incidents contains information about the actual incident. The mock server has a limited amount of responses, but covers multiple incidents for multiple vehicles. A sample incidentObject looks like this:
{
"incident": "incident_02",
"name": "Battery SoC less than 15%",
"triggeredLabels": [],
"reported": true,
"state": {
"time": 1563334177071,
"gps": {
"time": 1563334177071,
"value": "-33.92188915|18.41570377",
"label": "gps"
},
"soc": {
"time": 1563334169921,
"value": 55.29412,
"label": "soc"
}
},
"vid": "vehicle_1",
"start": {
"time": 1563334169921,
"gps": {
"time": 1563334166092,
"value": "-33.92188915|18.41570377",
"label": "gps"
},
"soc": {
"time": 1563334169921,
"value": 55.29412,
"label": "soc"
}
},
"end": {
"time": 1563334177071,
"gps": {
"time": 1563334177071,
"value": "-33.92188915|18.41570377",
"label": "gps"
},
"soc": {
"time": 1563334169921,
"value": 55.29412,
"label": "soc"
}
}
}
Relevant keys:
vid: // vid the incident triggered for
start: // state of the vehicle when the incident triggered
state: // state of the vehicle when the incident is reported by ViriCiti
end: // state of the vehicle when the incident ended