Optimization

ALK_SendRouteHeader

This function is used to pass in the route header information. It is the first function that needs to be called before passing in the stops. It defines driver start time, start location and end location.

CoPilot SDK

long ALK_SendRouteHeader (short sStartTime,
   int lStartStopLat,
   int lStartStopLon,
   int lEndStopLat,
   int lEndStopLon);

Parameters

Return Value

• ≤0 - Failed
• Greater than 0 - Successful

Notes

All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble Maps London office is located at 51.51822N & 0.122805W so it should be pass as a 51518220 latitude & -122805 longitude.

The SDK optimization sample application uses a 24hr format for the input time. The SDK app demonstrates how to convert the time to minutes from midnight. This is because reading the input file is simpler in a 24hr format.

ALK_SendRouteStop

This function will pass the destination address details; including open and close window time and the onsite wait time. This function needs to be called for each destination.

CoPilot SDK

long ALK_SendRouteStop (short sStopNo,
   char *pStreetAddress,
   char *pOptionalAddress1,
   char *pOptionalAddress2,
   char *pOptionalAddress3,
   char *pCity,
   char *pPostalCode,
   char *pCountry,
   int lLat,
   int lLon,

short sStartTimeConstraint,
   short sEndTimeConstraint,
   short sWaitTime);

Parameters

Return Value

• Less than or equal to 0 - Failed
• Greater than 0 - Successful

Notes

All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble Maps London office is located at 51.51822N & 0.122805W so it should be pass as a 51518220 latitude & -122805 longitude.

If the input fileaddress details includes Latitude and Longitude values, CoPilot will only use these for the geocode location for optimizationdetails exclusively, regardless of the addressadditional information passed at the same time. This helps to speed up the optimization process without the need for multiple geocoding. This is different to our API for adding addresses into CoPilot via Msg_TripAddStopWithHouseNum.

