Skip to content

RouteMgr

Overview
Description A class containing static methods related to a route, defined as a list of stops and a route that is calculated between them.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Class
Package com.alk.cpik.route

Methods

Method Name Return Type Description
setActiveVehicleRoutingProfile(VehicleRoutingProfile)
Available in CoPilot 10.9 and Higher
void Sets the active VehicleRoutingProfile to be used in routing.
getActiveVehicleRoutingProfile()
Available in CoPilot 10.9 and Higher
VehicleRoutingProfile Gets the active VehicleRoutingProfile being used in routing.
getVehicleRoutingProfiles()
Available in CoPilot 10.9 and Higher
List of VehicleRoutingProfile Returns a list of all of the routing profiles that are currently available in CoPilot.
getVehicleRoutingProfile(String profileName)
Available in CoPilot 10.9 and Higher
VehicleRoutingProfile Searches CoPilot for a VehicleRoutingProfile with the given name.
resetVehicleRoutingProfileToDefault(String profileName)
Available in CoPilot 10.9 and Higher
boolean Resets the specified VehicleRoutingProfile to the default for that vehicle type.
addVehicleRoutingProfile(VehicleRoutingProfile routingProfile, boolean overwriteIfNameExists)
Available in CoPilot 10.9 and Higher
RoutingProfileAdditionResult Adds a new routing profile to CoPilot.
optimizeStops (boolean) boolean Will attempt to optimize the current trip. 1. bKeepFinalDestination is false if the number of stops <= 2 , otherwise, bKeepFinalDestination is true.
addStop(AddStopPurpose, Stop, RoutePreviewMode) void Geocodes and inserts a stop into CoPilot's active route.
addStops(AddStopPurpose, StopList, RoutePreviewMode) void Geocodes and inserts a list of stops into CoPilot's active route.
calculateRoute() void If valid stops have been added, this causes a route to be calculated between them.
removeAllStops() void Passing this API will clear the trip list, removing all destinations in the active trip. Once passed the trip list will be empty.
getStopList() StopList Returns a list of stops currently added to the trip.
pickStopFromGeoUri (String) void When passed a stop to CoPilot via this API it will find the location on the map.
hasDestination() boolean The active trip is said to have a destination if there are at least 2 valid stops in the trip and there is a route calculated between them.
latLonAheadOnRoute (int) Coordinate Returns a Coordinate object with the latitude and longitude of the position a variable number of minutes ahead on the current route
isCopilotReadyToAddStops() boolean Returns whether or not CoPilot is ready to add stops
isReceivingGPSSignal() boolean Returns whether CoPilot is actively receiving a GPS signal
getRouteLegs() List<Leg> Returns a list of each leg along the current route.

Hooks and Callbacks

Hooks and Callbacks related to routing can be found below. Please refer to the Hooks and Callbacks section of this guide for more information.

RouteListener
onGPSFixChanged
onStopsAdded
onStopsMoved
onStopsReplaced
onStopsDeleted
onReadyToAddStops
onStartRouteCalculation
onCompleteRouteCalculation
onFailedRouteCalculation
onOutOfRoute
onRejoinRoute
onStartChangeVehicleType
onFinishChangeVehicleType
onRouteSyncError
onRouteSyncRouteIntegrated
onRouteCalculation
onStartAlternateRouteCalculation*
onCompleteAlternateRouteCalculation*
onAlternateRouteSelected*

*only supported in CoPilot v9.6.8


RouteMgr.setActiveVehicleRoutingProfile

Overview
Description CoPilot requires a vehicle routing profile to generate appropriate routes. By using this API, the active routing profile can be set as detailed within the VehicleRoutingProfile. This profile should be used to define the vehicle that is being driven. This may range from a Truck to a Car.

The vehicle types available are defined by your CoPilot license. (Truck profiles, for example, require an additional license attribute.) Further details on routing per vehicle type can be found within the routing section of the CoPilot feature guide.

Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik.route

Syntax public static void setActiveVehicleRoutingProfile(VehicleRoutingProfile routingProfile)

Parameters VehicleRoutingProfile routingProfile - The profile to set in copilot

Sample Code

// Create a new heavy duty truck profile, "CPIK Test", with default values
// Then set this profile as the current profile in copilot
try {
  VehicleRoutingProfile rp = VehicleRoutingProfile.createNewProfile("CPIK Test", VehicleType.TRUCK_HEAVY_DUTY);
  RouteMgr.setActiveVehicleRoutingProfile(rp);
} catch (Exception profileException) { System.out.println(profileException.getMessage()); }

RouteMgr.getActiveVehicleRoutingProfile

Overview
Description CoPilot will always have a vehicle routing profile set following the first installation. To identify the profile that is currently active, this API will provide those details and will return VehicleRoutingProfile.
Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik.route

Syntax public static VehicleRoutingProfile getActiveVehicleRoutingProfile()

Return Values VehicleRoutingProfile - A representation of copilot’s currently selected routing profile

Sample Code

// Check and print copilot's current active profile
VehicleRoutingProfile currentProfile = RouteMgr.getActiveVehicleRoutingProfile();
System.out.println("Current profile: " + currentProfile.toString());

RouteMgr.getVehicleRoutingProfiles

Overview
Description Returns a list of all of the routing profiles that are currently available in CoPilot. This will include the CoPilot default profiles as well as those which may have been created on the device or sent via API integration.
Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik.route

Syntax

public static List<VehicleRoutingProfile> getVehicleRoutingProfiles()

Return Values

List- A list of all routing profiles in CoPilot

Sample Code

// Print out the list of all of the routing profiles in copilot
List<VehicleRoutingProfile> allProfiles = RouteMgr.getVehicleRoutingProfiles();
for (VehicleRoutingProfile rp : allProfiles)
  System.out.println(rp.toString());

RouteMgr.getVehicleRoutingProfile

Overview
Description Searches CoPilot for a VehicleRoutingProfile with the given name. If a match is found, the VehicleRoutingProfile will be returned. If a match is not found, null will be returned.
Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik.route

Syntax

public static VehicleRoutingProfile getVehicleRoutingProfile(String profileName)

Parameters String profileName - The profile name to search for. Starting with CoPilot 10.14, you can choose from default vehicle routing profiles specific to each by region of the world.

Return Values VehicleRoutingProfile - The profile found that matches the search name, or null if no match was found.

Sample Code

// Print out the profile with the given name
VehicleRoutingProfile matchProfile = RouteMgr.getVehicleRoutingProfile("Test");
if (matchProfile == null)
  System.out.println("No match found");
else
  System.out.println("Match: " + matchProfile .toString());

RouteMgr.resetVehicleRoutingProfileToDefault

Overview
Description Resets the specified VehicleRoutingProfile to the default for that vehicle type. This will perform the same action as clicking “Reset to Default” in the UI for a given routing profile. The name is not case sensitive.
Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik.route

Syntax public static boolean resetVehicleRoutingProfileToDefault(String profileName)

Parameters String profileName - The profile name to reset

Return Values Boolean - True if the specified profile was found and reset, false otherwise.

Sample Code

// Reset profile “ResetTest”
boolean result = RouteMgr.resetVehicleRoutingProfileToDefault("ResetTest");

RouteMgr.addVehicleRoutingProfile

Overview
Description Use this API when you would like to add a new routing profile to CoPilot. This should be used for all vehicle types, from Auto to different Truck types.

Routing profiles should have unique names. Duplicate names will not be supported within CoPilot. To update an existing profile, the additional parameter overwriteIfNameExists should be passed.

Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik.route

Syntax public static RoutingProfileAdditionResult addVehicleRoutingProfile(VehicleRoutingProfile routingProfile, boolean overwriteIfNameExists)

Parameters VehicleRoutingProfile routingProfile - The routing profile to add into CoPilot boolean overwriteIfNameExists - Whether or not to overwrite an existing profile if an existing profile is found with the same name as the given profile.

Return Values RoutingProfileAdditionResult - The result of the attempted profile addition

Sample Code

// Create a new heavy duty truck profile, "CPIK Test", with default values
// Add that new routing profile into copilot.  Note that this does not change the active profile.
try {
  VehicleRoutingProfile rp = VehicleRoutingProfile.createNewProfile("CPIK Test", VehicleType.TRUCK_HEAVY_DUTY);
  RouteMgr.addVehicleRoutingProfile(rp, true);
} catch (Exception profileException) { System.out.println(profileException.getMessage()); }

RouteMgr.resetUserRoadSpeeds

Overview
Description Resets user-specified custom road speeds to the default road speeds provided CoPilot. By default, no custom road speeds should be specified unless they were changed by the user in the CoPilot user interface.

Custom road speeds can only be set via API, not the CoPilot UI, from version 10.9.0 and up.

Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik.route

Syntax public static void resetUserRoadSpeeds(VehicleType vehicleType, String jurisdiction)

Parameters

VehicleType vehicleType - The vehicle type to reset road speeds for. This field is mandatory.
String jurisdiction - The jurisdiction to reset road speeds for. These jurisdiction codes can be found by calling RouteMgr.getDefaultRoadSpeeds(vehicleType, null). If null or empty string, all jurisdictions for this vehicle type will be reset.

Sample Code

// Reset user road speeds for medium duty truck in NJ
RouteMgr.resetUserRoadSpeeds(VehicleType.TRUCK_MEDIUM_DUTY, "New Jersey");
// Delete all user speeds for heavy duty truck for all jurisdictions
RouteMgr.resetUserRoadSpeeds(VehicleType.TRUCK_HEAVY_DUTY, null);

RouteMgr.setUserRoadSpeeds

Overview
Description Per vehicle type, road speeds can be set for each road class and jurisdiction. Changing the default road speeds that come with CoPilot will have a drastic effect on ETA calculations. While altering these speeds is not recommended, you can use this API to set the road speeds for a routing profile.

This API allows setting custom road speeds for individual road classes on a per vehicle type and per jurisdiction basis.

Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik.route

Syntax public static void setUserRoadSpeeds(RoadSpeedSet roadSpeedSet)

Parameters RoadSpeedSet roadSpeedSet - The custom road speed set to set in copilot

Sample Code

// Set custom rural highway road speed of 60 mph for trucks in NJ
SpeedUnit customSpeed = SpeedUnit.fromMPH(60);
RoadSpeedSet rss = new RoadSpeedSet();
rss.setVehicleType(VehicleType.TRUCK_HEAVY_DUTY);
rss.setJurisdiction("New Jersey");
rss.setSpeed(RoadClass.INTERSTATE, RoadArea.RURAL, customSpeed);
RouteMgr.setUserRoadSpeeds(rss);

RouteMgr.getUserRoadSpeeds

Overview
Description Returns a list of custom road speeds that have been set by the user in CoPilot. This will return each custom road speed per jurisdiction. If no custom road speeds have been set, this API will return null.
Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik.route

Syntax static List<​RoadSpeedSet> getUserRoadSpeeds(VehicleType vehicleType, String jurisdiction)

Parameters

VehicleType vehicleType - The vehicle type to get the custom road speeds for. This field is mandatory. Passing in an invalid vehicle type of null will result in a null value being returned.
String jurisdiction - The jurisdiction to get the custom road speeds for. Passing null or empty string will return all jurisdictions.

Return Values List<​RoadSpeedSet> - A list of RoadSpeedSet objects representing the user road speeds that are set in CoPilot.

Sample Code

// Get and print user road speeds for medium duty truck in NJ
List<RoadSpeedSet> userSpeedNJ = RouteMgr.getUserRoadSpeeds(VehicleType.TRUCK_MEDIUM_DUTY, "New Jersey");
System.out.println("Custom speeds for medium duty truck in NJ: " + userSpeedNJ.get(0).toString());
// Get and print all user road speeds for heavy duty truck
List<RoadSpeedSet> allUserSpeeds = RouteMgr.getUserRoadSpeeds(VehicleType.TRUCK_HEAVY_DUTY, null);
for (RoadSpeedSet rss : allUserSpeeds)
  System.out.println(rss.toString());

RouteMgr.getDefaultRoadSpeeds

Overview
Description Returns the list of default road speeds in CoPilot per vehicle type.
Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik.route

Syntax public static List<​RoadSpeedSet> getDefaultRoadSpeeds(VehicleType vehicleType, String jurisdiction)

Parameters VehicleType vehicleType - The vehicle type to get the default road speeds for. This field is mandatory. Passing null or an invalid vehicle type will result in a null value being returned. String jurisdiction - The jurisdiction to get the default road speeds for. Passing null or empty string will return all jurisdictions.

Return Values List<​RoadSpeedSet> - A list of RoadSpeedSet objects representing the default road speeds that are set in CoPilot.

Sample Code

