Vehicle Metadata¶
The vehicle-metadata API allows you or your maintenance provider to upload metadata about your vehicles.
https://sdk.viriciti.com/api/v1/vehicle-metadata
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-metadata API. Contact our Customer Excellence team for more information.
Send Vehicle Metadata¶
Incoming body requests will be validated against a JSON Schema, to guarantee the quality of the data. Errors result in a status code 400 and will be returned to the client. The body will contain information about why the input didn't pass validation.
{
"type": "object",
"properties": {
"externalVehicleId": {
"type": "string"
},
"vin": {
"type": "string"
},
"macAddress":{
"type": "string"
},
"manufacturer":{
"type": "string"
},
"modelName": {
"type": "string"
},
"yearOfInitialUse": {
"type": "number"
},
"kmDrivenToDateOfCommisioning": {
"type": "number"
},
"energyType": {
"type": "string",
"enum": [
"Electric",
"Hydrogen",
"Hybrid",
"CNG",
"Diesel",
"Trolley"
]
},
"battery": {
"type": "object",
"properties": {
"supplier": {
"type": "string"
},
"modelName": {
"type": "string"
},
"chemistry": {
"type": "string"
},
"effectiveCapacityKwh": {
"type": "number"
},
"nrPacks": {
"type": "number"
}
}
},
"dimensions": {
"type": "object",
"properties": {
"frontalAreaM2": {
"type": "number"
},
"length": {
"type": "number"
},
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
},
"weights": {
"type": "object",
"properties": {
"kerbWeightKg": {
"type": "number"
}
}
},
"tires": {
"type": "object",
"properties": {
"manufacturer": {
"type": "string"
},
"modelName": {
"type": "string"
},
"tireCode": {
"type": "string"
}
}
},
"articulated": {
"type": "boolean"
},
"maxNumPassengers": {
"type": "number"
},
"hvac": {
"type": "object",
"properties": {
"energySource": {
"type": "string",
"enum": [
"auxiliary",
"main-battery"
]
}
}
},
"chargerConnectors": {
"type": "string",
"enum": [
"plug",
"pantograph"
]
}
}
}
Get Assets¶
Before start sending data to Metadata API, you could make a GET request to the service and ask about your assets. The service will respond with all the VINs that have been set up for you, in order to send metadata info about them.
GET /api/v1/vehicle-metadata/my-assets¶
GET https://sdk.viriciti.com/api/v1/vehicle-metadata/my-assets
Respone:¶
The response will be an array including all the VINs that you are able to send metadata.
[
"vehicleMetadataTestVIN1"
]
POST /api/v1/vehicle-metadata¶
POST https://sdk.viriciti.com/api/v1/vehicle-metadata
Request Body:¶
{
"externalVehicleId": "externalVehicleId",
"vin": "vehicleMetadataTestVIN1",
"macAddress": "00:00:5e:00:53:af",
"manufacturer": "busManufacturer",
"modelName": "busModelName",
"yearOfInitialUse": 2022,
"kmDrivenToDateOfCommisioning": 100,
"energyType": "Electric",
"battery": {
"supplier": "CoulombTech",
"modelName": "batteryModelName",
"chemistry": "lithion",
"effectiveCapacityKwh": 20000,
"nrPacks": 10
},
"dimensions": {
"frontalAreaM2": 2,
"length": 2,
"width": 2,
"height": 2
},
"weights": {
"kerbWeightKg": 900
},
"tires": {
"manufacturer": "RubberCo",
"modelName": "maxspeedtire",
"tireCode": "LT215/85R16"
},
"articulated": true,
"maxNumPassengers": 30,
"hvac": {
"energySource": "auxiliary"
},
"chargerConnectors": ["plug"]
}
The unique identifier for each vehicle is VIN, which is a global unique identifier for each vehicle and as is defined by the International Organization for Standardization in ISO 3779.
In order to provide vehicle-metadata, you will have to provide the correct vin in the body request. An asset with this same VIN needs to be provisioned on https://portal.viriciti.com.
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 = {
externalVehicleId: 'externalVehicleId',
vin: 'vehicleMetadataTestVIN1',
macAddress: '00:00:5e:00:53:af',
manufacturer: 'busManufacturer',
modelName: 'busModelName',
yearOfInitialUse: 2022,
kmDrivenToDateOfCommisioning: 100,
energyType: 'Electric',
battery: {
supplier: 'CoulombTech',
modelName: 'batteryModelName',
chemistry: 'lithion',
effectiveCapacityKwh: 20000,
nrPacks: 10,
},
dimensions: {
frontalAreaM2: 2,
length: 2,
width: 2,
height: 2,
},
weights: {
kerbWeightKg: 900,
},
tires: {
manufacturer: 'RubberCo',
modelName: 'Maxspeedtire',
tireCode: 'LT215/85R16',
},
articulated: true,
maxNumPassengers: 30,
hvac: {
energySource: 'auxiliary',
},
chargerConnectors: ["plug"]
};
const options = {
method: 'POST',
headers: {
'x-api-key': '936afc31-fdf0-4f6b-b85b-02f115733fb4',
'content-type': 'application/json',
},
data: body,
url: 'https://sdk.viriciti.com/api/v1/vehicle-metadata/',
};
await axios(options)
.then((response) => {
console.log(response.data);
})
.catch((error) => {
console.log(error);
});
Responses¶
Success - Status code 201¶
A successful POST will result in a 201 status code. The response body will return the inserted data.
| Body Parameter | Status Code | Response Message |
|---|---|---|
|
201 |
|
Bad Request - Status code 400¶
A 400 bad request will be returned in case of validation errors. The response body, will always indicate the error(s). Following the variety of cases:
- Empty request body
Body Parameter Status Code Response Message { }400 { "message": "request.body should have required property 'externalVehicleId', request.body should have required property 'vin', request.body should have required property 'macAddress', request.body should have required property 'manufacturer', request.body should have required property 'modelName', request.body should have required property 'yearOfInitialUse', request.body should have required property 'kmDrivenToDateOfCommisioning', request.body should have required property 'energyType', request.body should have required property 'battery', request.body should have required property 'dimensions', request.body should have required property 'weights', request.body should have required property 'tires', request.body should have required property 'articulated', request.body should have required property 'maxNumPassengers', request.body should have required property 'hvac', request.body should have required property 'chargerConnectors'", "errors": [ { "path": ".body.externalVehicleId", "message": "should have required property 'externalVehicleId'", "errorCode": "required.openapi.validation" }, { "path": ".body.vin", "message": "should have required property 'vin'", "errorCode": "required.openapi.validation" }, { "path": ".body.macAddress", "message": "should have required property 'macAddress'", "errorCode": "required.openapi.validation" }, { "path": ".body.manufacturer", "message": "should have required property 'manufacturer'", "errorCode": "required.openapi.validation" }, { "path": ".body.modelName", "message": "should have required property 'modelName'", "errorCode": "required.openapi.validation" }, { "path": ".body.yearOfInitialUse", "message": "should have required property 'yearOfInitialUse'", "errorCode": "required.openapi.validation" }, { "path": ".body.kmDrivenToDateOfCommisioning", "message": "should have required property 'kmDrivenToDateOfCommisioning'", "errorCode": "required.openapi.validation" }, { "path": ".body.energyType", "message": "should have required property 'energyType'", "errorCode": "required.openapi.validation" }, { "path": ".body.battery", "message": "should have required property 'battery'", "errorCode": "required.openapi.validation" }, { "path": ".body.dimensions", "message": "should have required property 'dimensions'", "errorCode": "required.openapi.validation" }, { "path": ".body.weights", "message": "should have required property 'weights'", "errorCode": "required.openapi.validation" }, { "path": ".body.tires", "message": "should have required property 'tires'", "errorCode": "required.openapi.validation" }, { "path": ".body.articulated", "message": "should have required property 'articulated'", "errorCode": "required.openapi.validation" }, { "path": ".body.maxNumPassengers", "message": "should have required property 'maxNumPassengers'", "errorCode": "required.openapi.validation" }, { "path": ".body.hvac", "message": "should have required property 'hvac'", "errorCode": "required.openapi.validation" }, { "path": ".body.chargerConnectors", "message": "should have required property 'chargerConnectors'", "errorCode": "required.openapi.validation" } ] }- Wrong type in one of the required types. e.g. wrong type in eneryType:
Body Parameter Status Code Response Message { "externalVehicleId": "externalVehicleId", "vin": "vehicleMetadataTestVIN1", "macAddress": "00:00:5e:00:53:af", "manufacturer": "busManufacturer", "modelName": "busModelName", "yearOfInitialUse": 2022, "kmDrivenToDateOfCommisioning": 100, "energyType": "Electrics", // wrong type, the correct one in 'Electric' . . . "tires": { "manufacturer": "RubberCo", "modelName": "maxspeedtire", "tireCode": "LT215/85R16" }, "articulated": true, "maxNumPassengers": 30, "hvac": { "energySource": "auxiliary" } }400 { "message": "request.body.energyType should be equal to one of the allowed values: Electric, Hydrogen, Hybrid, CNG, Diesel, Trolley", "errors": [ { "path": ".body.energyType", "message": "should be equal to one of the allowed values: Electric, Hydrogen, Hybrid, CNG, Diesel, Trolley", "errorCode": "enum.openapi.validation" } ] }- In case the request body contains an unknown vin then the service will respond back with Bad Request indicating in the response message that the vin was not found.
Body Parameter Status Code Response Message { "externalVehicleId": "externalVehicleId", "vin": "vehicleMetadataTestVIN2", "macAddress": "00:00:5e:00:53:af", "manufacturer": "busManufacturer", "modelName": "busModelName", "yearOfInitialUse": 2022, "kmDrivenToDateOfCommisioning": 100, "energyType": "Electric", . . . "tires": { "manufacturer": "RubberCo", "modelName": "maxspeedtire", "tireCode": "LT215/85R16" }, "articulated": true, "maxNumPassengers": 30, "hvac": { "energySource": "auxiliary" } }400 { "message": "Bad Request. No assets found for this \"vin\": vehicleMetadataTestVIN2" }- In case there is an internal error with Api-Key and API Gateway then the service will warning you with the following:
Body Parameter Status Code Response Message { "externalVehicleId": "externalVehicleId", "vin": "vehicleMetadataTestVIN1", "macAddress": "00:00:5e:00:53:af", "manufacturer": "busManufacturer", "modelName": "busModelName", "yearOfInitialUse": 2022, "kmDrivenToDateOfCommisioning": 100, "energyType": "Electric", . . . "tires": { "manufacturer": "RubberCo", "modelName": "maxspeedtire", "tireCode": "LT215/85R16" }, "articulated": true, "maxNumPassengers": 30, "hvac": { "energySource": "auxiliary" } }400 { "message": "Api Key Error" }Unauthorized - Status code 401¶
In case you are trying to reach the API with a wrong Api-Key the authentication service will cut the request by sending back an unauthorized warning.
Headers Status Code Response Message { // "x-api-key": "936afc31-fdf0-4f6b-b85b-02f115733fb4" "x-api-key": "936afc31-fdf0-4f6b-b85b-02f115733fb" // <-- e.g. forgot the last number of your Api-Key }400 UnauthorizedConflict - Status code 409¶
The service will throw a conflict error when the request body contains a VIN which is duplicated accross multiple Portal assets. Duplication errors can be resolved by assigning correct and unique VINs in Portal.
Body Parameter Status Code Response Message { "externalVehicleId": "externalVehicleId", "vin": "vehicleMetadataTestVIN3", "macAddress": "00:00:5e:00:53:af", "manufacturer": "busManufacturer", "modelName": "busModelName", "yearOfInitialUse": 2022, "kmDrivenToDateOfCommisioning": 100, "energyType": "Electric", . . . "tires": { "manufacturer": "RubberCo", "modelName": "maxspeedtire", "tireCode": "LT215/85R16" }, "articulated": true, "maxNumPassengers": 30, "hvac": { "energySource": "auxiliary" } }409 { "message": "Conflict Error. Duplicate vin: vehicleMetadataTestVIN2" }Internal Server Error - Status code 500¶
The server will respond with an Internal Server Error for any operations that failed to be resolved in our internal system.
Body Parameter Status Code Response Message { "externalVehicleId": "externalVehicleId", "vin": "vehicleMetadataTestVIN3", "macAddress": "00:00:5e:00:53:af", "manufacturer": "busManufacturer", "modelName": "busModelName", "yearOfInitialUse": 2022, "kmDrivenToDateOfCommisioning": 100, "energyType": "Electric", . . . "tires": { "manufacturer": "RubberCo", "modelName": "maxspeedtire", "tireCode": "LT215/85R16" }, "articulated": true, "maxNumPassengers": 30, "hvac": { "energySource": "auxiliary" } }500 { "message": "Something went wrong" }