Miscellaneous Location

_|

The MiscLocation class allows users to manage miscellaneous locations in the Fleet Management SDK. MiscLocations are points of interest, depots, or other locations relevant to logistics and route optimization. This API provides endpoints to:

• Add new miscellaneous locations to the system.
• Retrieve and update location details such as alias, address, and coordinates.
• Delete miscellaneous locations when they are no longer needed.

Note

Miscellaneous locations can be used as departure points. For more information, see Departure
Additionally, miscellaneous locations can also serve as destinations. Refer to Destination for further details."

MiscLocation Structure

Each miscellaneous location object consists of the following attributes:

Name	Type	Description	Setter	Getter
Id	LargeInteger	Unique identifier for the miscellaneous location.	❌	✅
IsDepot	bool	Indicates whether the location is a depot.	✅	✅
Coordinates	Coordinates	Geographical coordinates of the miscellaneous location.	✅	✅
Address	AddressInfo	Address information of the miscellaneous location.	✅	✅
Alias	String	Alias name of the miscellaneous location.	✅	✅

Managing MiscLocations

Creating a MiscLocation

Add a miscellaneous location to the agenda, allowing it to be utilized as a point of interest, depot, or any other location relevant to logistics and route optimization.

Note

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

How it works

1. Create a vrp::MiscLocation and set the desired fields.
2. Create a ProgressListener and vrp::Service.
3. Call the addMiscLocation() method from the vrp::Service using the vrp::MiscLocation and ProgressListener and wait for the operation to be done.

Example

// Define MiscLocation address
gem::AddressInfo address;
address.setField("USA", gem::EAddressField::Country);
address.setField("New York", gem::EAddressField::City);
address.setField("10007", gem::EAddressField::PostalCode);
address.setField("Broadway", gem::EAddressField::StreetName);

// Define MiscLocation coordinates
gem::Coordinates coords(40.712776, -74.005974);

// Create a `vrp::MiscLocation` and set the desired fields.
gem::vrp::MiscLocation location;
location.setAlias("Central Depot");
location.setIsDepot(true);
location.setCoordinates(coords);
location.setAddress(address);

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

// Call the addMiscLocation method
int res = service.addMiscLocation(&listener, location);

// Wait for completion
WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);

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

Retrieving MiscLocations

There are two ways to retrieve MiscLocation data:

a) Get a MiscLocation by ID

Get a certain MiscLocation by ID.

How it works

1. Create a ProgressListener, a vrp::Service and a vrp::MiscLocation.
2. Call the getMiscLocation() method from the vrp::Service using the vrp::MiscLocation from 1.), the ID of the miscLocation that you want to retrieve and the ProgressListener.
3. Once the operation completes, the vrp::MiscLocation from 1.) will be populated.

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

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

b) Get All MiscLocations

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

How it works

1. Create a ProgressListener and vrp::Serviceand a vrp::MiscLocationList.
2. Call the getMiscLocations() method from the vrp::Service and the ProgressListener.
3. Once the operation completes, the list from 1.) will be populated with miscLocations that match the search criteria.

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

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

Updating a MiscLocation

Saves the updates made to a miscLocation. MiscLocations can be updated with new alias, address, or coordinates.

How it works

1. Create a ProgressListener and a vrp::Service.
2. Retrieve the miscLocation you want to update (see Get MiscLocation) in a vrp::MiscLocation.
3. Change the desired fields of the vrp::MiscLocation.
4. Call the updateMiscLocation() method from the vrp::Service using the vrp::MiscLocation from 2.) and ProgressListener and wait for the operation to be done.

Example

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