// Get and print default road speeds for medium duty truck in NJ
List<RoadSpeedSet> roadSpeedsNJ = RouteMgr.getDefaultRoadSpeeds(VehicleType.TRUCK_MEDIUM_DUTY, "New Jersey");
System.out.println("Custom speeds for medium duty truck in NJ: " + roadSpeedsNJ.get(0).toString());
// Get and print default road speeds for heavy duty truck in all jurisdictions
List<RoadSpeedSet> allDefaultRoadSpeeds = RouteMgr.getDefaultRoadSpeeds(VehicleType.TRUCK_HEAVY_DUTY, null);
for (RoadSpeedSet rss : allDefaultRoadSpeeds)
  System.out.println(rss.toString());

RouteEnums.VehicleProfileModificationResult

Overview
Description The result of an attempted modification to a field in a VehicleRoutingProfile.
Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Enum
Package com.alk.cpik.route
Value Description
SUCCESS The field was changed successfully
FAILED_OPTION_NOT_SUPPORTED_FOR_VEHICLE_TYPE The field is not supported for the profile’s vehicle type
FAILED_OPTION_NOT_SUPPORTED_FOR_REGION The field is not supported for the profile’s region
LENGTH_OUT_OF_RANGE_FOR_VEHICLE_TYPE The length is out of range for the profile’s vehicle type. The value was still set, but was rounded up or down to match the min or max value.
WIDTH_OUT_OF_RANGE_FOR_VEHICLE_TYPE The width is out of range for the profile’s vehicle type. The value was still set, but was rounded up or down to match the min or max value.
HEIGHT_OUT_OF_RANGE_FOR_VEHICLE_TYPE The height is out of range for the profile’s vehicle type. The value was still set, but was rounded up or down to match the min or max value.
TOTAL_WEIGHT_OUT_OF_RANGE_FOR_VEHICLE_TYPE The weight is out of range for the profile’s vehicle type. The value was still set, but was rounded up or down to match the min or max value.
WEIGHT_PER_AXLE_OUT_OF_RANGE_FOR_VEHICLE_TYPE The weight per axle is out of range for the profile’s vehicle type. The value was still set, but was rounded up or down to match the min or max value.

RouteEnums.RouteCalculationError

Overview
Description The error code for why a route calculation failed.
Supported Since Version 10.14
Platforms Supported Android, Linux, iOS
Type Enum
Package com.alk.cpik.routeEnums
Value Description
ROUTE_CANCELLED The routing operation was cancelled.
INVALID_STOP The stop could not be geocoded.
NO_ROUTE_POSSIBLE No route can be calculated between the entered stops.

RouteMgr.isCopilotReadyToAddStops

Overview
Description Returns whether or not CoPilot is ready to add stops, this should be called before a stop is passed to CoPilot.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

static Boolean isCopilotReadyToAddStops()
+(bool) isCopilotReadyToAddStops

Return Value

Returns boolean value whether or not CoPilot is ready to add stops

Sample Code

// Get whether or not CoPilot is ready to add stops
boolean iSReadyToAddStops = RouteMgr.isCopilotReadyToAddStops();
if (iSReadyToAddStops)
  System.out.println("CoPilot is ready to add stops");
else
  System.out.println("CoPilot is NOT ready to add stops");
NSLog([NSString stringWithFormat:@"Ready To Add Stops: %@", ([RouteMgr isCopilotReadyToAddStops] == true) ? @"True" : @"False"]);

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RouteMgr.addStop

Overview
Description Geocodes and inserts a stop into CoPilot's active route. When passing in a stop and you wish to receive alternate route data via RouteListener callbacks, RoutePreviewMode should not be set as NO_PREVIEW. RouteMgr.selectAlternateRoute can then be used to select the route to navigate.

CoPilot provides different kinds of route previews. By using RoutePreviewMode parameter, you can define the route preview screen you want to be shown in the CoPilot UI.

If you are already on one of the route preview screens in the CoPilot UI and you call the this API with RoutePreviewMode set as NO_PREVIEW, the API will retain user’s current view instead of going to the navigation screen.

Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik.route

Note

When you have a Latitude and Longitude value as well as the street address, CoPilot will prioritize the information provided.

Scenario 1 – Only the full address is passed

  • CoPilot will try to geocode the address.

Scenario 2 – Only lat/long is passed

  • CoPilot will try to use lat/long to provide the route.

Scenario 3 – Both Address and lat/long are passed

  • CoPilot will geocode the address and compare the air distance between the address location and the input lat/lon. If the input street name is within 0.5 miles of the input lat/lon, then CoPilot will route to a point closest to the lat/lon on that input street.

    If the input street name is not within 0.5 miles of the input lat/lon, CoPilot will route to a point on the closest street to the input lat/lon. It will also send "ERROR_STREET_NOT_FOUND."

Tip

When passing UK Postcodes note that this will be used as the sole location for geocoding an address. UK postcodes are simply lat/long points and are a useful tool to quickly geocode an address. As a result, when passing a UK postcode and a lat/long, CoPilot will geocode the postcode not the lat/long. It is not advised that both UK postcode and lat/long coordinates are passed together and as a result we recommend the following:

  • If you have lat/long for a destination pass the lat/long. Optional extras include House Number, Street Name, City Name, Country. Do not include UK Postcode if you have a lat/long for a destination

  • Pass UK postcode. Optional extras include House Number, Street Name, City Name, Country.

Syntax

static void addStop(AddStopPurpose purpose, Stop stop, RoutePreviewMode mode)

Parameters

AddStopPurpose - An enumerated value that describes how to incorporate a stop into a trip.

Stop - A stop object.

RoutePreviewMode - An enumerated value that tells CoPilot what route preview that user wants to show in CoPilot UI.

Sample Code

// Make a new stop to add
StopBuilder sb = StopBuilder.fromLatLon(new Coordinate(40.368273, -74.654965));
Stop newStopToAdd = sb.geocode(GeocodeSearchType.BEST_MATCH);

// Clear the current route and add the new stop
RouteMgr.addStop(RouteEnums.AddStopPurpose.NEW_TRIP, newStopToAdd, RoutePreviewMode.PREVIEW_TRIP_MAP);

RouteMgr.addStops

Overview
Description Geocodes and inserts a list of stops into CoPilot's active route. When passing in a stop and you wish to receive alternate route data via RouteListener callbacks, RoutePreviewMode should not be set as NO_PREVIEW.

CoPilot provides different kind of route previews. By using RoutePreviewMode parameter, you can decide whether or not to show the route preview and what preview screen you want to show in CoPilot UI.

If you are already on one of the route preview screens in CoPilot UI and you call the this API with RoutePreviewMode set as NO_PREVIEW, the API will retain user’s current view instead of going to the navigation screen.

Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik

Note

When you have a Latitude and Longitude value as well as the street address, CoPilot will prioritize the information provided.

Scenario 1 – Only the full address is passed

  • CoPilot will try to geocode the address.

Scenario 2 – Only lat/long is passed

  • CoPilot will try to use lat/long to provide the route.

Scenario 3 – Both Address and lat/long are passed

  • CoPilot will geocode the address and compare the air distance between the address location and the input lat/lon. If the input street name is within 0.5 miles of the input lat/lon, then CoPilot will route to a point closest to the lat/lon on that input street.

    If the input street name is not within 0.5 miles of the input lat/lon, CoPilot will route to a point on the closest street to the input lat/lon. It will also send "ERROR_STREET_NOT_FOUND."

Tip

When passing UK Postcodes note that this will be used as the sole location for geocoding an address. UK postcodes are simply lat/long points and are a useful tool to quickly geocode an address. As a result, when passing a UK postcode and a lat/long, CoPilot will geocode the postcode not the lat/long. It is not advised that both UK postcode and lat/long coordinates are passed together and as a result we recommend the following:

  • If you have lat/long for a destination pass the lat/long. Optional extras include House Number, Street Name, City Name, Country. Do not include UK Postcode if you have a lat/long for a destination

  • Pass UK postcode. Optional extras include House Number, Street Name, City Name, Country.

Syntax

static void addStop(AddStopPurpose purpose, StopList stops, RoutePreviewMode mode)

Parameters RoutePreviewMode - An enumerated value what tells CoPilot what route preview that user wants to show in CoPilot UI.

Sample Code

// Make new stops to add
StopBuilder sbA = StopBuilder.fromLatLon(new Coordinate(40.368273, -74.654965));
Stop newStopToAddA = sbA.geocode();
StopBuilder sbB = StopBuilder.fromLatLon(new Coordinate(40.345621, -74.645877));
Stop newStopToAddB = sbB.geocode();
List<Stop> stopList = new StopList<Stop>();
stopList.add(newStopToAddA);
stopList.add(newStopToAddB);

// Add these new stops to the trip, after the final destination
RouteMgr.addStops(RouteEnums.AddStopPurpose.AFTER_FINAL_DESTINATION, stopList, RouteEnums.RoutePreviewMode.PREVIEW_TRIP_MAP);

RoutePreviewMode

Overview
Description An enumerated value which will be used by RouteMgr.addStop and RouteMgr.addStops to tell CoPilot what route preview that the user wants to be shown in the CoPilot UI.
Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Enum
Package com.alk.cpik.route

Values

Value Description
NO_PREVIEW Don't show the route preview
PREVIEW_TRIP_PLAN Show route preview with plan view
PREVIEW_TRIP_MAP Show route preview with map view
PREVIEW_TRIP_MAP_NO_WIDGET Show route preview with map view without widgets. (Map only, no buttons, menus or labels)

RouteMgr.pickStopFromGeoUri

Overview
Description The geo URI scheme is a Uniform Resource Identifier (URI) scheme defined by the Internet Engineering Task Force. The URI geo finds a physical location using address or coordinate information. When passed to CoPilot via this API it will find the location on the map.

The URI format follows the scheme outlined within android standards located on developer.android.com.

Supported on Android Since Version 9.6.0.821
Type Method
Package com.alk.cpik.route

Syntax

static void pickStopFromGeoUri(String)

Sample Code

// Find a uri on the map
String sampleUri = "geo:0,0?q=254+Nassau+Street+Princeton,NJ+08542";
try {
  RouteMgr.pickStopFromGeoUri(sampleUri);
} catch (CopilotException e) {
  e.printStackTrace();
}

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RouteMgr.deleteStop

Overview
Description When CoPilot has a route loaded, by using this API you can delete a stop from the active route. This API should be used in conjunction with RouteMgr.addStops or RouteMgr.addStop and StopBuilder which are used to add stops to a route.

The next stop or final destination can be deleted by using the NEXT_STOP or FINAL_STOP values. They are both static const values in RouteMgr class. If you wish to delete another stop that is within your current trip list you can pass the stop index number to this API.

To return the stop list with the index numbers use RouteMgr.getStopList which returns the StopList object with these details.

NEXT_STOP and FINAL_STOP will never delete your current gps location. For example, while in trip plan screen, you can have a trip with only your current gps location, nothing will happen if you call deleteStop(RouteMgr.NEXT_STOP) or deleteStop(RouteMgr.FINAL_STOP) in this case. But if you call deleteStop(0), your gps location will be deleted.

Note: The index of each stop will change as you travel or delete other stops. The index is not unique for each trip planned. It is recommended that RouteMgr.getStopList is always called before using the index value to verify the correct stop is being deleted. When in navigation please note you are not able to delete your current location.Always pass index of further stop.

Supported on Android Since Version 10.9
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

static void deleteStop(int index)
+(void) deleteStop:(int)index

Parameters int - The index number of the stop that you want to delete. There are two preset value NEXT_STOP and FINAL_STOP. You can use them to delete your next stop or final stop without figuring out the actual index of them.

Sample Code

// Delete your next stop
RouteMgr.deleteStop(RouteMgr.NEXT_STOP);
// Delete your last stop
RouteMgr.deleteStop(RouteMgr.FINAL_STOP);

// Delete the stop of index 2 in your trip
RouteMgr.deleteStop(2);
// Delete your next stop
[RouteMgr deleteStop:[RouteMgr NEXT_STOP]];

// Delete your last stop
[RouteMgr deleteStop:[RouteMgr FINAL_STOP]];

// Delete the stop of index 2 in your trip
[RouteMgr deleteStop:2];

RouteMgr.removeAllStops

Overview
Description Passing this API will clear the trip list, removing all destinations in the active trip. Once passed the trip list will be empty.

Search Keywords: Clear Trip, Delete Trip, Clear Stop, Delete Stop, Remove Stop, Clear Destination, Delete Destination, Remove Destination

Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

void removeAllStops() throws CoPilotException
+(void)removeAllStops

Sample Code

try {
  // Clear all stops on the route
  // After this call, there will be zero stops on the route
  RouteMgr.removeAllStops();
} catch (CopilotException e) {
  e.printStackTrace();
}
[RouteMgr removeAllStops];

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

RouteMgr.AddStops RouteMgr.GetStopList RouteMgr.CalculateRoute RouteMgr.optimizeStops


RouteMgr.getStopList

Overview
Description Returns a list of stops currently added to the trip.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

StopList getStopList() throws RouteException, CopilotException
+(NSArray*) getStopList

Return Value

A list of Stop objects that represents the stops on the current route.

Sample Code