Within the input file Stop number 1 should be passed as the first stop and an increment of 1 for each subsequent stop should be passed to ensure consistent output results are received. ` If you wish to define the starting or end stops within an input file and exclude them from the optimization Static Stops enable this. To utilize static stops at the beginning or end of the route the stop should be given the stop number 2001 and incrementing my 1 for each subsequent static stop. Static stops can only be included at the beginning and/or end of an input file. Time windows will not be considered in these cases. For further information please refer to the CoPilot Feature Guide.

Time Constraints

Although CoPilot software does not specifically have any restrictions on the length of Time Constraint window, it is advisable to allow a minimum of 1 hour between the sStartTimeConstraint and sEndTimeConstraint. This allows CoPilot sufficient time to optimize the route efficiently. If you require a time window less than 1 hour please discuss it with us prior to implementation, by emailing .

If the Time Constraint Window is not feasible to be met, i.e. the driver does not leave the depot before the End Time Constraint CoPilot will optimize the stop as soon as possible after the time window has ended.

ALK_SendRouteStopWithBlockWindowTime

This function will pass the destination address details; including open and close window time and the onsite wait time (same as ALK_SendRouteStop), in addition, the blocking window open and close time. A blocking time means, do not reach this destination between these two times. For example a shop is open between 9am to 5 but closes 12pm to 1pm for lunch.

For each destination, any one of the 3 SendRouteStop functions needs to be called

ALK_SendRouteStop
      ALK_SendRouteStopWithBlockWindowTime
      ALK_SendRouteStopWithSecondWindowTime

CoPilot SDK

long ALK_SendRouteStopWithBlockWindowTime (short sStopNo,
               const char *pStreetAddress,
               const char *pCity,
               const char *pPostalCode,
               const char *pCountry,
               long lLat,
               long lLon,
               short sOpenWindowStartTime,
               short sOpenWindowEndTime,
               short sWaitTime,
               short sBlockWindowStartTime,
               short sBlockWindowEndTime);

Parameters

Return Value

• Less than or equal to 0 - Failed
• Greater than 0 - Successful

Notes

All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble Maps London office is located at 51.51822N & 0.122805W so it should be pass as a 51518220 latitude & -122805 longitude.

If the input fileaddress details includes Latitude and Longitude values, CoPilot will only use these for the geocode location for optimizationdetails exclusively, regardless of the addressadditional information passed at the same time. This helps to speed up the optimization process without the need for multiple geocoding. This is different to our API for adding addresses into CoPilot via Msg_TripAddStopWithHouseNum.

Time Constraints, although CoPilot software does not specifically have any restrictions on the length of Time Constraint window, it is advisable to allow a minimum of 1 hour between the sOpenWindowStartTime and sOpenWindowEndTime. This allows CoPilot sufficient time to optimize the route efficiently. If you require a time window less than 1 hour please discuss it with us prior to implementation, by emailing .

If the Time Constraint Window is not feasible to be met, i.e. the driver does not leave the depot before the End Time Constraint CoPilot will optimize the stop as soon as possible after the time window has ended.

If there is no blocking window time, sBlockWindowStartTime and sBlockWindowEndTime can be set as 0.

Within the input file Stop number 1 should be passed as the first stop and an increment of 1 for each subsequent stop should be passed to ensure consistent output results are received.

ALK_SendRouteStopWithSecondWindowTime

This function will pass the destination address details; including open and close window time and the onsite wait time (same as ALK_SendRouteStop), in addition, a second window open and close time.

A second time window is when you provide two positive destination reached time. For example a shop is open between 9am to 12pm and 1pm to 5pm.

For each destination, one of the 3 SendRouteStop functions needs to be called:

• ALK_SendRouteStop
• ALK_SendRouteStopWithBlockWindowTime
• ALK_SendRouteStopWithSecondWindowTime

CoPilot SDK

long ALK_ SendRouteStopWithSecondWindowTime (short sStopNo,
  const char *pStreetAddress,
  const char *pCity,
  const char *pPostalCode,
  const char *pCountry,
  long lLat,
  long lLon,
  short sOpenWindowStartTime,
  short sOpenWindowEndTime,
  short sWaitTime,
  short sSecondWindowStartTime,
  short sSecondWindowEndTime);

Parameters

Return Value

• Less than or equal to 0 = Failed
• Greater than 0 Successful

Notes

All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble Maps London office is located at 51.51822N & 0.122805W so it should be pass as a 51518220 latitude & -122805 longitude.

If the input fileaddress details includes Latitude and Longitude values, CoPilot will only use these for the geocode location for optimizationdetails exclusively, regardless of the addressadditional information passed at the same time. This helps to speed up the optimization process without the need for multiple geocoding. This is different to our API for adding addresses into CoPilot via Msg_TripAddStopWithHouseNum.

Time Constraints

Although CoPilot software does not specifically have any restrictions on the length of Time Constraint window, it is advisable to allow a minimum of 1 hour between the sOpenWindowStartTime and sOpenWindowEndTime. This allows CoPilot sufficient time to optimize the route efficiently. If you require a time window less than 1 hour please discuss it with us prior to implementation, by emailing .

If the Time Constraint Window is not feasible to be met, i.e. the driver does not leave the depot before the End Time Constraint CoPilot will optimize the stop as soon as possible after the time window has ended.

If there is no second open window time, sSecondWindowStartTime and sSecondWindowEndTime can be set as 0.

Within the input file Stop number 1 should be passed as the first stop and an increment of 1 for each subsequent stop should be passed to ensure consistent output results are received.

ALK_SendRouteStopWithBlockWindowTimeWithClusterID

Please use this API only in consultation with us on the implementation as it may have detrimental impact to the optimized output.

This function will pass the destination address details; including open and close window time and the onsite wait time (same as ALK_SendRouteStop), in addition, the blocking window open and close time. A blocking time means, do not reach this destination between these two times. For example a shop is open between 9am to 5 but closes 12pm to 1pm for lunch.

This API also includes the Unique Cluster ID. This can be used to override the CoPilot clustering logic or merge with the CoPilot clustering logic as needed to improve the optimization in line with business process

The Unique cluster ID will coerce the algorithm to cluster destinations together based on these IDs. It never uses only the unique cluster ID by itself and clusters can still break apart during sequencing. However, stops with the same unique cluster ID are more likely to be sequenced together in the end result.

When using the Unique Cluster ID it is possible to set 3 different strictness values using the below Configuration settings added to user.cfg

[Optimization]
"UniqueClusterStrictness"=0

This is the default setting for CoPilot, 0 will disable the use of Unique Cluster IDs using CoPilot clustering logic alone

"UniqueClusterStrictness"=1

This will cluster with CoPilot clustering logic and also try to cluster stops using the Unique Cluster ID. It will also use will use the CoPilot logic to break up clusters when they cause an increase in time window failures.

"UniqueClusterStrictness"=2

Using this setting will place all the emphasis on the Cluster ID, CoPilot cluster logic is disabled, this may lead to an increase of missed Time Windows. It is not advised to use this setting unless you are confident that your clusters are already considering time windows, or if you have minimal time windowed stops

The use of unique clusters is likely to significantly impact the optimized route provided by CoPilot. Without the use of unique clusters CoPilot will implement its own cluster logic and as a result it is not always needed.

For each destination, any one of the 3 SendRouteStop functions needs to be called

• ALK_SendRouteStop
• ALK_SendRouteStopWithBlockWindowTime
• ALK_SendRouteStopWithSecondWindowTime

Syntax (Prototyped in alkmsg.h)

long ALK_SendRouteStopWithBlockWindowTimewithClusterID
  (short sStopNo,
const char *pStreetAddress,
const char *pCity,
const char *pPostalCode,
const char *pCountry,
int lLat,
int lLon,
short sOpenWindowStartTime,
short sOpenWindowEndTime,
short sWaitTime,
short sBlockWindowStartTime,
short sBlockWindowEndTime,
const char *pClusterID);

Parameters

Notes

All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble Maps London office is located at 51.51822N & 0.122805W so it should be pass as a 51518220 latitude & -122805 longitude.

If the input file address details includes Latitude and Longitude values, CoPilot will only use these for the geocode location for optimization details exclusively, regardless of the address additional information passed at the same time. This helps to speed up the optimization process without the need for multiple geocoding. This is different to our API for adding addresses into CoPilot via Msg_TripAddStopWithHouseNumprovided.

Time Constraints

Although CoPilot software does not specifically have any restrictions on the length of Time Constraint window, it is advisable to allow a minimum of 1 hour between the sOpenWindowStartTime and sOpenWindowEndTime. This allows CoPilot sufficient time to optimize the route efficiently.

If the Time Constraint Window is not feasible to be met, i.e. the driver does not leave the depot before the End Time Constraint CoPilot will optimize the stop as soon as possible after the time window has ended.

If there is no blocking window time, sBlockWindowStartTime and sBlockWindowEndTime can be set as 0. Within the input file Stop number 1 should be passed as the first stop and an increment of 1 for each subsequent stop should be passed to ensure consistent output results are received.

Return Value

• Less than or equal to 0 = Failed
• Greater than 0 = Successful

ALK_SendRouteStopWithSecondWindowTimeWithClusterID

Warning: Please use this API only in consultation with us on the implementation as it may have detrimental impact to the optimized output.

This function will pass the destination address details; including open and close window time and the onsite wait time (same as ALK_SendRouteStop), in addition, a second time window open and close time. A second time window is when you provide two positive destination reached times. For example a shop is open between 9am to 12pm and 1pm to 5pm.

This API also includes the Unique Cluster ID. This can be used to override the CoPilot clustering logic or merge with the CoPilot clustering logic as needed to improve the optimization in line with business process.

The Unique cluster ID will coerce the algorithm to cluster destinations together based on these IDs. It never uses only the unique cluster ID by itself and clusters can still break apart during sequencing. However, stops with the same unique cluster ID are more likely to be sequenced together in the end result.

When using the Unique Cluster ID it is possible to set 3 different strictness values using the below Configuration settings added to user.cfg

[Optimization]
"UniqueClusterStrictness"=0

This is the default setting for CoPilot, 0 will disable the use of Unique Cluster IDs using CoPilot clustering logic alone

"UniqueClusterStrictness"=1

This will cluster with CoPilot clustering logic and also try to cluster stops using the Unique Cluster ID. It will also use will use the CoPilot logic to break up clusters when they cause an increase in time window failures.

"UniqueClusterStrictness"=2

Using this setting will place all the emphasis on the Cluster ID, CoPilot cluster logic is disabled, this may lead to an increase of missed Time Windows. It is not advised to use this setting unless you are confident that your clusters are already considering time windows, or if you have minimal time windowed stops

The use of unique clusters is likely to significantly impact the optimized route provided by CoPilot. Without the use of unique clusters CoPilot will implement its own cluster logic and as a result it is not always needed.

For each destination, any one of the 3 SendRouteStop functions needs to be called:

• ALK_SendRouteStop
• ALK_SendRouteStopWithBlockWindowTime
• ALK_SendRouteStopWithSecondWindowTime

Syntax (Prototyped in alkmsg.h)

long ALK_SendRouteStopWithSecondWindowTimewithClusterID
  (short sStopNo,
const char *pStreetAddress,
const char *pCity,
const char *pPostalCode,
const char *pCountry,
int lLat,
int lLon,
short sOpenWindowStartTime,
short sOpenWindowEndTime,
short sWaitTime,
short sSecondWindowStartTime,
short sSecondWindowEndTime,
const char *pClusterID);

Parameters

Notes

All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble Maps London office is located at 51.51822N & 0.122805W so it should be pass as a 51518220 latitude & -122805 longitude.

If the input file address details includes Latitude and Longitude values, CoPilot will only use these for the geocode location for optimization details exclusively, regardless of the address additional information passed at the same time. This helps to speed up the optimization process without the need for multiple geocoding. This is different to our API for adding addresses into CoPilot via Msg_TripAddStopWithHouseNumprovided.

Time Constraints

Although CoPilot software does not specifically have any restrictions on the length of Time Constraint window, it is advisable to allow a minimum of 1 hour between the sOpenWindowStartTime and sOpenWindowEndTime. This allows CoPilot sufficient time to optimize the route efficiently. If the Time Constraint Window is not feasible to be met, i.e. the driver does not leave the depot before the End Time Constraint CoPilot will optimize the stop as soon as possible after the time window has ended. If there is no second time window, sSecondWindowStartTime and sSecondWindowEndTime can be set as 0. Within the input file Stop number 1 should be passed as the first stop and an increment of 1 for each subsequent stop should be passed to ensure consistent output results are received.

Return Value

• Less than or equal to 0 = Failed
• Greater than 0 = Successful

ALK_StartETACalculation

After passing route header and destination details, call this function to start the Optimization and/or ETA calculation process.

This event will also return notifications and error values:

• Notifications: Geocoding started, geocoding completed, Calculation started, Calculation Completed, Calculation Timed Out, Calculation user cancelled, Calculation is running,

• Errors: Depot non geocodable, geocoding stop errors, destination geocoded significant distance from other stops, destination will not be reached before midnight, complete route cannot be completed within 24 hours.

• Geocode Results: This will return the latitude and longitude locations for every destination passed to CoPilot.

CoPilot SDK

long ALK_StartETACalculation     (void *pEventCallback,
  long lTimeOut,
  bool bOptimize, callingConvention convention = convention_default,
  long lDestID =CONN_ID_NONE,
  long lSrcID = CONN_ID_NONE);

Parameters

Return Value

• ≤0 Failed
• Greater than 0 = Successful

enum callingConvention {
   convention_default,
   convention_cdecl,
   convention_stdcall
};

void ETACallback (ETAEvent sEvent,
       int info1,
       int info2,
       int info3,
       int info4 );

//If bOptimize = false
typedef enum
{

HEADER_DETAILS,                   //info1 : ETA for the end stop (typically depot)
                                  //info2 : Total distance from start depot to end depot by using given stop sequence in miles
                                  //info3 : Unused
                                  //info4 : Unused

STOP_DETAILS,                     //info1 : Given stop sequence number
                                  //info2 : ETA based on given stop sequence
                                  //info3 : Unused
                                  //info4 : Distance in miles from previous stop. It will express as a long value in hundredth of actual value. To get actual value, divide the value by 100. If distance between stop is 2.7 miles, it will return as a 270.

ETA_CALCULATION_STARTED,          //Ignore all the parameter
ETA_CALCULATION_COMPLETED,        //Ignore all the parameter
ETA_CALCULATION_TIMEOUT,          //Ignore all the parameter
ETA_CALCULATION_CANCEL,           //Ignore all the parameter
ETA_CALCULATION_RUNNING,          //Ignore all the parameter
ETA_DEPOT_NONGEOCODABLE           //Ignore all the parameter
ETA_STOP_ERRORS                   //info1 : Stop error type
                                  //info2 : Additional info based on error code
ETA_EVENT_NOTIFICATION            //info1 : Notification Type
                                  //info2 : Notification Related Info
                                  //info3 : Notification Related Info
                                  //info4 : Notification Related Info
STOP_GEOCODE_RESULT               //info1 : Given stop sequence number
                                  //info2 : Latitude of stop
                                  //info3 : Longitude of stop
                                  //info4 : Currently not supported
} ETAEvent;

//If bOptimize = true
typedef enum
{
HEADER_DETAILS,                    //info1 : Optimized ETA for the end stop (typically depot)
                                   //info2 : Total distance from start Depot to end depot by using optimized route in miles
                                   //info3 : Unused
                                   //info4 : Unused

STOP_DETAILS,                      //info1 : Given stop sequence number
                                   //info2 : ETA based on optimized stop sequence
                                   //info3 : Optimized stop sequence number
                                   //info4 : Distance in miles from previous stop. It will express as a long value in hundredth of actual value. To get actual value, divide the value by 100. If distance between stop is 2.7 miles, it will return as a 270.

ETA_CALCULATION_STARTED,           //Ignore all the parameter
ETA_CALCULATION_COMPLETED,         //Ignore all the parameter
ETA_CALCULATION_TIMEOUT,           //Ignore all the parameter
ETA_CALCULATION_CANCEL,            //Ignore all the parameter
ETA_CALCULATION_RUNNING,           //Ignore all the parameter
ETA_DEPOT_NONGEOCODABLE,           //Ignore all the parameter
ETA_STOP_ERRORS                    //info1 : Stop error type
                                   //info2 : Additional info based on error code

ETA_EVENT_NOTIFICATION             //info1 : Notification Type
                                   //info2 : Notification Related Info
                                   //info3 : Notification Related Info
                                   //info4 : Notification Related Info

STOP_GEOCODE_RESULT                //info1 : Given stop sequence number
                                   //info2 : Latitude of stop
                                   //info3 : Longitude of stop
                                   //info4 : Currently not supported

} ETAEvent;

sEvent : Event depending upon the progress of optimization

#define STOP_ERROR_MAXDISTANCE       0x02
#define STOP_ERROR_DELIVERY_24HOURS  0x03
#define STOP_ERROR_DELIVERY_MIDNIGHT 0x04
#define STOP_ERROR_TIME_WINDOW       0x05
#define STOP_ERROR_WAIT_TIME         0x06

STOP_ERROR_MAXDISTANCE: Will provide notification when stop is more than 100 miles away from route, this stop will be removed from the optimization list. info2 contain original stop number.

Max Distance Error configuration.

By default CoPilot sets the max distance as 100 miles, this is measured as a matrix of all stops to identify any that are potentially in correct locations. This means that if a destination is over 100 miles away from all other stops it will be removed from the optimization. To change the default value add the following section to the:

Program Files / CoPilot / user.cfg file

[Optimization]

“MaxAirTravelMile”=100

STOP_ERROR_DELIVERY_24HOURS: Will provide notification when delivery time will take more than 24 hours.

STOP_ERROR_DELIVERY_MIDNIGHT: Will provide notification when delivery time for given stop pass through midnight. info2 contain original stop number. info 2 contains negative value for returning depot.

STOP_ERROR_TIME_WINDOW This provides notification when the destination close time is earlier than its own start time or the depot start time.

STOP_ERROR_WAIT_TIME This provides notification when wait time for a regular stop is more than 30 minutes or wait time for a break stop is more than 2 hours.

STOP_ERROR_BREAK_INSERT This provides notification a stop was marked as a break stop but could not be inserted into the end sequence. Common reasons for this error include setting a break time outside of the driver’s working hours or setting a final break time after the final stop has been completed.

ETA_EVENT_NOTIFICATION: It will provide different type of notification from the optimization engine e.g. Geocode started, Geocode Finished etc. Following section contain different notification type supported.

#define GEOCODE_STARTED 0x01 #define GEOCODE_FINISHED 0x02

GEOCODE_STARTED: Will provide notification when optimization engine start the geocoding of the stops.

GEOCODE_FINISHED: Will provide notification when optimization engine finish the geocoding of the stops.

STOP_GEOCODE_RESULT: It will provide Geocoded latitude and longitude of the stops. Optimization engine will provide this information during the geocoding of the stops. While passing the stop, if already contains the latitude/longitude, optimization engine will not provide this information.

ALK_StopETACalculation

This call will stop the ETA calculation process at an appropriate time.

CoPilot SDK

  long ALK_StopETACalculation (long lDestID =CONN_ID_NONE,
  long lSrcID = CONN_ID_NONE);

Parameters

Return Value

• Less than or equal to 0 = Failed
• Greater than 0 = Successful