Telematics Gateway¶
Sending vehicle data is feasible through the Telematics Gateway product and can be accessed via HTTP endpoint:
https://sdk.viriciti.com/api/v1/telematics-gateway/data/<company>/<operator>
An x-api-key header needs to be provided with every request.
In addition to the x-api-key header, the Content-Type header will need to be set to application/json.
Configuration needs to be set up prior to the use of the vehicle-telematics API. Contact our Customer Excellence team for more information.
Send Engineering Units¶
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.
{
"type": "object",
"properties": {
"vin": {
"type": "string"
},
"units": {
"type": "array",
"minItems": 6,
"items": [
{
"type": "object",
"properties": {
"label": {
"type": "string",
"enum": [
"gps",
"soc",
"voltage",
"current",
"range",
"speed",
"odo"
]
},
"time": {
"type": "ISO8601 DateTime string with timezone" // 1970-12-31T00:00:00.000+0700
},
"value": {
"anyOf": [
{
"type": "object",
"properties": {
"lat": "number",
"lon": "number"
}
},
{
"type": "number"
}
]
}
},
"required": [
"gps",
"soc",
"voltage",
"current",
"speed",
"odo"
]
}
]
}
}
POST /api/v1/data/company/operator¶
POST https://sdk.viriciti.com/api/v1/telematics-gateway/data/:company/:operator
Request Body:¶
{
"vin": "4Y1SL65848Z411439",
"units": [
{
"label": "gps",
"time": "2022-01-12T00:00:00.000+0100",
"value": {
"lat": 23.2424,
"lon": 32.4565
}
},
{
"label": "soc",
"time": "2022-01-12T00:00:00.000+0100",
"value": 85.6
},
{
"label": "current",
"time": "2022-01-12T00:00:00.000+0100",
"value": 1.8
},
{
"label": "voltage",
"time": "2022-01-12T00:00:00.000+0100",
"value": 558
},
{
"label": "range",
"time": "2022-01-12T00:00:00.000+0100",
"value": 256
},
{
"label": "speed",
"time": "2022-01-12T00:00:00.000+0100",
"value": 0
},
{
"label": "odo",
"time": "2022-01-12T00:00:00.000+0100",
"value": 733.5
}
]
}
The unique identifier for each vehicle, decided to be the VIN, which is a global unique identifier for each vehicle and it is as defined by the International Organization for Standardization in ISO 3779.
Telematics-Gateway accepting the follow postfixes for each unit:
| units | postfix |
|---|---|
| soc | % |
| voltage | V |
| current | A |
| range | km |
| spped | km/h |
| odo | km |
Request Sample¶
In the following example we can see a code snippet of a post request written in NodeJS using the Axios module.
const axios = require('axios');
const body = {
vin: "4Y1SL65848Z411439",
units: [
{
label: "gps",
time: "2022-01-12T00:00:00.000+0100",
value: {
"lat": 23.4345,
"lon": 32.4565
}
},
{
label: "soc",
time :"2022-01-12T00:00:00.000+0100",
value: 89.0
},
{
label: "current",
time : "2022-01-12T00:00:00.000+0100",
value: 1.8
},
{
label: "voltage",
time : "2022-01-12T00:00:00.000+0100",
value: 558
},
{
label: "range",
time : "2022-01-12T00:00:00.000+0100",
value: 256
},
{
label: "speed",
time : "2022-01-12T00:00:00.000+0100",
value: 0
},
{
label: "odo",
time : "2022-01-12T00:00:00.000+0100",
value: 733.5
}
]
}
const options = {
method: 'POST',
headers: {
"x-api-key": "936afc31-fdf0-4f6b-b85b-02f115733fb4",
},
data: body,
url: "https://sdk.viriciti.com/api/v1/telematics-gateway/data/<company>/<operator>"
}
await axios(options)
.then((response) => {
console.log(response.data);
}).catch((error) => {
console.log(error);
})
Responses¶
Success - Status code 201¶
When the request is correct, then the service responds with by acknowledging the request and status code 201.
| Body Parameter | Status Code | Response Message |
|---|---|---|
|
201 |
|
Bad Request - Status code 400¶
On incorrect input telematics-gateway will respond with a 400 status code, the response body will contain more information describing the issue.
- Missing unit, e.g. missing gps unit
| Body Parameter | Status Code | Response Message |
|---|---|---|
|
400 |
|
The response message acknowledge that the request body is too small because it waits for a complete message of engineering units including 'gps' , 'soc' , 'current' , 'voltage' , 'range' , 'speed' and 'odo'.
- Wrong Label, e.g. typo spee instead of speed
| Body Parameter | Status Code | Response Message |
|---|---|---|
|
400 |
|
The path depicts where the error is located. For the above example, we can see that the error is located in the label of the 5th elemnt in the units array.
- Error type in value, e.g. passing a string in soc value
| Body Parameter | Status Code | Response Message |
|---|---|---|
|
400 |
|
Not Found - Status code 404¶
When sending data for an unknown VIN, the service will respond with a 404. The response body contains more information about what went wrong.
| Body Parameter | Status Code | Response Message |
|---|---|---|
|
404 |
|
Conflict - Status code 409¶
In the case multiple Portal assets are configured with the same VIN, the service will respond with a 409 status code. The response body contains more information about what went wrong.
To resolve this, ensure all Portal assets are properly configured with their respective VINs.
| Body Parameter | Status Code | Response Message |
|---|---|---|
|
409 |
|