try {
  // Get the list of stops on the route
  List<Stop> currentStopList = RouteMgr.getStopList();
  System.out.println("There are " + String.valueOf(currentStopList.size()) + "stops on the current route");
  System.out.println("The first stop on the route is: " + currentStopList.get(0).toString());
} catch (CopilotException | RouteException e) {
  e.printStackTrace();
}
NSArray *stops = [RouteMgr getStopList];
 int i = 0;
 for(Stop *stop in stops)
{
 NSLog([NSString stringWithFormat:@"Destination: %@", (stop.isDestination == true) ? @"True" : @"False"]);
 NSLog(self makeToast:[NSString stringWithFormat:@"Name: %@", stop.name]);
}

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs RouteMgr.AddStops() RouteMgr.RemoveAllStops() RouteMgr.CalculateRoute() RouteMgr.optimizeStops()


RouteMgr.calculateRoute

Overview
Description If valid stops have been added, this causes a route to be calculated between them.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

void calculateRoute()
+(void) calculateRoute

Sample Code

try {
  // Clear all stops on the route
  RouteMgr.removeAllStops();

  double latitudeA = 40.368420;
  double longitudeA = -74.655036;
  // Make new stops to add
  StopBuilder sbA = StopBuilder.fromLatLon(new Coordinate(latitudeA, longitudeA));
  Stop newStopToAddA = sbA.geocode(GeocodeSearchType.BEST_MATCH).get(0);

  double latitudeB = 40.368530;
  double longitudeB = -74.6552036;
  StopBuilder sbB = StopBuilder.fromLatLon(new Coordinate(latitudeB, longitudeB));
  Stop newStopToAddB = sbB.geocode(GeocodeSearchType.BEST_MATCH).get(0);

  StopList stopList = new StopList();
  stopList.add(newStopToAddA);
  stopList.add(newStopToAddB);
  // Add these new stops to the trip, after the final destination
  RouteMgr.addStops(RouteEnums.AddStopPurpose.AFTER_FINAL_DESTINATION, stopList, RoutePreviewMode.PREVIEW_TRIP_MAP);
} catch (CopilotException | GeocodingException | RouteException e) {
  e.printStackTrace();
}
// At this point, the route will not have yet been calculated, there are stops but no route
// Make the call to calculate the route
RouteMgr.calculateRoute();
// After the call, the route will be calculated between the stops on the route.
NSMutableArray *stops = [[NSMutableArray alloc] init];
StopBuilder *stopBuilder = [StopBuilder fromCountryAndPostalCode:@USA withZip:@08540];
Stop *stop2 = [stopBuilder2 getStop];
[stops addObject:stop2];
StopBuilder *stopBuilder = [StopBuilder fromCityAndState:@Princeton withState:@NJ];
Stop *stop1 = [stopBuilder1 getStop];
[stops addObject:stop1];
[RouteMgr addStops:CP_AFTER_FINAL_DESTINATION withStopList:stops];
[RouteMgr calculateRoute];

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs RouteMgr.AddStops() RouteMgr.RemoveAllStops() RouteMgr.GetStopList() RouteMgr.optimizeStops()


RouteMgr.optimizeStops()

Overview
Description Will attempt to optimize the current trip. This will always return false in a few cases

1. bKeepFinalDestination is false and number of stops is less than or equal to 2
2. bKeepFinalDestination is true and number of stops is less than or equal to 3.

Please note this is a basic optimization model, often referred to as Travelling Sales Person logic. It will use straight line distance only between the stops to calculate the optimal order. Max number of stops is 100.

The driver is not prompted to review or accept the new optimized order. The route will not take into account any time windows or wait time for the ETA.

Refer to OptimizationMgr for the advanced optimization options.

Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

boolean optimizeStops(Boolean)
+(bool) optimizeStops:(bool)

Parameters

bKeepFinalDestination; Keep optimization from changing the destination.

Return Value

True on success

Sample Code

// We'll assume that there were a few stops added to the route
// we will attempt to optimize them and keep the original destination
boolean routeOptimizationSuccessful = RouteMgr.optimizeStops(true);
if (routeOptimizationSuccessful) {
  System.out.println("Route optimization was successful");
  try {
    System.out.println("The new route is: " + RouteMgr.getStopList().toString());
  } catch (CopilotException | RouteException e) {
    e.printStackTrace();
  }
  } else {
    System.out.println("Route optimization failed, the route has not changed");
  }
NSLog([NSString stringWithFormat:@"Optimization was: %@", ([RouteMgr optimizeStops:false] == true) ? @"Successful" : @"Failed"]]);

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

RouteMgr.isCopilotReadyToAddStops() RouteMgr.AddStops() RouteMgr.RemoveAllStops() RouteMgr.GetStopList() RouteMgr.CalculateRoute()


DistanceUnit

Overview
Description Representation of a distance. This object is independent of units. Use the appropriate methods to set / get the desired value in the desired units.
Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Class
Package com.alk.cpik

Public Methods

Method Name Return Type
static fromInches(int inches) DistanceUnit
static fromFeet(int feet) DistanceUnit
static fromFeetAndInches(int feet, int inches) DistanceUnit
static fromCentimeters(int centimeters) DistanceUnit
static fromMeters(double meters) DistanceUnit
getInches() int
getCentimeters() int
getFeet() int
getMeters() double

Sample Code

// Create a new DistanceUnit representing 96 inches
DistanceUnit ninetySixInches = DistanceUnit.fromInches(96);
System.out.println(String.valueOf(ninetySixInches.getInches()) + " inches");

// Create a new DistanceUnit representing 53 feet
DistanceUnit fiftyThreeFeet = DistanceUnit.fromFeet(53);
System.out.println(String.valueOf(ninetySixInches.getInches()) + " inches");

// Create a new DistanceUnit representing 2.8 meters
DistanceUnit twoPointEightMeters = DistanceUnit.fromMeters(2.8);
System.out.println(String.valueOf(twoPointEightMeters.getCentimeters()) + " centimeters");

SpeedUnit

Overview
Description Representation of a speed. This object is independent of units. Use the appropriate methods to set / get the desired value in the desired units.
Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Class
Package com.alk.cpik

Public Methods

Method Name Return Type
fromMPH(int mph) SpeedUnit
fromKPH(int kph) SpeedUnit
getMPH() int
getKPH() int

Sample Code

// Create a new SpeedUnit representing 55 miles per hour
SpeedUnit fiftyFiveMPH = SpeedUnit.fromMPH(55);
System.out.println(String.valueOf(fiftyFiveMPH.getMPH()) + " mph");

// Create a new SpeedUnit representing 80 kilometers per hour
SpeedUnit eightyKPH = SpeedUnit.fromKPH(80);
System.out.println(String.valueOf(eightyKPH.getKPH()) + " kph");

WeightUnit

Overview
Description Representation of a weight. This object is independent of units. Use the appropriate methods to set / get the desired value in the desired units.
Supported Since Version 10.9
Platforms Supported Android, Linux. iOS
Type Class
Package com.alk.cpik

Public Methods

Method Name Return Type
fromPounds(int pounds) WeightUnit
fromUSTons(double tons) WeightUnit
fromKilograms(int kilograms) WeightUnit
fromMetricTonnes(double tonnes) WeightUnit
getPounds() int
getUSTons() double
getKilograms() int
getMetricTonnes() double

Sample Code

// Create a new WeightUnit representing 80,000 lbs
WeightUnit eightyThousandPounds = WeightUnit.fromPounds(80000);
System.out.println(String.valueOf(eightyThousandPounds.getPounds()) + " lbs");

// Create a new WeightUnit representing 36 metric tons
int kg = 36 * 1000;
WeightUnit thirtySixTons = WeightUnit.fromKilograms(kg);
System.out.println(String.valueOf(thirtySixTons.getKilograms()) + " kg");

RoadSpeedSet

Overview
Description Object representing a set of road speeds. This object contains a region and a vehicle type, as well as individual speeds for urban / rural roads of types interstate, divided highway, primary, secondary, local, ferry and ramp.
Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Class
Package com.alk.cpik.route

Public Methods

Method Name Return Type
getJurisdiction() String
setJurisdiction(String) void
getVehicleType() VehicleType
setVehicleType(VehicleType) void
getSpeed(RoadClass, RoadArea) SpeedUnit
setSpeed(RoadClass, RoadArea, SpeedUnit) void

Sample Code

// Create a road speed set with some custom speeds
SpeedUnit customSpeedA = SpeedUnit.fromMPH(60);
SpeedUnit customSpeedB = SpeedUnit.fromMPH(55);
SpeedUnit customSpeedC = SpeedUnit.fromMPH(30);
RoadSpeedSet rss = new RoadSpeedSet();
rss.setVehicleType(VehicleType.TRUCK_HEAVY_DUTY);
rss.setJurisdiction("New Jersey");
rss.setSpeed(RoadClass.INTERSTATE, RoadArea.RURAL, customSpeedA);
rss.setSpeed(RoadClass.INTERSTATE, RoadArea.URBAN, customSpeedB);
rss.setSpeed(RoadClass.SECONDARY, RoadArea.RURAL, customSpeedC);
RouteMgr.setUserRoadSpeeds(rss);

VehicleRoutingProfile

Overview
Description Class describing a vehicle routing profile in CoPilot. This class has no public constructors. The only way to pass a new routing profile into CoPilot is via the static createNewProfile(String profileName, VehicleType vehicleType) method.

CoPilot must be active before a routing profile can be passed. Once created, a profile’s vehicle type and name cannot be changed without deleting the profile and adding it again.

The only way to get a VehicleRoutingProfile object is by calling VehicleRoutingProfile.createNewProfile() with a name and a VehicleType. The object returned by this method call will be a new VehicleRoutingProfile object with the given name, and will have its fields pre-populated with the defaults for the given VehicleType for the currently installed region. Not all fields in the VehicleRoutingProfile object are valid for all vehicle types and/or all regions.

All ‘set’ methods return a VehicleProfileModificationResult. This result describes whether or not the set was successful. If not, it will return an error describing why the set was not successful.

All ‘get’ methods return the requested value if the field is valid for the vehicle type / region, or null if the field is not valid for the vehicle type / region.

Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Class
Package com.alk.cpik.route

Public Methods

Method Name Return Type Description          
createNewProfile(String, VehicleType) VehicleRoutingProfile Create a new VehicleRoutingProfile
getName() String Get the unique name of the VehicleRoutingProfile
getVehicleType() VehicleType Get the vehicle type of the VehicleRoutingProfile
getUserCreated() Boolean Get whether or not the profile is user created
getRoutingType() RoutingType Get the routing type to use for this profile
setRoutingType(RoutingType) VehicleProfileModificationResult Set the routing type to use for this profile
getDiscouragedFerries() Boolean Get whether or not the usage of ferries is discouraged
setDiscouragedFerries(boolean) VehicleProfileModificationResult Set whether or not the usage of ferries is discouraged
setSideOfStreetAdherence(StopSideAdherenceLevel sideOfStreetAdherence)
Available in CoPilot 10.14.0.325 and Higher
VehicleProfileModificationResult Sets the side of street adherence level in a vehicle routing profile.
getSideOfStreetAdherence()
Available in CoPilot 10.14.0.325 and Higher
StopSideAdherenceLevel Gets the side of street adherence level of a vehicle routing profile.
getTollRoadUsage() TollRoads Get whether or not the usage of toll roads is discouraged
setTollRoadUsage(TollRoads) VehicleProfileModificationResult Set whether or not the usage of toll roads is discouraged
setDisplayRoadRestrictionOnMap(DisplayTruckRestrictions)
Available in CoPilot 10.9.0.1180 and Higher
VehicleProfileModificationResult Set whether to display road restrictions on the CoPilot map.
getDisplayRoadRestrictionOnMap()
Available in CoPilot 10.9.0.1180 and Higher
DisplayTruckRestrictions Get whether road restrictions are displayed on the CoPilot map.
getInternationalBordersOpen() Boolean Get whether or not international borders are open. Set false to minimize the number of international border crossings. For example, if all your stops are in the “lower 48” United States, the resulting route will stay in the United States even though the most practical or shortest route would normally involve some Canadian mileage. The true option ignores international boundaries in generating the best route
setInternationalBordersOpen (boolean) VehicleProfileModificationResult Set whether or not international borders are open. Set false to minimize the number of international border crossings. For example, if all your stops are in the “lower 48” United States, the resulting route will stay in the United States even though the most practical or shortest route would normally involve some Canadian mileage. The true option ignores international boundaries in generating the best route
getPropaneRestricted() Boolean Get whether or not to avoid propane restricted roads.
setPropaneRestricted(boolean) VehicleProfileModificationResult Set whether or not to avoid propane restricted roads.
getFavorStateAndNationalNetwork() Boolean State + National Network routing favors the US Federally designated National Network (primary Interstates with reasonable entry/egress points up to 1 mile off the Interstate) and state-designated extensions to the National Network (additional highways and supporting roads any distance off the Interstate, as determined by individual states). This option also incorporates roads that permit 53’ trailers or twins
setFavorStateAndNationalNetwork(boolean) VehicleProfileModificationResult See above
get53FootRouting() Boolean
set53FootRouting(boolean) VehicleProfileModificationResult
getLondonCongestionZoneRoutingPreference() RestrictedZonePreference How to route with respect to the London Congestion Zone.
setLondonCongestionZoneRoutingPreference
(RestrictedZonePreference)
VehicleProfileModificationResult See above
getLondonLowEmissionZoneRoutingPreference() RestrictedZonePreference How to route with respect to the London Low Emission Zone.
setLondonLowEmissionZoneRoutingPreference
(RestrictedZonePreference)
VehicleProfileModificationResult See above
getUltraLowEmissionZoneRoutingPreference()
Available in CoPilot 10.14 and Higher
RestrictedZonePreference Gets how CoPilot will route with respect to the Ultra Low Emission Zone in London.
setUltraLowEmissionZoneRoutingPreference()
Available in CoPilot 10.14 and Higher
RestrictedZonePreference Sets how CoPilot will route with respect to the Ultra Low Emission Zone in London.
getEUTunnelCode() EUTunnelCode How to route with respect to European Tunnel Codes for hazardous materials.
setEUTunnelCode(EUTunnelCode) EUTunnelCode See above
getHazmatType() HazmatType How to route with respect to the transportation of hazardous materials. See below chart for specific NA information.
setHazmatType(HazmatType) VehicleProfileModificationResult
getElevationDiscouragedAbove() DistanceUnit Whether to discourage routing above a certain altitude
setElevationDiscouragedAbove(DistanceUnit) VehicleProfileModificationResult See above
getGovernorSpeedLimit() SpeedUnit Enables a maximum average road speed to use in route calculations. This speed overrides all other road speeds used in route calculations when they are higher than the governor setting
setGovernorSpeedLimit(SpeedUnit) VehicleProfileModificationResult See above
getVehicleDimensions() VehicleDimensions Dimensions of the vehicle
setVehicleDimensions(VehicleDimensions) List See above