// Retrieve an existing MiscLocation by id
gem::vrp::MiscLocation location;
LargeInteger locationId = 0; // Set your misclocation id
int res = service.getMiscLocation(listener, location, locationId);
if (res == gem::KNoError)
{
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 20000);
    if(listener.IsFinished() && listener.GetError() == gem::KNoError)
    {
        // Update misclocation properties
        location.setAlias("Updated Depot");
        gem::Coordinates newCoords(41.123456, -73.987654);
        location.setCoordinates(newCoords);

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

Deleting a MiscLocation

MiscLocations can be deleted individually or in bulk.

Note

If a miscellaneous location that needs to be deleted was previously used to create orders or as a departure point, the id_depot in those orders or the departure field will be set to 0.

How it works

1. Create a ProgressListener and vrp::Service.
2. Call the deleteMiscLocation() method from the vrp::Service using the miscLocation object and ProgressListener and wait for the operation to be done.

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

// Remove multiple MiscLocations by IDs
LargeIntList locationsToDelete = {111, 222, 333};
int res = service.deleteMiscLocation(listener, locationsToDelete);
if (res == gem::KNoError)
{
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);
    if (listener.IsFinished() && listener.GetError() == gem::KNoError && res == gem::KNoError)
        std::cout << "MiscLocations deleted successfully" << std::endl;
    else
        std::cout << "Failed to delete miscLocations: Operation timed out or server returned an error." << std::endl;
}
else
	  std::cout << "Failed to send deleteMiscLocation 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 data.	Ensure all mandatory fields are properly filled.
KNotFound	The specified MiscLocation ID does not exist.	Verify that the correct location ID is provided.
KInternalAbort	Server-side issue or unexpected parsing error.	Retry the request or check API status.

Departure

Overview

Departures in Fleet Management SDK define the starting points for vehicle routes. These locations serve as the origin of a route and can impact optimization by influencing travel distance and time.

Departure Structure

Each Departure consists of:

Name	Type	Description	Setter	Getter
DepotId	LargeInteger	Unique identifier for the depot associated with the departure.	✅	✅
Alias	String	Alias name of the departure.	✅	✅
Coordinates	Coordinates	Geographical coordinates (latitude, longitude) of the departure.	✅	✅
MatchedCoordinates	Coordinates	Matched geographical coordinates (latitude, longitude) of the departure.	❌	✅
Address	AddressInfo	Address information of the departure.	✅	✅
NumberOfPackages	unsigned int	Number of packages with which the vehicle is loaded. Default is 0.	❌	✅
Weight	float	Weight with which the vehicle is loaded. Default is 0.	❌	✅
Cube	float	Cubic volume with which the vehicle is loaded. Default is 0.	❌	✅
DepartureTime	Time	Time at which the vehicle departs from the location.	❌	✅
TimeToNext	unsigned int	Time required to travel to the next order.	❌	✅
DistanceToNext	float	Distance to the next order in the distance unit set in the ConfigurationParameters.	❌	✅

Example Usage

Departure departure;
departure.SetAlias("Warehouse A");
departure.SetCoordinates(coordinates);
departure.SetAddress(address);
departure.SetDepotId(12345);

Setting precise departure locations improves route planning and boosts the efficiency of vehicle operations with the Fleet Management SDK.

Destination

Overview

Destinations in Fleet Management SDK define the final stop for a vehicle route. These locations mark the endpoint of a route and play a key role in optimizing route efficiency.

Destination Structure

Each Destination consists of:

Name	Type	Description	Setter	Getter
Alias	String	Alias name of the destination.	✅	✅
Coordinates	Coordinates	Geographical coordinates (latitude, longitude) of the destination.	✅	✅
MatchedCoordinates	Coordinates	Matched geographical coordinates (latitude, longitude) of the destination.	❌	✅
Address	AddressInfo	Address information of the destination.	✅	✅
ArrivalTime	Time	Time at which the vehicle arrives at the destination.	❌	✅
TraveledDistance	float	Distance traveled by the vehicle to reach this destination, in the distance unit set in the ConfigurationParameters.	❌	✅

Example Usage

Destination destination;
destination.SetAlias("Customer B");
destination.SetCoordinates(coordinates);
destination.SetAddress(address);

By accurately managing destination locations, ensures optimal route planning and timely deliveries.