Skip to main content

RouteMgr (CPIK Libraries)

Contents

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 Later
void Sets the active VehicleRoutingProfile to be used in routing.
getActiveVehicleRoutingProfile()
Available in CoPilot 10.9 and Later
VehicleRoutingProfile Gets the active VehicleRoutingProfile being used in routing.
getVehicleRoutingProfiles()
Available in CoPilot 10.9 and Later
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 Later
VehicleRoutingProfile Searches CoPilot for a VehicleRoutingProfile with the given name.
resetVehicleRoutingProfileToDefault(String profileName)
Available in CoPilot 10.9 and Later
boolean Resets the specified VehicleRoutingProfile to the default for that vehicle type.
addVehicleRoutingProfile(VehicleRoutingProfile routingProfile, boolean overwriteIfNameExists)
Available in CoPilot 10.9 and Later
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


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


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 of VehicleRoutingProfile - A list of all routing profiles in CoPilot

Sample Code


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 region of the world.

Return Values

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

Sample Code


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


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


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


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


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 of RoadSpeedSet - A list of RoadSpeedSet objects representing the user road speeds that are set in CoPilot.

Sample Code


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 of RoadSpeedSet - A list of RoadSpeedSet objects representing the default road speeds that are set in CoPilot.

Sample Code


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


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 1 mile 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 1 mile 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


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

Added stops and current location

If you send more than one stop to CoPilot, the device’s Current (GPS) Location will replace the first stop in your list of stops once the driver taps the navigation button to begin the trip. If you do not want the current location to replace your first stop, you can either:

  1. Send a duplicate of the first stop. CoPilot will replace the first of those stops with the current GPS position and set the second as the first stop in the trip.
  2. Send as your first stop the location where you expect the driver to begin their trip. (A depot, for example.)

Notes on entering locations

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 1 mile 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 1 mile 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

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

stoplist - A list of stop objects.

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

Sample Code


RoutePreviewMode

Overview
Description An enumerated value which will be used by RouteMgr.addStop and RouteMgr.addStops to tell CoPilot which 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 https://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


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 values: 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


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


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


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


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


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


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

Hooks and Callbacks


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


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 boolean whether CoPilot is actively receiving a GPS signal.

Sample Code


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


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 the 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


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());

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


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


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


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


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
Type Class
Package com.alk.cpik.route

Public Methods

Method Name Return Type Description          
createNewProfile(String, VehicleType) VehicleRoutingProfile Create a new VehicleRoutingProfile
getVehicleRoutingProfileSource()
Available in CoPilot 10.26.1.300 and Later
VehicleRoutingProfileSource Gets the source of the VehicleRoutingProfile. This method can return Default, Manual, API, or FleetPortal. Note: Any profiles added in older versions of CoPilot will continue to be shown in CoPilot under “My Profiles” instead of “Company Profiles” and will be considered as profiles created by the user (Manual). In order to display them under “Company Profiles,” and have them correctly identified as profiles created via API, you must override the existing profile via API using the same name.
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 Later
VehicleProfileModificationResult Sets the side of street adherence level in a vehicle routing profile.
getSideOfStreetAdherence()
Available in CoPilot 10.14.0.325 and Later
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 Later
VehicleProfileModificationResult Set whether to display road restrictions on the CoPilot map.
getDisplayRoadRestrictionOnMap()
Available in CoPilot 10.9.0.1180 and Later
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()
Deprecated in CoPilot 10.19.3.48. Use State + National Network routing.
Boolean
set53FootRouting(boolean)
Deprecated in CoPilot 10.19.3.48. Use State + National Network routing.
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
getLondonUltraLowEmissionZoneRoutingPreference()
Available in CoPilot 10.14 and Later
RestrictedZonePreference Gets how CoPilot will route with respect to the Ultra Low Emission Zone in London.
setLondonUltraLowEmissionZoneRoutingPreference()
Available in CoPilot 10.14 and Later
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. (North America Only)
setElevationDiscouragedAbove(DistanceUnit) VehicleProfileModificationResult See above. (North America Only)
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


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


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


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

Sample Code


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


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.

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 Later
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


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


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.

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.

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.

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, 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


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


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

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 Later
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 Later
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 Later
Sets a routing preference for Congestion Zones 0: Avoid, 1: Allow, 2: Warn when driving No
LowEmissionZonesOpen
Available in CoPilot 10.14 and Later
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

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


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
FILE_NOT_FOUND The RouteSync JSON file was not found/accessible.
EMPTY_FILE_ERROR The RouteSync JSON file is empty
JSON_PARSING_ERROR Invalid RouteSync JSON file
NUM_LEGS_STOPS_ERROR The number of trip legs is greater than or equal to number of trip stops
OOR_DISTANCE_NOT_FOUND The OOR distance value was not found in the JSON
COMPLIANCE_NOT_FOUND The compliance value was not found in the JSON
GEOCODING_ERROR Error geocoding one or more stops
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.
Last updated July 2, 2024.
Contents