Sample Code

// Create a vehicle profile with the defaults for heavy duty truck
try {
  VehicleRoutingProfile rpTruckDef = VehicleRoutingProfile.createNewProfile("HeavyDutyDefaults", VehicleType.TRUCK_HEAVY_DUTY);
  System.out.println("Heavy duty truck defaults: " + rpTruckDef.toString());
  RouteMgr.addVehicleRoutingProfile(rpTruckDef, true);
} catch (Exception profileException) { System.out.println(profileException.getMessage()); }

// Create a vehicle profile based on the defaults of medium duty truck
// Change the weight to 12,000 lbs.
try {
  VehicleRoutingProfile rpMedDuty12K = VehicleRoutingProfile.createNewProfile("MedDuty12K", VehicleType.TRUCK_MEDIUM_DUTY);
  VehicleDimensions dims = rpMedDuty12K.getVehicleDimensions();
  WeightUnit totalTruckWeight = WeightUnit.fromPounds(12000);
  dims.setTotalWeight(totalTruckWeight);
  rpMedDuty12K.setVehicleDimensions(dims);
  System.out.println("Medium duty with weight set to 12K lbs: " + rpMedDuty12K.toString());
  RouteMgr.addVehicleRoutingProfile(rpMedDuty12K, true);
} catch (Exception profileException) { System.out.println(profileException.getMessage()); }

// Create an auto profile based on the defaults for auto
// Set the profile to avoid toll roads
try {
  VehicleRoutingProfile autoAvoidTolls = VehicleRoutingProfile.createNewProfile("AutoAvoidTolls", VehicleType.AUTO);
  autoAvoidTolls.setTollRoadUsage(RouteEnums.TollRoads.ALWAYS_AVOID);
  System.out.println("Auto avoiding tolls: " + autoAvoidTolls.toString());
  RouteMgr.addVehicleRoutingProfile(autoAvoidTolls, true);
} catch (Exception profileException) { System.out.println(profileException.getMessage()); }

setSideOfStreetAdherence

Overview
Description This API allows you to modify the side of street adherence level in a Vehicle Routing Profile. Side of street adherence defines the extent to which CoPilot will try to route to the side of the street where a stop is located. This API works in conjunction with StopBuilder’s similarly named API call.

If a stop is sent in with a StopSideAdherenceLevel, that leg of the trip will operate with that StopSideAdherenceLevel. If the StopBuilder has NO StopSideAdherenceLevel defined, and the routing profile DOES have an adherence level defined via this API, CoPilot will operate with that level.

If both of those do not set an adherence level, you can use the user.cfg value "RoutingSideStreetMileCostX1000" as the default value for any profiles that do not have a value sent.

Supported Since Version 10.14.0.325
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik.route

Syntax

setSideOfStreetAdherence(StopSideAdherenceLevel sideOfStreetAdherence)

Parameters

sideOfStreetAdherence - StopSideAdherenceLevel

Return Value

VehicleProfileModificationResult

Sample Code

com.alk.cpik.route.VehicleRoutingProfile mSelectedVehicleRouteProf;
StopSideAdherenceLevel adherenceType =
       mSelectedVehicleRouteProf.getSideOfStreetAdherence();
if(adherenceType != null)
mSpinnerSideOfStreetAdherenceType.setSelection(adherenceType.ordinal());


position = mSpinnerSideOfStreetAdherenceType.getSelectedItemPosition();
            StopSideAdherenceLevel adherenceLevel = ALKEnum.toEnum(StopSideAdherenceLevel.class, position);
            modResult = mSelectedVehicleRouteProf.setSideOfStreetAdherence(adherenceLevel);
            rList.add("StopSideAdherenceLevel Result: " + modResult.toString() + "\n");

getSideOfStreetAdherence

Overview
Description This API allows you to get the side of street adherence level of a Vehicle Routing Profile. Side of street adherence defines the extent to which CoPilot will try to route to the side of the street where a stop is located.
Supported Since Version 10.14.0.325
Platforms Supported Android, Linux, iOS
Type Method
Package com.alk.cpik.route

Syntax

StopSideAdherenceLevel getSideOfStreetAdherence()

Parameters

None

Return Value

StopSideAdherenceLevel

Sample Code

com.alk.cpik.route.VehicleRoutingProfile mSelectedVehicleRouteProf;
StopSideAdherenceLevel adherenceType =
       mSelectedVehicleRouteProf.getSideOfStreetAdherence();
if(adherenceType != null)
mSpinnerSideOfStreetAdherenceType.setSelection(adherenceType.ordinal());


position = mSpinnerSideOfStreetAdherenceType.getSelectedItemPosition();
            StopSideAdherenceLevel adherenceLevel = ALKEnum.toEnum(StopSideAdherenceLevel.class, position);
            modResult = mSelectedVehicleRouteProf.setSideOfStreetAdherence(adherenceLevel);
            rList.add("StopSideAdherenceLevel Result: " + modResult.toString() + "\n");

RestrictedZonePreference

Overview
Description An enumerated value for how CoPilot should route with respect to a restricted zone.
Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Enum
Package com.alk.cpik.route

Values

Value Description
AVOID Completely avoid usage of any roads in the zone if none of the stops (or waypoints) are in the zone.
ALLOW Allow routing through the zone irrespective of the location of the stops.
WARN Allow routing into/from/through the zone with a warning if a route originates, goes into, or passes through the zone.

DisplayTruckRestrictions

Overview
Description An enumerated value for whether road restrictions should be displayed on the CoPilot map.
Supported Since Version 10.9.0.1180
Platforms Supported Android, Linux, iOS
Type Enum
Package com.alk.cpik.route

Values

Value Description
NEVER Never display truck restrictions.
ALWAYS Always display truck restrictions.
BASED_ON_PROFILE Display restrictions that apply to the current vehicle routing profile.

RouteEnums.VehicleType

Overview
Description A variety of vehicle types can be specified in RoutingProfile. The selected vehicle type can heavily influence route results and ETA values. This enum is use for representing the vehicle type for which the routing started.
Supported on Android Since Version 9.6.0.812
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.route
Value Description
AUTO Car/Auto
RV Recreational Vehicle, Caravan
MOTORCYCLE Motorbike, Motorcycle
BICYCLE Bicycle, Push bike
WALKING Walking mode
TRUCK_LIGHT_DUTY See description in the Feature Guide
TRUCK_MEDIUM_DUTY See description in the Feature Guide
TRUCK_HEAVY_DUTY See description in the Feature Guide
COMMERCIAL_PLATE
Deprecated in CoPilot 10.9
Vehicles with commercial plate, also known as light duty profiles
TRUCK
Deprecated in CoPilot 10.9
Truck vehicle type, heavy or medium duty
BUS Bus vehicle type
OTHER
Deprecated in CoPilot 10.9
Other vehicle that is not specified above
INVALID Invalid vehicle type

VehicleDimensions

Overview
Description Class representing the dimensions of a vehicle. These dimensions are set as part of a routing profile and are used in CoPilot for Truck routing profiles.
Supported Since Version 10.9
Platforms Supported Android, Linux, iOS
Type Class
Package com.alk.cpik.route

Public Methods

Method Name Return Type Description
getLength() DistanceUnit Get the length of the vehicle
setLength(DistanceUnit) void Set the length of the vehicle
getWidth() DistanceUnit Get the width of the vehicle
setWidth(DistanceUnit) void Set the width of the vehicle
getHeight() DistanceUnit Get the height of the vehicle
setHeight(DistanceUnit) void Set the height of the vehicle
getTotalWeight() WeightUnit Get the total weight of the vehicle
setTotalWeight(WeightUnit) void Set the total weight of the vehicle
getWeightPerAxle() WeightUnit Get the weight per axle of the vehicle
setWeightPerAxle(WeightUnit) void Set the weight per axle of the vehicle
// Create vehicle dimensions for a NA truck, 53' L x 102" W x 13'6" H x 80K lbs total x 34K lbs/axle
VehicleDimensions naTruck = new VehicleDimensions();
DistanceUnit length = DistanceUnit.fromInches(636);
DistanceUnit width = DistanceUnit.fromInches(102);
DistanceUnit height = DistanceUnit.fromInches(162);
WeightUnit totalWeight = WeightUnit.fromPounds(80000);
WeightUnit maxWeightPerAxle = WeightUnit.fromPounds(34000);
naTruck.setLength(length);
naTruck.setWidth(width);
naTruck.setHeight(height);
naTruck.setTotalWeight(totalWeight);
naTruck.setWeightPerAxle(maxWeightPerAxle);
System.out.println("NA truck dimensions: " + naTruck.toString());

// Create vehicle dimensions for an EU truck 12.5m L x 2.8m W x 4m H x 36t total x 7.5t lbs/axle
VehicleDimensions euTruck = new VehicleDimensions();
DistanceUnit length = DistanceUnit.fromCentimeters(1250);
DistanceUnit width = DistanceUnit.fromCentimeters(280);
DistanceUnit height = DistanceUnit.fromCentimeters(400);
WeightUnit totalWeight = WeightUnit.fromKilograms(36000);
WeightUnit maxWeightPerAxle = WeightUnit.fromKilograms(7500);
euTruck.setLength(length);
euTruck.setWidth(width);
euTruck.setHeight(height);
euTruck.setTotalWeight(totalWeight);
euTruck.setWeightPerAxle(maxWeightPerAxle);
System.out.println("EU truck dimensions: " + euTruck.toString());

TypeAheadGeocoder

Overview
Description The TypeAheadGeocoder is the object by which users can use CoPilot TypeAhead geocoding. There should only be one instance of the TypeAheadGeocoder at any given time. Typeahead style searching must first determine a city / zip code, then the street, then the address number. Not following the correct order may cause empty results to be returned during the process.
Supported on Android Since Version 9.6.0.1667
Supported on iOS Since Version 10.9
Type Object
Package com.alk.cpik

Methods

Method Name Return Type Description
cityOrZipSearch(String, String, int) List<Stop> Start a typeahead - style address search by passing in a city or zip code search string
clearSearch() Void Cancel a typeahead - style search
houseNumberSearch(String, int, int) List<Stop> Search for a house number in the typeahead - type search.
selectStop(int, AddStopPurpose, boolean) Void Select a stop returned from a call to houseNumberSearch.
streetSearch(String, int, int) List<Stop> Search for a street within the list of cities returned by cityOrZipSearch

Sample Code

// Perform type ahead geocoding
TypeAheadGeocoder myGeocoder = TypeAheadGeocoder.getInstance();
int numResults = 5;
String citySearchText = "Princeton";
String countryCode = "US";
List<Stop> cityResults = myGeocoder.cityOrZipSearch(citySearchText, countryCode, numResults);

String streetSearchText = "North Harrison";
int indexOfSelectedCity = 0;
// Parse the city results
List<Stop> streetResults = myGeocoder.streetSearch(streetSearchText, numResults, indexOfSelectedCity);

String houseNumberSearchText = "457";
int indexOfSelectedStreet = 0;
// Parse the street results
List<Stop> houseResults = myGeocoder.houseNumberSearch(houseNumberSearchText, numResults, indexOfSelectedStreet);

