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:
- 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.
- 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 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) | ListSee 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 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
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_PLATEDeprecated in CoPilot 10.9
| Vehicles with commercial plate, also known as light duty profiles |
TRUCKDeprecated in CoPilot 10.9
| Truck vehicle type, heavy or medium duty |
BUS | Bus vehicle type |
OTHERDeprecated 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
| ArrayListReturns 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 (Listint
| 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 | 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 |
wrongSideofStreetCostAvailable 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 |
autoSetStopDirectionAvailable 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 |
CongestionZonesOpenAvailable in CoPilot 10.14 and Later
| Sets a routing preference for Congestion Zones 0: Avoid, 1: Allow, 2: Warn when driving | No |
LowEmissionZonesOpenAvailable 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. |