Fuel Prices

_|

Overview

The Fuel Prices class allows users to manage fuel prices for different fuel types within the VRP system. This API is essential for calculating accurate fuel costs for vehicles, especially when optimizing routes. The API provides endpoints to:

• Set fuel prices for different fuel types.
• Retrieve fuel prices along with the time they were last updated.

Fuel Price Structure

The fuel price structure consists of the following components:

FuelPricePair

Each FuelPricePair represents a fuel type and its corresponding price.

Name	Type	Description
fuel	EFuelType	The type of fuel. 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.
price	float	The price of one liter of fuel or one kWh (for electric vehicles).

FuelPrices

The FuelPrices structure contains a list of FuelPricePair elements and the time when the prices were added.

Name	Type	Description
fuelPrices	FuelPricePairList	A list of fuel prices, one for each fuel type.
additionTime	Time	The time when the fuel prices were added.

Managing Fuel Prices

1. Setting Fuel Prices

Set the desired prices for each fuel type. The time will be automatically updated if the operation is successful.

How it works

1. Create a FuelPrices object and populate the fuelPrices list with FuelPricePair elements for each fuel type.
2. Create a ProgressListener and vrp::Service.
3. Call the addFuelPrices() method from the vrp::Service using the FuelPrices object and ProgressListener.
4. Wait for the operation to complete.

Example

// Create a FuelPrices object and set fuel prices
gem::vrp::FuelPricePair dieselStPrice;
dieselStPrice.fuel = gem::vrp::EFuelType::FT_DieselStandard;
dieselStPrice.price = 1.08;
gem::vrp::FuelPricePair dieselPrPrice;
dieselPrPrice.fuel = gem::vrp::EFuelType::FT_DieselPremium;
dieselPrPrice.price = 1.15;

gem::vrp::FuelPricePairList pricesPairList;
pricesPairList.toStd().push_back(dieselStPrice);
pricesPairList.toStd().push_back(dieselPrPrice);

gem::vrp::FuelPrices prices;
prices.fuelPrices = pricesPairList;

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

// Call the addFuelPrices method and wait for completion
int res = service.addFuelPrices(&listener, prices);
if (res == gem::KNoError)
{
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 10000);

    // Check operation success
    if (listener.IsFinished() && listener.GetError() == gem::KNoError)
        std::cout << "Fuel prices set successfully" << std::endl;
    else
        std::cout << "Failed to add fuelPrices: Operation timed out or server returned an error." << std::endl;
}
else
	  std::cout << "Failed to send addFuelPrices request." << std::endl;

2. Retrieving Fuel Prices

Get all the changes of the fuel prices and when they were made.

Note

The first one in the list is the most recent change. All the routes created after this change will use these prices to calculate the cost.

How it works

1. Create a ProgressListener, a vrp::Service, and a FuelPricesList.
2. Call the getFuelPrices() method from the vrp::Service using the FuelPricesList and ProgressListener.
3. Once the operation completes, the FuelPricesList will be populated with all fuel prices that was added.

Example

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

// Call the getFuelPrices method
int res = service.getFuelPrices(listener, fuelPricesList);

if (res == gem::KNoError)
{
    // Wait for completion
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);

    // Check operation success and process the results
    if (listener.IsFinished() && listener.GetError() == gem::KNoError ) 
        for (const auto& fuelPrices : fuelPricesList) 
        {
            std::cout << "Fuel prices added at: " << fuelPrices.additionTime << std::endl;
            for (const auto& fuelPricePair : fuelPrices.fuelPrices) 
                std::cout << "Fuel Type: " << fuelPricePair.fuel << ", Price: " << fuelPricePair.price << std::endl;
        }
    else
        std::cout << "Failed to retrive fuel prices: Operation timed out or server returned an error." << std::endl;
}
else
	  std::cout << "Failed to send getFuelPrices 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 fuel price data.	Ensure all mandatory fields are properly filled.
KInternalAbort	Server-side issue or unexpected parsing error.	Retry the request or check API status.