int index = 0;
RouteEnums.AddStopPurpose purpose = RouteEnums.AddStopPurpose.NEW_TRIP;
boolean preview = false;
// Parse the house results
myGeocoder.selectStop(index, purpose, preview);
TypeAheadGeocoder *geocoder = [TypeAheadGeocoder getInstance];
NSArray* arrayOfStops = [geocoder cityOrZipSearch:@Princeton withCountryCode:US withNumberResults:5];
NSArray* streetSearchResults = [geocoder streetSearch:@North Harrison withNumberResults:5 withIndexOfSelectedCity:0];
NSArray* houseNumberResults = [geocoder houseNumberSearch:@457 withNumberResults:5 withIndexOfSelectedStreet:0];

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


AlternateRouteInfo

Overview
Description An object which represents alternate route calculation information of trip. AlternateRouteInfo is being passed when route/alternate route calculation finished as well traffic information processed for route. AlternateRouteInfo contains route index, distance, major road on route, eta, traffic minutes etc.
Supported on Android Since Version 9.6.0.1716
Type Object
Package com.alk.cpik.route

Methods

Method Name Return Type Details
getTripID() int Trip ID. This is being use when selecting the route.
getMajorRoad() String Major road on the route
getDistance() double The distance of the trip. If the user.cfg setting [CPIK] "AlwaysReturnInMiles" is set to true, this will be the distance in miles. Otherwise, this will be the distance in either KM or Mi depending on whether or not CoPilot is set to use metric or standard measurements.
getETA() int Duration of the trip in minutes including traffic delay.
getTrafficDelay() int The traffic delay, in minutes, being added to the trip’s ETA.
getIsTrafficIncluded() boolean Is traffic is processed for this route and getTrafficDelay contain the traffic information.

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


Leg

Overview
Description An object which represents a "leg" of a trip. A "leg" is the route in between 2 points. This leg object contains the 2 points, and information about the leg such as the amount of time required to traverse the leg and the ETA for the destination. The origin stop of the first leg will “move” with each change in current position.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Object
Package com.alk.cpik.route

Methods

Method Name Return Type Details
getOrigin() Stop The origin stop on the leg.
getDestination() Stop The destination stop on the leg.
getDistance() double The distance remaining to traverse the leg. If the user.cfg setting [CPIK] "AlwaysReturnInMiles" is set to true, this will be the distance in miles. Otherwise, this will be the distance in either KM or Mi depending on whether or not CoPilot is set to use metric or standard measurements.
getTime() double The time remaining, in minutes, to traverse the leg.
getTrafficDelay() double The traffic delay, in minutes, being added to the leg’s remaining travel time.
getETA() Date The time at which the user will reach the destination stop of the leg. This time is represented in local time at the destination. The java Date.toString() method may give misleading results if used to print this value, as it will attempt to make time zone translations.
getCoordinates()
Available in CoPilot 10.19 and Higher
ArrayList Returns an ArrayList of Coordinate objects that represent the Leg. By default, the maximum number of Coordinate objects that can be returned is 500. This value can be changed with the following config value (in user.cfg or product.cfg):
[CPIK]
“LegMaxCoords”=500

Sample Code

// Get the first leg of the trip and get its information.
Leg firstLeg = RouteMgr.getRouteLegs(false).get(0);
Stop originStop = firstLeg.getOrigin();
Stop destinationStop = firstLeg.getDestination();
double distanceRemaining = firstLeg.getDistance();
double timeRemainingInMinutes = firstLeg.getTime();
double trafficDelayInMinutes = firstLeg.getTrafficDelay();
Date etaInDestinationLocalTime = firstLeg.getETA()

//To get leg coordinates
public void logCoordsOfRouteLegs()
{
    boolean bIgnoreWaypoints = false;
List<Leg> routeLegList = RouteMgr.getRouteLegs(ignoreWaypoints);
if(routeLegList.size() != 0)
{
for (Leg leg : routeLegList)
{
Log(leg.toString());
    ArrayList<Coordinate> legCoords = leg.getCoordinates();
for (Coordinate coord : legCoords)
    Log(coord.toString());
}
       }
}

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RouteMgr.getRouteLegs

Overview
Description Returns a list of each leg along the current route.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

java.util.List<Leg> getTripLegs(Boolean ignoreWaypoints)
+(NSArray*) getRouteLegs:(bool)

Parameters

ignoreWaypoints - If true, waypoints will not be included as endpoints of trip legs. Instead, adjacent legs containing waypoints will be combined.

Return Value

java.util.List<Leg>; A list of Leg objects

Sample Code

boolean ignoreWaypoints = false;
// Get and print the list of “legs” on the current route.
List<Leg> legList = RouteMgr.getRouteLegs(ignoreWaypoints);
for (int legPos = 0; legPos < legList.size(); legPos++)
  System.out.println("Trip leg" + String.valueOf(legPos) + " : " + legList.get(legPos).toString());
NSArray *legs = [RouteMgr getRouteLegs:false];
for(Leg *leg in legs)
{
  NSLog(Leg");
  NSLog(@"Origin Stop");
  NSLog([NSString stringWithFormat:@"Address: %@",
leg.originStop.address]);
  NSLog([NSString stringWithFormat:@"City: %@",
leg.originStop.city]);
}

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RouteMgr.hasDestination

Overview
Description The active trip is said to have a destination if there are at least 2 valid stops in the trip and there is a route calculated between them.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

boolean hasDestination()
+(bool) hasDestination

Return Value

boolean value whether or not CoPilot has a valid destination with a calculated route.

Sample Code

// Print whether or not CoPilot is navigating to a destination
boolean navigatingToDestination = RouteMgr.hasDestination();
if (navigatingToDestination)
  System.out.println("CoPilot has a destination");
else
  System.out.println("CoPilot does NOT have a destination");
NSLog([NSString stringWithFormat:@"Has Destination: %@", ([RouteMgr hasDestination] == true) ? @"True" : @"False"])

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RouteMgr.latLonAheadOnRoute

Overview
Description Returns a Coordinate object with the latitude and longitude of the position a variable number of minutes ahead on the current route.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

static Coordinate latLonAheadOnRoute(int)
+(Coordinate*) latLonAheadOnRoute:(int)

Parameters

int iMinutesAhead; The number of minutes ahead on the current route to look forward.

Return Value

Coordinate object -The latitude and longitude iMinutesAhead ahead on the route

Sample Code

// Print the coordinate that is 3 minutes ahead on the route
int minutesAhead = 3;
try {
  Coordinate coordThreeMinsAhead = RouteMgr.latLonAheadOnRoute(minutesAhead);
  System.out.println("Lat/lon " + coordThreeMinsAhead.toString() + " is three minutes ahead on the route");
} catch (CopilotException | RouteException e) {
  e.printStackTrace();
}
Coordinate *latlon = [RouteMgr latLonAheadOnRoute:1];
NSLog(@"Lat Lon ahead 1 Minute on Route");
NSLog([NSString stringWithFormat:@"Latitude: %f", latlon.latitude]);
NSLog([NSString stringWithFormat:@"Longitude: %f", latlon.longitude]);

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RouteMgr.adjustRoadPriority

Overview
Description Adjust the priority of the given roads
Note this API is now deprecated, to amend road speeds please see Routing Profile APIs.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

void adjustRoadPriority(AdjustRoadPriorityParams)
+(void) adjustRodPriority:(AdjustRoadPriorityParams*)

Parameters

params - The parameters to this method

Sample Code

try {
  AdjustRoadPriorityParams params = new AdjustRoadPriorityParams();
  params.setPriority(RoadPriority.HIGH_PRIORITY);
  RouteMgr.adjustRoadPriority(params);
} catch (CopilotException e) {
  e.printStackTrace();
}

RouteMgr.isReceivingGPSSignal

Overview
Description Returns whether CoPilot is actively receiving a GPS signal
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

boolean isReceivingGPSSignal()
+(bool) isReceivingGPSSignal

Return Value

Returns whether CoPilot is actively receiving a GPS signal

Sample Code

// Print whether or not CoPilot is receiving a GPS signal
boolean isReceivingGPS = RouteMgr.isReceivingGPSSignal();
if (isReceivingGPS)
  System.out.println("CoPilot is receiving a GPS signal");
else
  System.out.println("CoPilot is NOT receiving a GPS signal");

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RouteMgr.getSnappedPositionOfStop

Overview
Description Returns the snapped coordinates of the stop at the given index along the route. When stops are added, they are snapped to the nearest road but still contain the coordinates that were passed in. This API is used to get the coordinates that were snapped to the road.
Supported on Android Since Version 9.6.0.1320
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

getSnappedPositionOfStop(int idx)

Return Value

Coordinate- Returns the snapped coordinates of the stop at the given index along the route.

Sample Code

// Print the snapped coordinates of the first stop on the route
// This is where the green highlighted line begins
int stopIdx = 0;
Coordinate co = RouteMgr.getSnappedPositionOfStop(stopIdx);
System.out.println(co.toString());

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RouteMgr.selectAlternateRoute

Overview
Description This API passes selected route by using the Trip ID from CoPilot planning mode to CoPilot guidance mode. Once the user has passed the trip to CoPilot, CoPilot will send the route information by calling onRouteCalculation which will contain the route related information related to that Trip ID.

If the integrated application calls this API it will allow users to select an alternate the route without the CoPilot user interface.

Supported on Android Since Version 9.6.0.1716
Type Method
Package com.alk.cpik.route

Note

When the integrated application is adding the stop to CoPilot by calling RouteMgr.addStop it should pass bPreviewRoute as true to ensure user is taken to the navigation screen once this API is called.*

Syntax

AlternateRouteSelectionResult selectAlternateRoute(int tripID)

Return Value

AlternateRouteSelectionResult – A return code with details of the alternate route selection success, or if a failure, a cause for the failure.

Sample Code

// Select the route which having trip ID =1
AlternateRouteSelectionResult result = RouteMgr.selectAlternateRoute(1);

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RouteMgr.deleteRoutingProfile

Overview
Description This API allows users to remove and delete a routing profile from CoPilot’s list of saved routing profiles. The name of the profile should be provided to delete the profile. The exact name must be provided.

A Routing Profile should only be deleted if it is a custom profile. Default profiles should not be deleted by using this API.

Supported on Android Since Version 9.6.0.1552
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

RoutingProfileDeletionResult deleteRoutingProfile(String profileName)

Parameters

profileName – The exact String name of the profile to delete.

Return Value

RoutingProfileDeletionResult – A return code with details of the deletion success, or if a failure, a cause for the failure.

Sample Code

String profileName = "ProfileName B";
RouteEnums.RoutingProfileDeletionResult result = RouteMgr.deleteRoutingProfile(profileName);
System.out.println("Profile deletion result: " + result.toString());

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

RouteMgr.getActiveRoutingProfile() RouteMgr.addRoutingProfile() RouteMgr.getRoutingProfiles() RouteMgr.setActiveRoutingProfile() RouteMgr.getActiveProfileType() RouteMgr.selectActiveRoutingProfile()


AddStopPurpose

Overview
Description A value describing how to incorporate a stop into a trip.
Supported on Android Since Version 9.6.0.1716
Type Enum
Package com.alk.cpik.RouteEnums

Values

Value Description
NEW_TRIP Clears the current trip to add the stop(s).
NEW_CURRENT_DESTINATION Inserts the stop as the current destination.
AFTER_FINAL_DESTINATION Adds the stop to the end of the trip.

Examples

Current trip: > Y -> Z
stopList: A B

addStops(AddStopPurpose.NEW_TRIP, stopList)

Trip after API call: A -> B

addStops(AddStopPurpose.NEW_CURRENT_DESTINATION, stopList)

Trip after API call: A -> Y -> Z -> B

addStops(AddStopPurpose.AFTER_FINAL_DESTINATION, stopList)

Trip after API call: Y -> Z -> A -> B

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RoadPriority

Overview
Description A value describing the priority of a road
Supported on Android Since Version 9.6.0.821
Type Enum
Package com.alk.cpik.route

Values

Value Description
HIGH_PRIORITY This value represent the high priority of the road.
LOW_PRIORITY This value represent the low priority of the road.
VERY_LOW_PRIORITY This value represent the very low priority of the road.

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RoutingProfileDeletionResult

Overview
Description A return value specifying the result of an attempt to delete a routing profile.
Supported on Android Since Version 9.6.0.1552
Type Enum
Package com.alk.cpik.route

Values

Value Description
SUCCESS The profile was successfully deleted.
FAILED_NAME_EMPTY The deletion failed, because the name provided was empty.
FAILED_PROFILE_NOT_FOUND The deletion failed because a profile with the given name was not found.
FAILED_CANNOT_DELETE_DEFAULT The deletion failed because you cannot delete the default profile.
FAILED_DB_ERROR The deletion failed due to an internal database error.
FAILED_COPILOT_NOT_STARTED The deletion failed because CoPilot has not yet started.
FAILED_UNKNOWN The deletion failed due to an unknown error.

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RoutingProfileAdditionResult

Overview
Description A return value specifying the result of an attempt to add a routing profile.
Supported on Android Since Version 9.6.0.1552
Type Enum
Package com.alk.cpik.RouteEnums

Values

Value Description
SUCCESS The addition was successful.
FAILED_CANNOT_ADD_DEFAULT The addition failed, you cannot add a profile named “default”.
FAILED_PROFILE_EXISTS The addition failed, the profile name already exists, and the overwrite parameter was set to false.
FAILED_UNKNOWN_ERROR The addition failed, due to an unknown error.
FAILED_VEHICLE_TYPE_NOT_LICENSED The vehicle type of the added profile is not licensed.
FAILED_COPILOT_NOT_STARTED The addition failed because CoPilot has not yet started.
FAILED_UNKNOWN The addition failed, due to an unknown error.

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


AlternateRouteSelectionResult

Overview
Description A return value specifying the result of an attempt to select the alternate route.
Supported on Android Since Version 9.6.0.1716
Deprecated on Android in Version 10
Type Enum
Package com.alk.cpik.route

Note

This API is not supported in CoPilot V10.

Values

Value Description
SELECTION_SUCCESS Alternate route selected successfully.
SELECTION_FAILED_INVALID_TRIP_ID Passing Trip ID is not valid. No such route present.
SELECTION_FAILED_ROUTE_PREVIEW_SCREEN CoPilot is currently not in route preview mode or alternate route screen. Selecting alternate route API only works when CoPilot in route preview screen or alternate route dialog screen.
SELECTION_FAILED_COPILOT_NOT_STARTED Selection failed because CoPilot was not started.
SELECTION_FAILED_UNKNOWN Selection failed due to unknown issue.

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RouteSync

Overview
Description A class containing RouteSync calls.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Class
Package com.alk.cpik.route

Methods

Method Name Return Type Description
sendManagedRoute (List<​RouteSyncLocation>, ComplianceLevel, double ) int Sends a "managed" route into CoPilot described by a list of RouteSyncLocation objects. Notifications will be sent if the position leaves this route by dOutOfRouteDistanceAllowance according to the ComplianceLevel passed in.
sendManagedRoute (String, ComplianceLevel, double ) int This API is used to send the route sync message from a series of lat/long to CoPilot from client application.
sendManagedRouteJSON(String) int Sends a RouteSync Managed route to CoPilot using a JSON message.
sendManagedRoute ( byte[] ) int Sends a RouteSync Managed route to CoPilot by using a byteArray that is read from a RouteSync DAT file.
sendManagedRouteJSON(String json, List skipStopsList) int Sends a managed route into CoPilot using a JSON message with a list of stops that need to be skipped.

RouteSync.sendManagedRoute (List of Coordinates)

Overview
Description Send a managed route into CoPilot described by a list of RouteSyncLocation objects. The variable dOutOfRouteDistanceAllowance is in miles.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

int sendManagedRoute List<RouteSyncLocation> latLonList, ComplianceLevel compliance, double dOutOfRouteDistanceAllowance)
+(int) sendManagedRoute:(NSArray*) ManagedRouteComplianceLevel double

