Vehicles

The Vehicle class enables users to manage their fleet efficiently within the Fleet Management SDK. Vehicles play a crucial role in optimizing logistics and route planning. This API provides endpoints to:

Add new vehicles to the fleet.
Retrieve and update vehicle details such as type, capacity, and status.
Delete vehicles when they are no longer in use.
Monitor last known positions and fuel consumption to enhance operational efficiency.

Vehicle Structure

Each vehicle object consists of the following attributes:

Name	Type	Description	Setter	Getter
Id	`LargeInteger`	Unique identifier for the vehicle.	❌	✅
Type	`EVehicleType`	The type of the vehicle. Possible values: • `VT_Car (0)`: Car vehicle type. • `VT_Pedestrian (1)`: Pedestrian vehicle type. • `VT_EBike (2)`: Electric bike vehicle type. • `VT_Truck (3)`: Truck vehicle type. • `VT_Bike (4)`: Regular bike vehicle type.	✅	✅
Status	`EVehicleStatus`	The status of the vehicle. Possible values: • `VS_Unavailable (-1)`: Vehicle is unavailable. • `VS_Available (0)`: Vehicle is available. • `VS_EnRoute (1)`: Vehicle is en route.	✅	✅
Name	`String`	The name of the vehicle.	✅	✅
Manufacturer	`String`	The manufacturer of the vehicle.	✅	✅
Model	`String`	The model of the vehicle.	✅	✅
LicensePlate	`IString`	The license plate of the vehicle.	✅	✅
FuelType	`EFuelType`	The fuel type of the vehicle. Possible values: • `FT_None (-1)`: Used for pedestrian and bike types. • `FT_DieselStandard (0)`: Standard diesel fuel type. • `FT_DieselPremium (1)`: Premium diesel fuel type. • `FT_GasolineStandard (2)`: Standard gasoline fuel type. • `FT_GasolinePremium (3)`: Premium gasoline fuel type. • `FT_Electric (4)`: Electric fuel type. • `FT_LPG (5)`: LPG (Liquid Petroleum Gas) fuel type.	✅	✅
LastPosition	`Coordinates`	The last known position of the vehicle.	✅	✅
Consumption	`float`	The consumption of the vehicle (l/100 km or kWh/100 km).	✅	✅
BikePower	`float`	The power of the bicycle in watts.	✅	✅
BikerWeight	`float`	The minimum weight that the vehicle can carry (only for bikes).	✅	✅
MaxLoadWeight	`float`	The maximum weight that the vehicle can carry.	✅	✅
MaxLoadCube	`float`	The maximum cubic volume that the vehicle can carry.	✅	✅
Height	`float`	The height of the vehicle.	✅	✅
Width	`float`	The width of the vehicle.	✅	✅
Weight	`float`	The weight of the vehicle.	✅	✅
Length	`float`	The length of the vehicle.	✅	✅
AxleLoad	`float`	The axle load of the vehicle.	✅	✅
FixedCost	`float`	The fixed cost of the vehicle.	✅	✅
CostPerHour	`float`	The cost per hour of the vehicle.	✅	✅
StartTime	`int`	The start time of the working program, in minutes from midnight.	✅	✅
EndTime	`int`	The end time of the working program, in minutes from startTime.	✅	✅

Managing Vehicles

Creating a Vehicle

Async adds a vehicle in the list of vehicles of the API user. The list of vehicles represents the fleet of the user.

Note

If the operation is successful, the vehicle will have an id assigned; which can be retrieved using the method vehicle.getId(), if not, an error code is returned which can be interpreted as mentioned at the end of the page.

How it works

Create a vrp::Vehicle and set the desired fields.
Create a ProgressListener and vrp::Service.
Call the addVehicle() method from the vrp::Service using the vrp::Vehicle and ProgressListener and wait for the operation to be done.

Example

// Create a Vehicle object and set its properties
gem::vrp::Vehicle vehicle;
vehicle.setName("Delivery Van 1");
vehicle.setType(gem::vrp::EVehicleType::VT_Truck);
vehicle.setStatus(gem::vrp::EVehicleStatus::VS_Available);
vehicle.setManufacturer("Ford");
vehicle.setModel("Transit");
vehicle.setFuelType(gem::vrp::EFuelType::FT_Diesel);
vehicle.setConsumption(8.5);
vehicle.setLicensePlate("XYZ-1234");
vehicle.setMaxLoadWeight(2000);
vehicle.setMaxLoadCube(12.5);
vehicle.setStartTime(420);// the vehicle start time of the working program in minutes from midninght
vehicle.setEndTime(540); // the vehicle end time of the working program in minutes from startTime

// Initialize Service and Listener
ProgressListener listener;
gem::vrp::Service service;

// Call the addVehicle method
int res = service.addVehicle(&listener, vehicle);
if (res == gem::KNoError)
{
    // Wait for completion
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);

    // Check operation success
    if (listener.IsFinished() && listener.GetError() == gem::KNoError)
        std::cout << "Vehicle added successfully. ID: " << vehicle.getId() << std::endl;
    else
        std::cout << "Failed to add vehicle: Operation timed out or server returned an error." << std::endl;
}
else
	  std::cout << "Failed to send addVehicle request." << std::endl;

Retrieving Vehicles

There are two ways to retrieve vehicle data:

a) Get a Vehicle by ID

How it works

Create a ProgressListener, a vrp::Service and a vrp::Vehicle.
Call the getVehicle() method from the vrp::Service using the vrp::Vehicle from 1.), the ID of the vehicle that you want to retrieve and the ProgressListener.
Once the operation completes, the vrp::Vehicle from 1.) will be populated.

