Historical
Accessing historical data for vehicles can be accessed via our HTTP endpoint:
https://sdk.viriciti.com
All information that is sent will be in JSON format, and an x-api-key header needs to be provided with every request.
Vehicles¶
Time Series¶
GET https://sdk.viriciti.com/api/v1/time/:vid
Retrieving time series information from vehicle can be done using this API. Each time you will need to request data for a specific vid (see terminology).
| Parameter | Description |
|---|---|
| start | Start time of the time stream in Unix timestamp (milliseconds) * |
| end | End time of the time stream in Unix timestamp (milliseconds) * |
| label | Vehicle Labels request * |
| step | Interval in which data is returned. (in unix timestamp (milliseconds), defaults to 1) |
| bordered | Enables the 'bordered' feature when set to 'true' |
Important! The Time Series API can do at most 31 days and 5 vehicle at a time
Standard request¶
The example below will demonstrate historical data request for odo of vehicle_1 from 1st August 2019 00:00:00 GMT to 5th August 2019 23:59:59 GMT
GET https://sdk.viriciti.com/api/v1/time/vehicle_1?label=odo&start=1564617600000&end=1565049599000
Example result from this query will look like:
[
{
"time": 1564617600000,
"value": 76.9
},
{
"time": 1564617700000,
"value": 77
},
{
"time": 1564617800000,
"value": 77
},
{
"time": 1565049599000,
"value": 77.1
},
...
]
Step¶
The step query parameter can be used to adjust the resolution of the data. The default, 1ms, will return all raw values and is the highest possible resolution. In some cases, however, it might be useful to group data by a higher interval. This results in less data and thus reduces response times. Providing step=3600000 will return data split by an hourly interval. Each datum reflects the last known value of that label within that hour. If there was no data for that hour the whole hour will be omitted.
Bordered¶
By default the first datapoint will be the first stored datum within the provided timespan. The last point is the last stored value within the timespan, but is also affected by the step parameter as explained above. To make sure your start and end have a value associated with them the bordered=true query parameter can be provided. This will insert the most recent (previous) values for both start and end respectively.
State (v1)¶
GET https://sdk.viriciti.com/api/v1/state/:vid
State API (v1) provides the ability to request data for a specific point in time.
| Parameter | Description |
|---|---|
| time | End time of time stream in unix timestamp (milliseconds) * |
| labels | Comma separated Charging Station Parameters request * |
The example below will retrieve current odo and soc of vehicle_1 on 1st August 2019 12:30:00 GMT
GET https://sdk.viriciti.com/api/v1/state/vehicle_1?labels=odo,soc&time=1564662659000
Example result from this query will look like:
[
{
"label": "odo",
"time": 1564662658000,
"value": 148645.30575
},
{
"label": "soc",
"time": 1564662658600,
"value": 84.8
},
...
]
State (v2)¶
POST https://sdk.viriciti.com/api/v2/state
State API (v2) provides the ability to request the most recent data for multiple vehicles at once. The request body must be an object with the VID as key and an array of parameters as value. Example of such request can look like:
{
"vehicle_1": [ "odo", "soc" ],
"vehicle_2": [ "soc" ]
}
Example response from this request will look like:
{
"vehicle_1": {
"odo": {
"value": 148645.30575,
"time": 1564662658000
},
"soc": {
"value": 84.8,
"time": 1564662658600
}
},
"vehicle_2": {
"soc": {
"value": 90,
"time": 1564662678635
}
}
}
Charging Stations¶
Time Series¶
Important! The Time Series API for Charging Stations can be queried for at most 31 days
Measurements¶
GET https://sdk.viriciti.com/api/v1/chargestations/time/measurements/:identity
Request historical measurements data between 2 two points in time
| Parameter | Description |
|---|---|
| start | Start time of the time stream in Unix timestamp (milliseconds) * |
| end | End time of the time stream in Unix timestamp (milliseconds) * |
| labels | Comma seperated charge station label parameters (power | soc | energy) * |
| connector | Connector to get the data for, if supplied |
The example below will retrieve energy and soc measurements from chargestation_1 and connector 2 between 16 July 2020 09:00 GMT and 17 July 2020 09:00 GMT
GET https://sdk.viriciti.com/api/v1/chargestations/time/measurements/chargestation_1?start=1594890000000&end=1594976400000&labels=energy,soc&connector=2
Example result from this query will look like:
[
{
"time": "2020-07-16T09:07:51.230Z",
"value": 88,
"connector": 2,
"label": "soc"
},
{
"time": "2020-07-16T09:07:21.208Z",
"value": 18945,
"connector": 2,
"label": "energy"
},
{
"time": "2020-07-16T09:07:21.208Z",
"value": 88,
"connector": 2,
"label": "soc"
},
...
]
Transactions¶
GET https://sdk.viriciti.com/api/v1/chargestations/time/transactions/:identity
Request historical transactions data within a specified start and end time
| Parameter | Description |
|---|---|
| start | Start time of the time stream in Unix timestamp (milliseconds) * |
| end | End time of the time stream in Unix timestamp (milliseconds) * |
The example below will retrieve transactions from chargestation_1 between 16 July 2020 09:00 GMT and 17 July 2020 09:00 GMT. 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.
GET https://sdk.viriciti.com/api/v1/chargestations/time/transactions/chargestation_1?start=1594890000000&end=1594976400000
Example result from this query will look like:
[
{
"chargestation": "chargestation_1",
"position": 1,
"status": "stopped",
"transactionId": "33",
"vehicle": {
"idTag": "000000000000",
"mac": "00:00:00:00:00:00:00:00",
"vid": "vid_123",
"vin": "XL901E2TXLF530062",
"name": "1234"
},
"start": {
"time": "2020-07-16T09:07:21.208Z",
"value": 0
},
"end": {
"time": "2020-07-17T08:07:21.208Z",
"value": 4678
},
"total": {
"duration": 828000,
"energy": 4678
}
},
...
]
Alive¶
GET https://sdk.viriciti.com/api/v1/chargestations/time/alive/:identity
Request historical alive data between 2 two points in time
| Parameter | Description |
|---|---|
| start | Start time of the time stream in Unix timestamp (milliseconds) * |
| end | End time of the time stream in Unix timestamp (milliseconds) * |
The example below will retrieve alive status from chargestation_1 between 16 July 2020 09:00 GMT and 17 July 2020 09:00 GMT
GET https://sdk.viriciti.com/api/v1/chargestations/time/alive/chargestation_1?start=1594890000000&end=1594976400000
Example result from this query will look like:
[
{
"time":"2020-07-16T16:18:00.000Z",
"value": true // alive changed to `true`
},
{
"time":"2020-07-16T20:18:00.000Z",
"value": false // alive changed to `false`
},
...
]
Status¶
GET https://sdk.viriciti.com/api/v1/chargestations/time/status/:identity
Request historical status data between 2 two points in time
| Parameter | Description |
|---|---|
| start | Start time of the time stream in Unix timestamp (milliseconds) * |
| end | End time of the time stream in Unix timestamp (milliseconds) * |
See Parameters for more information about a charger's connector status.
The example below will retrieve status from chargestation_1 between 16 July 2020 09:00 GMT and 17 July 2020 09:00 GMT. Example result from this query will look like:
[
{
"time":"2020-07-16T16:18:00.000Z",
"value": "Charging", // status changed to `Charging`
"position": 1
},
{
"time":"2020-07-16T16:20:05.000Z",
"value": "Available", // status changed to `Available`
"position": 2
},
{
"time":"2020-07-16T16:18:00.000Z",
"value": "Available", // status changed to `Available`
"position": 1
},
{
"time":"2020-07-16T16:20:05.000Z",
"value": "Charging", // status changed to `Charging`
"position": 2
},
...
]
Charging Time¶
For multiple chargestations¶
POST https://sdk.viriciti.com/api/v1/chargestations/transactions/charging-times
Requests the current charging time for multiple chargestations
| Parameter | Description |
|---|---|
| identities | Array of charger identities to request charging-time for |
| targetSoc | final SOC to calculate charging-time for |
Note: the targetSoc can not be higher than the current SOC, no charging time will be returned in that case.
The example below will query the charging-times for all connectors for ViriCiti_0 and ViriCiti_1
{
identities: [
"ViriCiti_0",
"ViriCiti_1"
]
}
{
"ViriCiti_0": [
{
"connector": 2,
"chargingTime": {
"mean": 2443,
"std": 552.015380859375
}
},
{
"connector": 1,
"chargingTime": {
"mean": 4141,
"std": 524.5238037109375
}
}
],
"ViriCiti_1": [
{
"connector": 1,
"chargingTime": {
"mean": 8102,
"std": 490.1287318212988
}
}
]
}
For multiple vehicles¶
POST https://sdk.viriciti.com/api/v1/chargestations/transactions/charging-times
Requests the current charging time for a single chargestation
| Parameter | Description |
|---|---|
| vehicles | Array of vehicles to request charging times for |
| targetSoc | final SOC to calculate charging-time for |
Note: the targetSoc can not be higher than the current SOC, no charging time will be returned in that case.
The example below will query the charging-times for bus_01 and bus_02 POST https://sdk.viriciti.com/api/v1/chargestations/transactions/charging-times
{
vehicles: [
"bus_01",
"bus_02"
]
}
{
"bus_01": {
"mean": 4167,
"std": 311.5238037109375
},
"bus_02": {
"mean": 8012,
"std": 220.5238037109375
},
}
For a single chargestation¶
GET https://sdk.viriciti.com/api/v1/chargestations/transactions/charging-time/identity
Requests the current charging time for a single chargestation
| Parameter | Description |
|---|---|
| identity | single charger identity to request charging-time for |
The example below will query the charging-times for all connectors for ViriCiti_0 and ViriCiti_1
GET https://sdk.viriciti.com/api/v1/chargestations/transactions/charging-time/ViriCiti_0
{
"ViriCiti_0": [
{
"connector": 2,
"chargingTime": {
"mean": 2443,
"std": 552.015380859375
}
},
{
"connector": 1,
"chargingTime": {
"mean": 4141,
"std": 524.5238037109375
}
}
]
}
For a single chargestation and connector¶
GET https://sdk.viriciti.com/api/v1/chargestations/transactions/charging-time/identity/connector
Requests the current charging time for a single chargestation
| Parameter | Description |
|---|---|
| identity | single charger identity to request charging-time for |
| connector | connector of the chargestation to request charging-time for |
The example below will query the charging-times for connector 1 for ViriCiti_0 GET https://sdk.viriciti.com/api/v1/chargestations/transactions/charging-time/ViriCiti_0/1
{
"ViriCiti_0": [
{
"connector": 1,
"chargingTime": {
"mean": 4141,
"std": 524.5238037109375
}
}
]
}