Parameters

latLonList-- a list of lat/long (please note Lat/Long value to multiplied by 1,000,000).

Compliance-- A ComplianceLevel value that indicates how strongly should CoPilot navigate to the original prescribed route.

outOfRouteDistanceAllowanceInfMiles-- out of route alert distance, in miles, that indicates how far can CoPilot

deviate from the original prescribed route before the OOR alert is issued. Default is 0.2 miles.

Return Value

Int value indicating success or failure in sending the event

Sample Code

// Create a new list of route sync locations
List<RouteSyncLocation> routeSyncLocationList = new
  ArrayList<RouteSyncLocation>();
double latitude = 40.367709;
double longitude = -74.655784;
routeSyncLocationList.add(new RouteSyncLocation(latitude, longitude,true));

latitude = 40.370121;
longitude = -74.658970;
routeSyncLocationList.add(new RouteSyncLocation(latitude, longitude));

latitude = 40.375556;
longitude = -74.663026;
routeSyncLocationList.add(new RouteSyncLocation(latitude, longitude,true));

double outOfRouteDistanceAllowedMiles = .05;
// Send a new route sync route with this list
RouteSync.sendManagedRoute(routeSyncLocationList, RouteEnums.ComplianceLevel.STRICT, outOfRouteDistanceAllowedMiles);
NSMutableArray *mutableArray = [[NSMutableArray alloc] init];
RouteSyncLocation* location = [[RouteSyncLocation alloc] init];
CLLocationCoordinate2D coordinate;

coordinate.latitude = 42.636605;
coordinate.longitude = -76.178562;
[location initWithLocation:coordinate];
location.bIsDestination = true;

[mutableArray addObject:location];

coordinate.latitude = 42.631765;
coordinate.longitude = -76.179130;
[location initWithLocation:coordinate];
location.bIsDestination = false;

[mutableArray addObject:location];

coordinate.latitude = 42.601277;
coordinate.longitude = -76.180520;
[location initWithLocation:coordinate];
location.bIsDestination = true;

[mutableArray addObject:location];

if([RouteSync sendManagedRouteByObjects:[mutableArray copy]
withComplianceLevel:STRICT withOutOfRouteAllowance:1] >= 0)
  NSLog(@"Successfully sent managed route");
else
  NSLog(@"Failed to send managed route");

RouteSync.sendManagedRoute (String of coordinates)

Overview
Description Sends a managed route into CoPilot described by a string in the format found in the example below. The variable dOutOfRouteDistanceAllowance is in miles.

Following the coordinate 1 should be added to define the start and end location as well as any additional stops.

Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Example String format:

42636605,76178562,1|42631765,-76179130|42629813,-76179562|42628445,-76180578|42626765,-76102354| 42621829,-76184082|42618605,-76183762|42608429,-76186134|42606325,-76180886|42601277,-76180520,1

Syntax

static int sendManagedRoute String latLonList, ComplianceLevel compliance, double dOutOfRouteDistanceAllowance)
+(int) sendManagedRoute:(NSString*) ManagedRouteComplianceLevel double

Parameters

latLonList- Series of lat/long (please note Lat/Long value to multiplied by 1,000,000).

Compliance- A ComplianceLevel value that indicates how strongly should CoPilot navigate to the original prescribed route.

outOfRouteDistanceAllowanceInfMiles- out of route alert distance, in miles, that indicates how far can CoPilot deviate from the original prescribed route before the OOR alert is issued. Default is 0.2 miles.

Return Value

Int value indicating success or failure in sending the event

Sample Code

// Create a string for input
String routeSyncString = "42636605,-76178562,1|42631765,- 76179130|42629813,-76179562|42628445,-76180578|42626765,- 76102354|42621829,-76184082|42618605,-76183762|42608429,- 76186134|42606325,-76180886|42601277,-76180520,1";
double outOfRouteDistanceAllowed = .05;

// Send a new route sync route with this list
RouteSync.sendManagedRoute(routeSyncString, RouteEnums.ComplianceLevel.STRICT, outOfRouteDistanceAllowed);
NSString *routeSyncString = @"42636605,-76178562,1|42631765,-76179130|42629813,-76179562|42628445,-76180578|42626765,-76102354|42621829,-76184082|42618605,-76183762|42608429,-76186134|42606325,-76180886|42601277,-76180520,1";
double outOfRouteDistanceAllowed = .05;

if([RouteSync sendManagedRoute:data withComplianceLevel:complianceLevel withOutOfRouteAllowance:outOfRouteAllowedDistance] >= 0)
  NSLog(Successfully sent managed route");
else
  NSLog @"Failed to send managed route");

RouteSync.sendManagedRouteJSON

Overview
Description Sends a managed route into CoPilot using a JSON message.
Supported on Android Since Version 9.6.0.1285
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

int sendManagedRouteJSON(String JSONString)

Return Value

Int – 0 success, negative valueerror

Parameters

JSONString - String containing JSON for integrating a routesync route

Sample Code

try {
  String rsFileString = new Scanner(new File("RouteSyncFile.json")).useDelimiter("\\Z").next();
  RouteSync.sendManagedRouteJSON(rsFileString);
} catch (FileNotFoundException e) {
  e.printStackTrace();
}

JSON Format

{
  "Compliance": 0,
  "OorDistance": 0.2,
  "Legs": [
    {
      "Coords": [
        -74730013, //Coords for roads you'd like the route to follow from Stop A -> Stop B
        40297252
      ]
    },
    {
      "Coords": [
        -74660179, //Coords for roads you'd like the route to follow from Stop B -> Stop C
        40348429,
        -74660635,
        40349433
      ]
    }
  ],
  "Trip": {
    "Name": "Test name",
    "Profile": {
      "name": "",
      "vehicleType": 4,
      "routingType": 3,
      "tollRoadType": 2,
      "maxHeight": 12900,
      "maxWidth": 9600,
      "totalLength": 48000,
      "totalWeight": 3300,
      "totalWeightPerAxle": 2300,
      "hazmatType": 0,
      "displayRestrictions": 2,
      "nationalNetwork": false,
      "fiftyThreeFootTrailer": false,
      "overrideRestrictions": true,
      "bordersOpen": true,
      "CongestionZonesOpen": 0,
      "LowEmissionZonesOpen": 0,
      "propane": false,
      "ferryClosed": false,
      "tollAvoid": false,
      "tollClosed": false,
      "truckDimensions": 0,
      "wrongSideofStreetCost": 1000,
      "autoSetStopDirection": 1
    },
    "Stops": [
      {
        "Location": {
          "Address": {
            "StreetAddress": "",
            "City": "Lawrence Township",
            "State": "NJ",
            "Zip": "08648",
            "County": "Mercer",
            "Country": ""
          },
          "Coords": {
            "Lat": "40.297263",
            "Lon": "-74.730034"
          }
        },
        "Waypoint": false,
        "Name": "Stop A"
      },
      {
        "Location": {
          "Coords": {
            "Lat": "40.348727",
            "Lon": "-74.659049"
          }
        },
        "Waypoint": false,
        "Name": "Stop B"
      },
      {
        "Location": {
          "Address": {
            "StreetAddress": "",
            "City": "New York",
            "State": "NY",
            "Zip": "10001",
            "County": "New York",
            "Country": ""
          }
        },
        "Waypoint": false,
        "Name": "Stop C"
      }
    ]
  }
}
JSON Parameter Description Required
Compliance This value will dictate how CoPilot will handle re-routing. That is, how strictly CoPilot should try to return to the original (sent) route in the event that the driver is out-of-route. There are three possible values: 0 – Strict Compliance; 1 – Moderate Compliance; 2 – Minimal Compliance. Yes
OorDistance This value will determine how far away from the planned route the CoPilot-equipped vehicle must be to generate an out-of-route (OOR) alert. The default value is 0.2 miles. Yes
Legs At least one leg is needed for each managed route. This should be passed as two sets of Coordinates. Yes
Coords At least 2 coords per leg are required. These are latitude and longitude points between stops on the trip that create the route you want the driver to follow. We recommend at least one latitude and longitude location for every road you want the route to follow, and an additional latitude and longitude on each side of every turning junction. These should be passed as long integers and encoded as millionths of a degree. Yes
Trip The trip details Yes
Profile This passes the Vehicle Routing Profile that is used for the managed route. Note: While optional, this parameter is highly recommended. Otherwise, CoPilot will use the current routing profile on the device to generate the route. No, but recommended
name Profile Name, this should be passed if the Profile group is included. No
vehicleType 0:Auto, 2:RV, 3:Truck, 6:Motorcycle, 7:Bicycle, 8:Walking. This should be passed if the Profile group is included. No
routingType 0:Quickest, 1:Shortest, 3:Fastest (Fastest requires a license for ActiveTraffic. Not recommended for truck profiles.) This should be passed if the Profile group is included. No
tollRoadType 0:Avoid, 1:Use If Necessary, 2:No Restriction. This should be passed if the Profile group is included. No
maxHeight Value sent in hundredths of inches. If sending in the routing profile and it is a truck vehicle type with a vehicle height you would like to specify, include this parameter. No
maxWidth Hundredths of inches. If sending in the routing profile and it is a truck vehicle type with a vehicle width you would like to specify, include this parameter. No
totalLength Hundredths of inches. If sending in the routing profile and it is a truck vehicle type with a vehicle length you would like to specify, include this parameter. No
totalWeight Pounds. If sending in the routing profile and it is a truck vehicle type with a vehicle weight you would like to specify, include this parameter. No
totalWeightPerAxle Pounds. If sending in the routing profile and it is a truck vehicle type with a vehicle weight per axle group you would like to specify, include this parameter. No
hazmatType 0:None, 1:General, 2:Explosive, 3:Inhalant, 4:Radioactive, 5:Caustic, 6:Flammable, 7:Harmful to water. If sending a Truck routing profile and you wish to specify any Hazmat category that may be applicable include this attribute No
displayRestrictions 0:Off, 1:On, 2:Based on profile. Within the truck routing profile that you are sending to CoPilot if you wish to include the setting to show restrictions on the map, include this parameter. No
nationalNetwork For North American customers, if sending a truck profile and you wish to apply the nationalNetwork routing profile setting this should be set with this parameter. No
fiftyThreeFootTrailer For North American customers sending a truck profile and wish to set the Fifty Three Foot Trailer setting within the routing profile, this parameter should be used. No
overrideRestrictions Set to true to to generate routes that waive truck restrictions pertaining to specific sizes and weights, but that continue to avoid truck-prohibited and truck discouraged roads. No
bordersOpen For North American customers if they wish to set the borders open parameter in the routing profile this should be set No
propane For North American customers who have a routing profile that needs to have the propane restriction set this parameter can be used No
ferryClosed To set the ferry routing attribute No
wrongSideofStreetCost
Available in CoPilot 10.14 and Higher
For School Bus profiles, set to 1000. This value favors approaching a stop on the same side of the road that you are driving on. It helps prevent a situation in which a student has to cross the road to get on the bus. No
autoSetStopDirection
Available in CoPilot 10.14 and Higher
For School Bus profiles, set to 1. This prevents a vehicle from making a U-turn at a stop. No
CongestionZonesOpen
Available in CoPilot 10.14 and Higher
Sets a routing preference for Congestion Zones 0: Avoid, 1: Allow, 2: Warn when driving No
LowEmissionZonesOpen
Available in CoPilot 10.14 and Higher
Sets a routing preference for Low Emission Zones. 0: Avoid, 1: Allow, 2: Warn when driving No
Stops Must always have one more stop than legs Yes
Location Details about the stop. Yes
Address The stop can be passed using the Address or the Coords. One of these options must be provided as part of the Stops Location section. Yes, if no Coords supplied
StreetAddress First line of the address of the Stop No
City City of the Stop No
State State of the stop No
Zip Zip or Postal Code for the stop No
County County of the stop No
Country Country code for the stop No
Coords The stop can be passed using the Coords or Address. If Address has not been provided this is mandatory. Yes, if no Address supplied
Lat Mandatory if using Coords for geocoding the stop Yes, if using Coords
Lon Mandatory if using Coords for geocoding the stop Yes, if using Coords
Waypoint Default is false. If you would like to set the stop as a Waypoint rather than a stop this should be set to True. No
Name Stop name – default is blank No