// Retrieve a specific vehicle by id
 ProgressListener listener;
gem::vrp::Service service;

LargeInteger vehicleId = 0; // set your vehicle id
int res = service.getVehicle(listener, vehicle, vehicleId);
if (res == gem::KNoError)
{
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);
    if (listener.IsFinished() && listener.GetError() == gem::KNoError)
        std::cout << "Vehicle returned successfully" << std::endl;
    else
        std::cout << "Failed to retrive vehicle: Operation timed out or server returned an error." << std::endl;
}
else
	  std::cout << "Failed to send getVehicle request." << std::endl;

b) Get All Vehicles (with optional filtering)

Returns all vehicles of the API user (which contain the search term).

How it works

Create a ProgressListener, a vrp::Service and a vrp::VehicleList.
Call the getAllVehicles() method from the vrp::Service using the list from 1.) and the ProgressListener.
Once the operation completes, the list from 1.) will be populated.

// Retrieve all vehicles, optionally filtering by a search term
ProgressListener listener;
gem::vrp::Service service;

gem::String searchTerm = "Truck";
gem::vrp::VehicleList vehicles;
int res = service.getVehicles(listener, vehicles, searchTerm);
if (res == gem::KNoError)
{
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 20000);
    if (listener.IsFinished() && listener.GetError() == gem::KNoError)
        std::cout << vehicles.size() << " vehicles returned successfully" << std::endl;
    else
        std::cout << "Failed to retrive vehicles: Operation timed out or server returned an error." << std::endl;
}
else
	  std::cout << "Failed to send getVehicles request." << std::endl;

Updating a Vehicle

Vehicles can be updated with new status, consumption rate, or other relevant information.

Note

If the consumption was changed and the vehicle was used in a route, the next time you access (retrieve) the route, its cost will be updated considering the new consumption of the vehicle.

How it works

Create a ProgressListener and a vrp::Service.
Retrieve the vehicle you want to update (see [Get Vehicle]./Vehicle#a-get-a-vehicle-by-id)) in a vrp::Vehicle.
Change the desired fields of the vrp::Vehicle.
Call the updateVehicle() method from the vrp::Service using the vrp::Vehicle from 2.) and the ProgressListener and wait for the operation to be done.

Example

// Retrieve an existing vehicle by id
ProgressListener listener;
gem::vrp::Service service;

gem::vrp::Vehicle vehicle;
LargeInteger vehicleId = 0;// Set your vehicle id
int res = service.getVehicle(listener, vehicle, vehicleId);
if (res == gem::KNoError)
{
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 20000);
     if(listener.IsFinished() && listener.GetError() == gem::KNoError)
    {
        // Update vehicle properties
        vehicle.setStatus(gem::vrp::EVehicleStatus::VS_Unavailable);
        vehicle.setConsumption(10);

        // Save the updated details
        res = service.updateVehicle(listener, vehicle);
        if (res == gem::KNoError)
        {
            WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);
            if (listener.IsFinished() && listener.GetError() == gem::KNoError)
                std::cout << "Vehicle updated successfully" << std::endl;
            else
                std::cout << "Failed to update vehicle: Operation timed out or server returned an error." << std::endl;
        }
        else
            std::cout << "Failed to send updupdateVehicleateOrder request." << std::endl;
    }
    else
        std::cout << "Failed to retrive vehicle: Operation timed out or server returned an error." << std::endl;
}
else
    std::cout << "Failed to send getVehicle request." << std::endl;

Deleting a Vehicle

Vehicles can be deleted individually or in bulk.

note

Deleted vehicle will no longer appear in the routes to which the vehicle was assigned; their cost will be re-calculated using the default values (the vehicle's type is a car which runs on standard gasoline and has a consumption of 7.5 l/100km).

How it works

Create a ProgressListener and vrp::Service.
Call the deleteVehicle() method from the vrp::Service using the vehicle's id and ProgressListener and wait for the operation to be done.

ProgressListener listener;
gem::vrp::Service service;

// Remove multiple vehicles by IDs
LargeIntList vehiclesToDelete = {111, 222, 333};
int res = service.deleteVehicle(listener, vehiclesToDelete);
if (res == gem::KNoError)
{
  WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);
  if (listener.IsFinished() && listener.GetError() == gem::KNoError && res == gem::KNoError)
      std::cout << "Vehicle deleted successfully" << std::endl;
  else
      std::cout << "Failed to delete Vehicle: Operation timed out or server returned an error." << std::endl;
}
else
	  std::cout << "Failed to send deleteVehicle request." << std::endl;

Error Handling

This API returns specific error codes to indicate potential issues. Below is a summary of common errors and how to resolve them:

Error Code	Description	Solution
`KInvalidInput`	Missing required fields or invalid vehicle data.	Ensure all mandatory fields are properly filled.
`KNotFound`	The specified vehicle ID does not exist.	Verify that the correct vehicle ID is provided.
`KInternalAbort`	Server-side issue or unexpected parsing error.	Retry the request or check API status.

Vehicle Structure​

Managing Vehicles​

Creating a Vehicle​

How it works​

Example​

Retrieving Vehicles​

a) Get a Vehicle by ID​

How it works​

b) Get All Vehicles (with optional filtering)​

How it works​

Updating a Vehicle​

How it works​

Example​

Deleting a Vehicle​

How it works​

Error Handling​

Vehicle Structure

Managing Vehicles

Creating a Vehicle

How it works

Example

Retrieving Vehicles

a) Get a Vehicle by ID

How it works

b) Get All Vehicles (with optional filtering)

How it works

Updating a Vehicle

How it works

Example

Deleting a Vehicle

How it works

Error Handling