sendManagedRouteJSON(String json, List skipStopsList)

Overview
Description Sends a managed route into CoPilot using a JSON message and a list of stops that need to be skipped.
Supported on Android Since Version 10.14.2
Type Method
Package com.alk.cpik.route

Syntax

int sendManagedRouteJSON(String JSONString, List<String> skipStopList)

Return Value

Int – 0 success Negative value - error

Parameters

JSONString - String containing JSON for integrating a RouteSync route. skipStopList - List of stops by StopID to be deleted.

Sample Code

try {
List<String> skipStops = new ArrayList<int>();
skipStops.add(11);
skipStops.add(23);

  String rsFileString = new Scanner(new File("RouteSyncFile.json")).useDelimiter("\\Z").next();

  RouteSync.sendManagedRouteJSON(rsFileString, skipStops);
} catch (FileNotFoundException e) {
  e.printStackTrace();
}

See the JSON format above.


RouteSync.sendManagedRoute (DAT File)

Overview
Description Send a RouteSync Managed route to CoPilot by using a byteArray that is read from a RouteSync DAT file. These files are typically generated by other Trimble MAPS products.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

sendManagedRoute(byte[] latlongListData)
+(int) sendManagedRoute:(NSData*)

Parameters

latlongListData- Byte array containing the byte contents of a RouteSync DAT file.

Return Value

Int value indicating success or failure in sending the event

Sample Code

// Read in a byte array from a routesync dat file
String filePath = ("routeSync.dat");// routeSync
File file = new File(filePath);
int size = (int) file.length();
byte[] datFileData = new byte[size];
try {
  BufferedInputStream buf = new BufferedInputStream(new FileInputStream(file));
  buf.read(datFileData, 0, datFileData.length);
  buf.close();
} catch (FileNotFoundException e) {
  // TODO Auto-generated catch block
  e.printStackTrace();
} catch (IOException e) {
  e.printStackTrace();
}
// Send this byte array as a managed route
RouteSync.sendManagedRoute(datFileData);

RouteSyncError

Overview
Description A value providing details on why an error with RouteSync has occurred.
Supported on Android Since Version 9.6.0.1204
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.route

Values

Value Description
LICENSING_ERROR Indicates that there is insufficient licensing to use this feature.
ROUTING_ERROR Indicates that one or more legs of the RouteSync route could not be generated.
UNKNOWN_ERROR An unknown error has occurred.

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RouteMgr Deprecated APIs

The methods and objects below have been deprecated. See the RouteMgr overview at the top of this page for more information about the latest APIs.

RouteMgr.getActiveRoutingProfile

Overview
Description Returns the RoutingProfile currently being used for routing. Will return null if a truck routing profile is currently in use.
Supported on Android Since Version 9.6.0.821
Deprecated on Android Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

RoutingProfile getActiveRoutingProfile()

Return Value

RoutingProfile; Contains info about the current routing profile

Sample Code

// Get and print out the routing profile that is currently set in copilot
RoutingProfile currentProfile = RouteMgr.getActiveRoutingProfile();
System.out.println("Current routing profile Name: " + currentProfile.getName());
System.out.println("Current routing profile VehicleType: " + currentProfile.getVehicleType());
System.out.println("Current routing profile RoutingType: " + currentProfile.getRoutingType());
System.out.println("Current routing profile UsePropaneRestrictions: " + currentProfile.getUsePropaneRestrictions());
System.out.println("Current routing profile DividedHighwayAvoidPreference: " + currentProfile.getDividedHighwayAvoidPreference());
System.out.println("Current routing profile FreewayAvoidPreference: " + currentProfile.getFreewayAvoidPreference());

// for all property print at the same time
System.out.println("Current routing profile: " + currentProfile.toString());

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

RouteMgr.addRoutingProfile() RouteMgr.getRoutingProfiles() RouteMgr.setActiveRoutingProfile() RouteMgr.getActiveProfileType() RouteMgr.selectActiveRoutingProfile() RouteMgr.deleteRoutingProfile()


RouteMgr.setActiveRoutingProfile

Overview
Description Sets the active RoutingProfile to be used in routing.
Supported on Android Since Version 9.6.0.821
Deprecated on Android Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

void setActiveRoutingProfile(RoutingProfile routingProfile);

Parameters

RoutingProfile routingProfile- An object containing routing information

Sample Code

// Get the current routing profile as a base
RoutingProfile rpToSet = RouteMgr.getActiveRoutingProfile();

// Make the desired changes. In this example, we'll change the vehicle type to RV
rpToSet.setVehicleType(RouteEnums.VehicleType.RV);

// Set the newly created profile
RouteMgr.setActiveRoutingProfile(rpToSet);

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

RouteMgr.getActiveRoutingProfile() RouteMgr.addRoutingProfile() RouteMgr.getRoutingProfiles() RouteMgr.setActiveRoutingProfile() RouteMgr.getActiveProfileType() RouteMgr.selectActiveRoutingProfile() RouteMgr.deleteRoutingProfile()


RouteMgr.getActiveTruckRoutingProfile

Overview
Description Returns the TruckRoutingProfile currently being used for routing. Will return null if any profile other than a heavy duty truck profile is in use or if CoPilot is not licensed for truck.
Supported on Android Since Version 9.6.0.821
Deprecated on Android Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

TruckRoutingProfile getActiveTruckRoutingProfile()

Return Value

TruckRoutingProfile; Contains info about the current truck routing profile

Sample Code

// Get and print out the truck routing profile that is currently set in copilot
TruckRoutingProfile currentProfile = RouteMgr.getActiveTruckRoutingProfile();
System.out.println("Current truck routing profile Name: " + currentProfile.getName());
System.out.println("Current truck routing profile HazmatType: " + currentProfile.getHazmatType());
System.out.println("Current truck routing profile RoutingType: " + currentProfile.getRoutingType());
System.out.println("Current truck routing profile UseNationalNetwork: " + currentProfile.getUseNationalNetwork());
System.out.println("Current truck routing profile DividedHighwayAvoidPreference:" + currentProfile.getDividedHighwayAvoidPreference());
System.out.println("Current truck routing profile FreewayAvoidPreference: " + currentProfile.getFreewayAvoidPreference());

// for all property print at the same time
System.out.println("Current truck routing profile is: " + currentProfile.toString());

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs RouteMgr.addTruckRoutingProfile() RouteMgr.getTruckRoutingProfiles() RouteMgr.setActiveRoutingProfile() RouteMgr.getActiveProfileType() RouteMgr.selectActiveRoutingProfile() RouteMgr.deleteRoutingProfile()


RouteMgr.setActiveRoutingProfile

Overview
Description Sets the active TruckRoutingProfile to be used in routing. This method will only work if CoPilot is licensed for truck.
Supported on Android Since Version 9.6.0.821
Deprecated on Android Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

static void setActiveRoutingProfile(TruckRoutingProfile)

Parameters

TruckRoutingProfile routingProfile; An object containing routing information

Sample Code

// Get the current routing profile as a base
TruckRoutingProfile rpToSet = RouteMgr.getActiveTruckRoutingProfile();

// Make the desired changes.
rpToSet.setUseTruckRestrictions(true);

// Set the newly created profile
RouteMgr.setActiveRoutingProfile(rpToSet);

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

RouteMgr.getActiveTruckRoutingProfile() RouteMgr.addTruckRoutingProfile() RouteMgr.getTruckRoutingProfiles() RouteMgr.selectActiveRoutingProfile() RouteMgr.deleteRoutingProfile()


RouteMgr.getActiveProfileType

Overview
Description Returns the VehicleType of the currently active routing profile.
Supported on Android Since Version 9.6.0.821
Deprecated on Android Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

static VehicleType getActiveProfileType()

Return Value

VehicleType object, The type of vehicle being represented by the current routing profile.

Sample Code

// Get and print the current profile type
RouteEnums.VehicleType currVehType = RouteMgr.getActiveProfileType();
System.out.println("Current vehicle type is: " +  currVehType.toString());

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

RouteMgr.getActiveRoutingProfile() RouteMgr.addRoutingProfile() RouteMgr.getRoutingProfiles() RouteMgr.setActiveRoutingProfile() RouteMgr.selectActiveRoutingProfile() RouteMgr.deleteRoutingProfile()


RouteMgr.getRoutingProfiles

Overview
Description Returns a list of all non-truck routing profiles saved in CoPilot.
Supported on Android Since Version 9.6.0.1552
Deprecated on Android Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

List<​RoutingProfile> getRoutingProfiles()

Return Value

List<​RoutingProfile> - All non-truck routing profiles currently saved in CoPilot.

Sample Code

List<RoutingProfile> rpList = RouteMgr.getRoutingProfiles();

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

RouteMgr.getActiveRoutingProfile() RouteMgr.addRoutingProfile() RouteMgr.setActiveRoutingProfile() RouteMgr.getActiveProfileType() RouteMgr.selectActiveRoutingProfile() RouteMgr.deleteRoutingProfile()


RouteMgr.getTruckRoutingProfiles

Overview
Description Returns a list of all heavy duty truck routing profiles saved in CoPilot. Will return an empty list if CoPilot is not licensed for truck.
Supported on Android Since Version 9.6.0.1552
Deprecated on Android Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

List getTruckRoutingProfiles()

Return Value

List - All truck routing profiles currently saved in CoPilot.

Sample Code

List<TruckRoutingProfile> trpList = RouteMgr.getTruckRoutingProfiles();

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

RouteMgr.getActiveTruckRoutingProfile() RouteMgr.addTruckRoutingProfile() RouteMgr.setActiveRoutingProfile() RouteMgr.getActiveProfileType() RouteMgr.selectActiveRoutingProfile() RouteMgr.deleteRoutingProfile()


RouteMgr.addRoutingProfile

Overview
Description Add a routing profile to CoPilot’s list of saved routing profiles
Supported on Android Since Version 9.6.0.1552
Deprecated on Android Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

RoutingProfileAdditionResult addRoutingProfile(RoutingProfile routingProfile, Boolean overwriteIfNameExists)

Parameters

RoutingProfile routingProfile – The routing profile to add to CoPilot

Boolean overwriteIfNameExists – Whether or not to overwrite the existing profile in CoPilot if a profile exists with the same name

Return Value

RoutingProfileAdditionResult – Result describing the success / failure of adding the routing profile.

Sample Code

RoutingProfile rp = new RoutingProfile();
//set the required property. You can set which property you want to add
rp.setVehicleType(RouteEnums.VehicleType.AUTO);
boolean usePropaneRestrictions = true;
rp.setUsePropaneRestrictions(usePropaneRestrictions);
boolean overwriteIfNameExists = true;
RouteMgr.addRoutingProfile(rp, overwriteIfNameExists);

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

RouteMgr.getActiveRoutingProfile() RouRouteMgr.getRoutingProfiles() RouteMgr.setActiveRoutingProfile() RouteMgr.getActiveProfileType() RouteMgr.selectActiveRoutingProfile() RouteMgr.deleteRoutingProfile()


RouteMgr.addTruckRoutingProfile

Overview
Description Add a truck routing profile to CoPilot’s list of saved truck routing profiles.
Supported on Android Since Version 9.6.0.1552
Deprecated on Android Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

RoutingProfileAdditionResult addTruckRoutingProfile(TruckRoutingProfile truckRoutingProfile, boolean overwriteIfNameExists)

Parameters

TruckRoutingProfile truckRoutingProfile – The truck routing profile to add to CoPilot

Boolean overwriteIfNameExists – Whether or not to overwrite the existing profile in CoPilot if a profile exists with the same name

Return Value

RoutingProfileAdditionResult – Result describing the success / failure of adding the routing profile.

Sample Code

TruckRoutingProfile trp = new TruckRoutingProfile();
//setting required property. You can set which property you want to add
trp.setHazmatType(RouteEnums.HazmatType.NONE);

boolean overwriteIfNameExists = false;
RouteMgr.addTruckRoutingProfile(trp, overwriteIfNameExists);

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

RouteMgr.getActiveTruckRoutingProfile() RouteMgr.getTruckRoutingProfiles() RouteMgr.setActiveRoutingProfile() RouteMgr.getActiveProfileType() RouteMgr.selectActiveRoutingProfile() RouteMgr.deleteRoutingProfile()


RouteMgr.selectActiveRoutingProfile

Overview
Description Select the current routing profile, based on profile name.
Supported on Android Since Version 9.6.0.1552
Deprecated on Android Since Version 10.9
Type Method
Package com.alk.cpik.route

Syntax

Boolean selectActiveRoutingProfile(String profileName)

Parameters

profileName – The exact name of the routing profile to select

Return Value

Boolean value true if the profile was found and selected, false if the given profile name was not found.

Sample Code

RouteMgr.selectActiveRoutingProfile("RoutingProfile A");

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

RouteMgr.getActiveRoutingProfile() RouteMgr.addRoutingProfile() RouteMgr.getRoutingProfiles() RouteMgr.setActiveRoutingProfile() RouteMgr.getActiveProfileType() RouteMgr.deleteRoutingProfile()


RoutingProfile

Overview
Description A Routing Profile specifically for non-truck vehicles. RoutingProfile objects have many optional parameters and inherit from RoutingProfileBase.
Supported on Android Since Version 9.6.0.821
Deprecated on Android in Version 10.9
Type Object
Package com.alk.cpik.route

Methods

Method Name Return Type Description
getVehicleType () VehicleType Different vehicle types will have different default road speeds associated with them so changing the vehicle type without manually overriding the road speeds for different road classes will result in different ETAs and, quite often, different routes
setVehicleType (VehicleType) void Set the VehicleType to use for the route
getUsePropaneRestrictions () boolean Get whether or not propane restricted roads should be allowed for the route.
setUsePropaneRestrictions (boolean) void Set whether or not propane restricted roads should be allowed for the route

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


TruckRoutingProfile

Overview
Description A Routing Profile specifically for trucks. TruckRoutingProfile objects have many optional parameters and inherit from RoutingProfileBase.
Supported on Android Since Version 9.6.0.821
Deprecated on Android in Version 10.9
Type Object
Package com.alk.cpik.route

Methods

Method Name Return Type Description
getEUTunnelCode () EUTunnelCode Get the current EUTunnelCode for routes going through the EuroTunnel
setEUTunnelCode (EUTunnelCode) void Set the current EUTunnelCode for routes going through the EuroTunnel
getLowEmissionZonePref () RestrictedZonePreference Get the current RestrictedZonePreference for routes with Low Emission Zones
setLowEmissionZonePref (RestrictedZonePreference) Void Set the current RestrictedZonePreference for routes with Low Emission Zones
getTruckDimensions () TruckDimensions Get the maximum allowed truck dimensions. CoPilot will only return routes that accommodate this vehicle's size
setTruckDimensions (TruckDimensions) Void Set the maximum allowed truck dimensions. CoPilot will only return routes that accommodate this vehicle's size
getHazmatType () HazmatType Get an EnumSet of the hazardous materials carried in the truck.
setHazmatType (HazmatType) void Specify which hazardous material will be carried in the truck
getUseNationalNetwork () boolean Get whether CoPilot's routes will favor roads classified as belonging to the national Network
setUseNationalNetwork (boolean) void Set whether CoPilot's routes will favor roads classified as belonging to the national Network
getUse53FootTrailerRouting () boolean Get whether CoPilot's routes will favor roads that are classified as providing oversized vehicle access
setUse53FootTrailerRouting (boolean) void Set whether CoPilot's routes will favor roads that are classified as providing oversized vehicle access

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.


RoutingProfileBase

Overview
Description Base class for Routing Profiles. This includes the core elements of a routing profile and each of the methods can be used to create a specific routing profile within CoPilot.

The routing profile will determine the route calculated by CoPilot and it is recommended that only necessary attributes are updated from the default.

Supported on Android Since Version 9.6.0.821
Deprecated on Android in Version 10.9
Type Object
Package com.alk.cpik.route

Methods

Method Name Return Type Description
getLondonCongestionZonePref() RestrictedZonePreference How CoPilot is routing with respect to the London Congestion Zone.
setLondonCongestionZonePref (RestrictedZonePreference) void Set how CoPilot should route with respect to the London Congestion Zone.
getTollRoadUsage () TollRoads How CoPilot is routing with respect to tolls.
setTollRoadUsage (TollRoads) void Set how CoPilot should route with respect to toll roads.
getFreewayAvoidPreference () AvoidRouting The avoidance preference of CoPilot for freeways.
setFreewayAvoidPreference (AvoidRouting) void Set the avoidance preference of CoPilot for freeways.
getDividedHighwayAvoidPreference () AvoidRouting The avoidance preference of CoPilot for divided highways.
setDividedHighwayAvoidPreference (AvoidRouting) void Set the avoidance preference of CoPilot for divided highways.
getPrimaryRoadAvoidPreference () AvoidRouting The avoidance preference of CoPilot for primary roads.
setPrimaryRoadAvoidPreference (AvoidRouting) void Set the avoidance preference of CoPilot for divided highways.
getSecondaryRoadAvoidPreference () AvoidRouting The avoidance preference of CoPilot for secondary roads.
setSecondaryRoadAvoidPreference (AvoidRouting) void Set the avoidance preference of CoPilot for secondary roads
getLocalRoadAvoidPreference () AvoidRouting The avoidance preference of CoPilot for local roads.
setLocalRoadAvoidPreference (AvoidRouting) void Set the avoidance preference of CoPilot for local roads.
getRoutingType () RoutingType Get the current type of route CoPilot generates for the user.
setRoutingType (RoutingType) void Set the current type of route CoPilot generates for the user.
getBreakMinutes () int Get the interval in minutes that CoPilot will use to plan breaks for the user during the trip.
setBreakMinutes (int) void Set the interval in minutes that CoPilot will use to plan breaks for the user during the trip.
getBreakWaitMinutes () int Get the length in minutes of the breaks that CoPilot may apply to the trip.
setBreakWaitMinutes () void Set the length in minutes of the breaks that CoPilot may apply to the trip.
getFreewaySpeed () int Get the speed (in miles per hour) at which a user will travel on freeways.
setFreewaySpeed (int) void Set the speed (in miles per hour) at which a user will travel on freeways.
getDividedHighwaySpeed () int Get the speed (in miles per hour) at which a user will travel on divided highways.
setDividedHighwaySpeed (int) void Set the speed (in miles per hour) at which a user will travel on divided highways.
getPrimaryRoadSpeed () int Get the speed (in miles per hour) at which a user will travel on primary roads.
setPrimaryRoadSpeed (int) void Set the speed (in miles per hour) at which a user will travel on primary roads.
getSecondaryRoadSpeed () int Get the speed (in miles per hour) at which a user will travel on secondary roads.
setSecondaryRoadSpeed (int) void Set the speed (in miles per hour) at which a user will travel on secondary roads.
getLocalRoadSpeed() int Get the speed (in miles per hour) at which a user will travel on local roads.
setLocalRoadSpeed(int) void Set the speed (in miles per hour) at which a user will travel on local roads.
getInternationalBordersOpen() boolean Get whether the route may cross into another country than that in which the route originates.
setInternationalBordersOpen(boolean) void Set whether the route may cross into another country than that in which the route originates.
getAvoidFerries() Boolean Get whether the route should avoid ferries.
setAvoidFerries(boolean) void Set whether the route should avoid ferries.

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

RouteMgr.addStop

Overview
Description Geocodes and inserts a single stop into CoPilot's active route.

When passing in a stop and you wish to receive alternate route data via RouteListener callbacks bPreviewRoute should be set as true. RouteMgr.selectAlternateRoute can then be used to select the route to navigate.

Supported on Android Since Version 9.6.0.821
Deprecated on Android in Version 10.9
Type Method
Package com.alk.cpik.route

Note

Please use updated API included above

Syntax

void addStop(AddStopPurpose purpose, Stop cpStop, boolean bPreviewRoute) throws RouteException, CopilotException

Parameters

purpose--Helps CoPilot understand how to incorporate the new stop into the user's trip

stop --The best known information for the stop to be added

bPreviewRoute--Whether or not to show the route preview screen on CoPilot after the stops are added. This will automatically trigger a route calculation for the stop that has been added.

Sample Code

double latitude = 40.368420;
double longitude = -74.655036;
// Make a new stop to add
StopBuilder sb = StopBuilder.fromLatLon(new Coordinate(latitude, longitude));
try {
  Stop newStopToAdd = sb.geocode(GeocodeSearchType.BEST_MATCH).get(0);
  boolean bPreviewRoute = true; // Set true if you want see a preview of route
  // Clear the current route and add the new stop
  RouteMgr.addStop(RouteEnums.AddStopPurpose.NEW_TRIP, newStopToAdd, bPreviewRoute);
  // Insert the new stop as the current destination
  RouteMgr.addStop(RouteEnums.AddStopPurpose.NEW_CURRENT_DESTINATION, newStopToAdd, bPreviewRoute);
  // Add the stop after the final destination
  RouteMgr.addStop(RouteEnums.AddStopPurpose.AFTER_FINAL_DESTINATION, newStopToAdd, bPreviewRoute);
} catch (CopilotException | GeocodingException | RouteException e) {
  e.printStackTrace();
}

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

  • RouteMgr.AddStops
  • RouteMgr.RemoveAllStops
  • RouteMgr.GetStopList
  • RouteMgr.CalculateRoute
  • RouteMgr.OptimizeStops

RouteMgr.addStops

Overview
Description Geocodes and inserts a list of stops into CoPilot's active route.

When passing in a stop and you wish to receive alternate route data via RouteListener callbacks bPreviewRoute should be set as true. RouteMgr.selectAlternateRoute can then be used to select the route to navigate.

Supported on Android Since Version 9.6.0.821
Deprecated on Android in Version 10.9
Type Method
Package com.alk.cpik.route

Note

Please note this API has been deprecated in v10.9. Details of the new addStops API is included above.

Syntax

void addStops(AddStopPurpose purpose, StopList stopList, boolean bPreviewRoute) throws RouteException, CopilotException

Parameters

purpose--helps CoPilot understand how to incorporate the new stop into the user's trip

stops--The best known information for the stops to be added

bPreviewRoute--whether or not to show the route preview screen on CoPilot after the stops are added. This will automatically trigger a route calculation when passed.

Sample Code

// Make new stops to add
try {
  double latitudeA = 40.368420;
  double longitudeA = -74.655036;
  StopBuilder sbA = StopBuilder.fromLatLon(new Coordinate(latitudeA, longitudeA));
  Stop newStopToAddA = sbA.geocode(GeocodeSearchType.BEST_MATCH).get(0);

  double latitudeB = 40.368530;
  double longitudeB = -74.6552036;
  StopBuilder sbB = StopBuilder.fromLatLon(new Coordinate(latitudeB, longitudeB));
  Stop newStopToAddB = sbB.geocode(GeocodeSearchType.BEST_MATCH).get(0);

  StopList stopList = new StopList();
  stopList.add(newStopToAddA);
  stopList.add(newStopToAddB);

  boolean bPreviewRoute = false; // Set true if you want see a preview of route
  // Add these new stops to the trip, after the final destination
  RouteMgr.addStops(RouteEnums.AddStopPurpose.AFTER_FINAL_DESTINATION, stopList, bPreviewRoute);
}catch(CopilotException | GeocodingException | RouteException e){
  e.printStackTrace();
}

Hooks and Callbacks

Hooks and Callbacks related to routing can be found here.

Related APIs

  • RouteMgr.GetStopList
  • RouteMgr.CalculateRoute
  • RouteMgr.optimizeStops

Last update: September 15, 2020