CoPilotMgr (SDK Libraries)

Contents

CopilotVersion #

Overview
Description A class containing information about the version of CoPilot and map data that is currently loaded on a device. This includes software version, map data version, year and quarter.
Supported on Android Since Version 9.6.0.821
Type Class
Package com.alk.cpik

Methods

Method Name Return Type Description
getAppVersion()
string
Returns the CoPilot application version.
getDataVersion()
string
Returns the CoPilot map data version.
getDataYear()
Int
Returns the year of the map data version.
getDataQuarter()
Int
Returns the quarter of the map data version.

Sample Code

CopilotVersion.getAppVersion #

Overview
Description Returns the CoPilot application version currently installed on the device
Supported Since CoPilot Version 9.6.0.867
Supported in following Platforms Android
Type Method
Package com.alk.cpik

Syntax

Return Value

String object containing the application version.

Sample Code

Related APIs

CopilotVersion.getDataVersion #

Overview
Description Returns the CoPilot map data version that is downloaded on the device.
Supported Since Version 9.6.0.867
Platforms Supported Android
Type Method
Package com.alk.cpik

Syntax

Return Value

String object containing the map data version.

Sample Code

CopilotVersion.getDataYear #

Overview
Description Returns an integer representing the year of the map data version that is currently in use on the device (e.g. 2014).
Supported Since Version 9.6.0.867
Platforms Supported Android
Type Method
Package com.alk.cpik

Syntax

Return Value

Integer value of the year of the map data version.

Sample Code

Related APIs

CopilotVersion.getDataQuarter #

Overview
Description Returns an integer representing the quarter that the map data version was released (1, 2, 3, or 4).
Supported Since Version 9.6.0.867
Platforms Supported Android
Type Method
Package com.alk.cpik

Syntax

Return Value

Integer value of the quarter of the map data version.

Sample Code

Related APIs

CopilotMgr #

Overview
Description A class containing static methods for setting and checking various CoPilot features and settings.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Class
Package com.alk.cpik

Methods

Method Name Return Type Description
enableMotionLock(boolean)
void
Enables or disables Motion Lock, which locks the navigation map when the vehicle is in motion.
getMotionLockEnabled()
Boolean
Returns whether Motion Lock is enabled or disabled.
getMotionLockSpeedThreshold()
MotionLockSpeedThreshold
Returns a MotionLockSpeedThreshold object containing the SpeedThreshold for Motion Lock.
setMotionLockSpeedThreshold( MotionLockSpeedThreshold)
void
Sets the SpeedThreshold at which Motion Lock is engaged.
getTimeFormat() [Linux only]
TimeFormat
Returns a TimeFormat enum representing the currently set format.
setTimeFormat(TimeFormat) [Linux only]
void
Sets the time format for CoPilot.
getUnitsOfMeasure()
UnitsofMeasure
Gets the UnitsOfMeasure displayed by CoPilot.
setUnitsOfMeasure(int)
void
Sets the UnitsOfMeasure displayed by CoPilot.
getVersionInfo()
CopilotVersion
Returns a CopilotVersion object containing information about CoPilot’s application version number and map data version.
setTurnInstructionCallbackDelay(int)
void
Sets the time between when turn instruction callbacks onReadyToSpeakTurnInstruction and onSpeakTurnInstructionComplete are fired when CoPilot starts speaking.
getTurnInstructionCallbackDelay()
Int
Retrieves the current delay between when the turn instruction callbacks onReadyToSpeakTurnInstruction and onSpeakTurnInstructionComplete.
getView() [Android only]
View
Retrieves the view associated with the CoPilot service.
isActive() [Android only]
Boolean
Determines if CoPilot can receive API calls. APIs can only be called after the onCPStartup callback is sent and before the onCPShutdown callback returns.
enableGPS() [Android only]
void
Restarts the CoPilot GPS Service and resumes all suspended GPS activities including listening, and processing.
disableGPS() [Android only]
void
Suspends background GPS/routing processing and deregister the CoPilot GPS Service. Background Navigation will not work after this API call.
setBillingProvider (IBillingProviderInterface) [Android only]
void
Sets a third-party, in-app billing provider that should be used by CoPilot for in-app billing operations.
setCopilotStartupParameters (CopilotStartupParams) [Android only]
void
Sets the CopilotStartupParams object that contains overridden methods used during CoPilot Startup.
addFavorite(Favorite)
void
Adds a new favorite to CoPilot’s favorites list.
removeFavorite(int)
void
Removes a favorite from CoPilot.
getFavoritesList()
List<Favorite>
Returns the list of favorites currently stored in CoPilot’s favorites list.

StopBuilder #

Overview
Description Builds stops using some of the optional parameters for creating stops.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Class
Package com.alk.cpik

Methods

Method Name Return Type Description
fromLatLon(Coordinate)
StopBuilder
Static method to create a StopBuilder from a latitude / longitude combination.
fromCountryAndPostalCode(String, String)
StopBuilder
Static method to create a StopBuilder from a country and postal code combination.
fromCityAndState (String, String)
StopBuilder
Static method to create a StopBuilder from a city and state combination.
setLatLong (Coordinate)
StopBuilder
Sets lat/long information for the stop to be created.
setPostalCode (String)
StopBuilder
Sets postal code for the stop to be created.
setStreetAddress (String)
StopBuilder
Sets street address for the stop to be created.
setCity (String)
StopBuilder
Sets city for the stop to be created.
setState (String)
StopBuilder
Sets state for the stop to be created.
setCountry(String)
StopBuilder
Sets country for the stop to be created.
setName(String)
StopBuilder
Sets optional name for the stop to be created.
setCounty(String)
StopBuilder
Sets optional county for the stop to be created.
setDestinationFlag(boolean)
StopBuilder
Sets optional flag to designate whether this stop is to be a waypoint.
geocode(GeocodeSearchType)
StopList
Geocodes the address and returns the list of stops.
setID(String)
StopBuilder
Sets a custom ID for the stop. *Available in version 10.9 and greater
setNote(String)
StopBuilder
Sets a custom note against the stop that will be shown on the stop details screen within the CoPilot UI.*Available in version 10.9 and greater
setEarliestArrivalTime(ArrivalTimeWindowInfo)
StopBuilder
Sets the Earliest acceptable Arrival Time when the stop can be reached. If no date is given, the current date will be used. Requires Additional License. (Optional, but if used setLatestArrivalTime and setPlannedDuration need to be used also.) *Available in version 10.9 and greater
setLatestArrivalTime(ArrivalTimeWindowInfo)
StopBuilder
Sets the Latest Arrival Time for Time Window the stop should be reached. If no date is given, the current date will be used. Requires Additional License.*Available in version 10.9 and greater
setPlannedDuration(int)
StopBuilder
Sets the planned duration for the stop. This should reflect all the non-driving (dwell) time at the destination. Requires Additional License. *Please note Planned Duration will be updated to Seconds in future releases. *Available in version 10.9 and greater
setSideOfStreetAdherence(StopSideAdherenceLevel)
StopBuilder
Sets Side of Street Adherence for the stop.*Available in version 10.9 and greater
setCustomFields(HashMap<String,String> customFields)
StopBuilder
Sets Custom Field for the stop that is used when providing a custom chevron display to the driver.
Please note, to use this field the configuration setting for custom chevron display must also be set. This field should never be used to add a unique identifier to the stop, setID can be used for this purpose. Further details on the configuration setting which must be set can be found within ConfigurationSettings.*Available in version 10.9 and greater
setIcon
string
Sets stop icon image. The name of the image should be passed. Image of the matching name must be saved within CoPilot.*Available in version 10.9 and greater
getNearbyStreets
string
Returns list of nearby streets relative to the coordinates passed to CoPilot, returned as StreetSearchResult
StreetSearchResult
string
Provides list of nearby streets relative to the coordinates passed to CoPilot via getNearbyStreets.

Notes

To build a waypoint rather than a stop, call the setDestinationFlag() method with a false parameter. (Stops are the default.) Waypoints are locations added only to guide the route along desired roads. CoPilot will tell drivers to stop at a stop or to drive through a waypoint.

Sample Code

Stop #

Overview
Description The Stop object provides data related to a specific location. CoPilot uses this information to geocode an address and add it as a stop on a route. Depending on the information provided, CoPilot will endeavor to populate as much of the remaining information about the stop as possible. Stop objects have many optional parameters and should be created via a StopBuilder object.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Class
Package com.alk.cpik

Methods

Method Name Return Type Description
isDestination()
Boolean
Returns true if the stop is a destination.
getName()
string
Gets the name of the object.
getAddress()
string
Gets the address of the object.
getCity()
string
Gets the city in which the object resides.
getState()
string
Gets the state in which the object resides.
getCountry()
string
Gets the country in which the object resides.
getCounty()
string
Gets the county in which the object resides.
getZip()
string
Gets the postal code in which the object resides.
getCoordinate()
Coordinate
Gets the coordinate object.
getID()
string
Gets the Stop ID for the the stop object.This is an optional field.*Available in version 10.9 and greater
getNote()
string
Gets the note associated with the stop object. This is an optional field. *Available in version 10.9 and greater
getEarliestArrivalTime()
ArrivalTimeWindowInfo
Gets the optional early time for the time window where a stop should be reached. *Available in version 10.9 and greater
getLatestArrivalTime()
ArrivalTimeWindowInfo
Gets the latest time for the time window where a stop should be reached. This is an optional field.*Available in version 10.9 and greater
getPlannedDurationMinutes()
Int
Gets the expected Dwell/Wait time that is added to a stop. This is an optional field. *Please note Planned Duration will be updated to Seconds in a release of CoPilot. *Available in version 10.9 and greater
getSideOfStreet()
StopSide
Gets the side of the street that the stop is on. *Available in version 10.9 and greater
getSideOfStreetAdherence()
StopSideAdherenceLevel
Gets the side of street adherence level that the routing uses to calculate its route to this stop. *Available in version 10.9 and greater
getETA()
string
Gets the current ETA for this stop. *Available in version 10.9 and greater
getCustomFields()
Hashmap<String,String>
Gets a Hashmap of the optional custom fields for this stop. *Available in version 10.9 and greater
getIcon()
string
Get the stop icon image name for the stop object. *Available in version 10.9 and greater
getTimeZoneOffset()
Int
Get time zone offset for the stop object. *Available in version 10.9 and greater

Example Output

  • Name: myStop
  • Address: Hallenstraat 19
  • City: Brussels
  • State:
  • Zip: 1000
  • Country: BE
  • Waypoint: false
  • Location:
    • Coordinates:50.85N, 4.35E
  • ID: This is id
  • Note: This is a note
  • Earliest Arrival Time:5/22/2018:13:0
  • Latest Arrival Time: 5/22/2018:14:0
  • Delivery Status:EARLY
  • Planned Duration:12
  • TimeZoneOffset:240
  • Side Of Street:UNKNOWN
  • Side Of Street Adherence:MODERATE
  • Advanced ETA:2018-05-31T14:32:20-04:00
  • Icon:myStopIcon
  • Custom Field : (CUSTOMCHEVRONDISPLAY:chevronmessage)
  • Vehicle Restricted: False

stop.isVehicleRestricted #

Overview
Description Returns true if the stop is mapped to a Vehicle Restricted Road (only allows pedestrians or bicycles). If this is true, CoPilot will route to closest road that allows vehicles.
Supported on Android Since Version 10.14
Supported on iOS Since Version 10.14
Type Method
Package com.alk.cpik

Syntax

Parameters

None

Return Values

Boolean

Sample Code

StopBuilder.getNearbyStreets #

Overview
Description This API will return a list of nearby streets relative to the coordinates passed to CoPilot. All nearby street names within the configurable distance, set as a maximum of 1 mile, will be returned. The number of streets returned can be set up to a maximum of 10. Streets will be returned sorted in order of distance.
Supported on Android Since Version 10.9
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.stopbuilder

Syntax

Parameters

Parameter Description
distance Maximum distance to return street names from, maximum distance of 1 mile.
maxResults Number of results to be returned. Maximum of 10.

Return Value

Street Name - String
Distance - double

Sample Code

StopBuilder.StreetSearchResult #

Overview
Description This API will return a list of nearby streets relative to the coordinates passed to CoPilot. All nearby street names within the configurable distance, set as a maximum of 1 mile will be returned. The number of streets returned can be limited within the request which will be returned sorted in order of distance.
Supported on Android Since Version 10.9
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.stopbuilder

Syntax

Parameters

Parameter Description
distanceThreshold Maximum distance to return street names from, maximum distance of 1 mile.
maxResults Number of results to be returned

Return Value

Street Name - String
Distance - double

Sample Code

GeocodeSearchType #

Overview
Description An enum that allows different types of geocoding. Geocoding attempts to match user input with actual locations in the CoPilot map database.
Supported on Android Since Version 9.6.0.1000
Type Enum
Package com.alk.cpik

Values

Value Description
EXACT_MATCH_ONLY Return only one stop. Will only return a stop that is an exact match to the input.
MULTI_MATCH Will return a list of stops which are closest to the given information.
BEST_MATCH Returns the best match geocoded stop from the given information.

StopSideAdherenceLevel #

Overview
Description An enumerated value that defines the Side of Street adherence level, which defines the extent to which CoPilot will try to route to the side of the street where a stop is located.
For further details on how this can affect a route, please see the Side of Street explanation document.
Supported Since Version 10.9
Platforms Supported Android, Linux
Type Enum
Package com.alk.cpik

Values

Value Description
OFF Will not reroute according to side of the street.
MINIMAL Will increase the route by up to a maximum of 1⁄4 mile to avoid ending up on the wrong side of the street.
MODERATE Will increase the route by up to a maximum of 1/2 mile to avoid ending up on the wrong side of the street.
AVERAGE Will increase the route by up to a maximum of 1 mile to avoid ending up on the wrong side of the street.
STRICT Will increase the route by up to a maximum of 5 miles to avoid ending up on the wrong side of the street.
ADHERE Will increase the route by up to a maximum of 10 miles to avoid ending up on the wrong side of the street.
STRONGLY_ADHERE Will route the driver by any possible means to reach the correct side of the street.

StopSide #

Overview
Description An enumerated value that represents whether the side of street of the specified stop is known. If it is known, the value will indicate if it is on the left-hand side of the road or right.
Supported Since Version 10.9
Platforms Supported Android, Linux
Type Enum
Package com.alk.cpik

Values

Value Description
UNKNOWN Stop Side Unknown
LEFT Stop Side Left
RIGHT Stop Side Right

StopArrivalStatus #

Overview
Description An enumerated value that indicates the status of the stop relative to the defined time window.
Supported Since Version 10.9
Platforms Supported Android, Linux
Type Enum
Package com.alk.cpik

Values

Value Description
UNKNOWN Arrival window status unknown
EARLY Stop arrival time early and expected before the defined window
ON_TIME On time with the defined arrival time window
AT_RISK Current ETA is at risk of the arrival time window
LATE Current ETA is later than the defined window

StopClickedInfo #

Overview
Description The StopClickedInfo class is used within the onMapStopClicked callback, which is called when a user clicks on a location on the map.

StopClickedInfo can be used to replicate the UI functionality in CoPilot, and it is specifically useful if using the CPIK No_Widget views and a custom UI. This would allow the integration application to replicate the pop up information based on a user tapping on the map screen.

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

Methods

Method Name Return Type Description
getClickedStop()
Stop
Gets information about the stop that was clicked.
getClickType()
StopClickType
Lets you distinguish whether a click on the map was a road, origin, destination, waypoint or intermediate stop.
toString()
String
Returns the string representation of the Stop object.

getClickType #

Overview
Description Lets you distinguish whether a click on the map was a road, origin, destination, waypoint or intermediate stop.
Supported Since Version 10.9.0.958
Platforms Supported Android, iOS Linux
Type Method
Package com.alk.cpik

Syntax

Parameters

None

Return Values

A StopClickType

Sample Code

StopClickType #

Overview
Description A value that represents the type for the location a user clicked on the map.
Supported Since Version 10.9.0.958
Platforms Supported Android, iOS Linux
Type Method
Package com.alk.cpik.ui

Syntax

StopClickType.ROAD

Values
ROAD
ORIGIN_STOP
DEST_STOP
WAYPOINT
INTERMEDIATE_STOP
UNKNOWN_ERROR

Sample Code

ArrivalTimeWindowInfo #

Overview
Description ArrivalTimeWindowInfo is a class that is used to assign a time window. Date information (i.e., day, month and year) are optional, but minutes from midnight is required. If user only specifies minutes from midnight, CoPilot will use today’s date. Minutes from midnight is the time since midnight in minutes. For example, if minutes from midnight is set to 960, this equates to a time of 4:00PM.
Supported Since Version 10.9
Platforms Supported Android, Linux
Type Object
Package com.alk.cpik

Methods

Method Name Return Type
getDay() int
getMonth() int
getYear() int
getMinutesFromMidnight() int
setDate(int, int, int) void
setMinutesFromMidnight(int) void
toString()
String

Sample Code

FavoriteBuilder #

Overview
Description Favorite objects have many optional parameters, and should be built via this FavoriteBuilder class. Favorites are CoPilot’s list of a user’s favorite locations.
For example: Favorite myFavorite = new FavoriteBuilder.setName(“MyFavorite”).setCountry(“US”).build();
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version Android, Linux
Type Class
Package com.alk.cpik.trip

Methods

Method Name Return Type Description
setName(String) FavoriteBuilder Sets name of the favorite.
setStreetAddress(String) FavoriteBuilder Sets street address of the favorite.
setCity(String) FavoriteBuilder Sets city of the favorite.
setState(String) FavoriteBuilder Sets state of the favorite.
setCountry(String) FavoriteBuilder Sets country of the favorite.
setZip(String) FavoriteBuilder Sets zip code of the favorite.
setFavoriteType(FavoriteType) FavoriteBuilder Sets FavoriteType of the favorite.
setFavoriteType(int) FavoriteBuilder Sets FavoriteType of the int.
setCoordinates(LocationCoordinate) FavoriteBuilder Sets coordinates of the favorite.
build() Favorite Constructs and returns a new favorite object with the information that has been set using a FavoriteBuilder object.

Sample Code

Favorite #

Overview
Description Favorite objects contain information to be used in CoPilot’s list of a user’s favorite locations. Favorite objects have many optional parameters and cannot be constructed by themselves. They should be created via a FavoriteBuilder object.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Object
Package com.alk.cpik.trip

Methods

Method Name Return Type Description
getFavoriteType() FavoriteType Gets the FavoriteType describing the favorite.
getName()
string
Gets name of the object.
getAddress()
string
Gets address of the object.
getCity()
string
Gets city in which the object resides.
getState()
string
Gets state in which the object resides.
getCountry()
string
Gets country in which the object resides.
getZip()
string
Gets postal code in which the object resides.

Example Output

Name: myFavorite Address: Avenue A.J. Slegers 397 City: Brussels State: Zip: 1200 Country: BE Type: HOME Location: Coordinates: 50.84035N, 4.413889E

FavoriteType #

Overview
Description An enum of the ways to define a favorite type.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.trip

Values

Value Description
GENERAL The favorite is a general favorite.
HOME The favorite is the Home location.
WORK The favorite is the Work location.

ContactBuilder #

Overview
Description Builder to create Contact objects
Supported on Android Since Version 9.6.0
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik

Public Methods

Method Name Return Type
setName(String)
string
setPhoneNumber(String)
ContactBuilder
setEmailAddress(String)
ContactBuilder
setStreetAddress(String)
ContactBuilder
setCity(String)
ContactBuilder
setState(String)
ContactBuilder
setCountry(String)
ContactBuilder
setZip(String)
ContactBuilder
setCoordinates(Coordinate)
ContactBuilder
build() Contact

Sample Code

CoPilotMgr.singleSearchInit #

Overview
Description This API initiates single search. This includes several HTTP requests and requires internet connection. Once the initialization has successfully finished, a callback onSingleSearchReady will be returned indicating that the other Single Search APIs are available to use.
Note: This API must be called and the onSingleSearchReady callback received before Single Search APIs can be used.
Supported Since Version 10.9
Platforms Supported Android, Linux
Type Method
Package com.alk.cpik

Sample Code

SingleSearchError #

Overview
Description A response enum from a request to the Single Search web service. Responses will provide information on the result of the request including specific reasons if a request fails.
Supported Since Version 10.9
Platforms Supported Android, Linux
Type Enum
Package com.alk.cpik

Value

Value Description
OK Successfully get the single search response
FAILURE_INIT Failed to initialize single search
FAILURE_WEBSERVICE Single Search Web Service returns errors
FAILURE_CONNECT There are network connection issues
FAILURE_INVALID_JSON While using singleSearchJSON API, the JSON parameter user passes in is invalid
FAILURE_DATA_NOT_LICENSED_OR_NOT_INSTALLED You requested data is either not licensed or not installed
FAILURE_DATA_NOT_AVAILABLE_FOR_RESULT The stop results returned from single search web service are not valid in CoPilot installed data
FAILURE_GENERIC Unknown errors

CopilotMgr.singleSearch #

Overview
Description This API is used for a Single Search query. It will send user’s query string together with all default search settings to the Single Search web service. This API is not synchronous. A callback onSingleSearchFinished will be returned once web service gives the response back.
Supported Since Version 10.9
Platforms Supported Android, Linux
Type Method
Package com.alk.cpik

Syntax - static void singleSearch(String query)

Parameters String: Single search query string. Can be address, POI name, street name, city name, zip.

Sample Code

CopilotMgr.singleSearchJSON #

Overview
Description This API is used for Single Search query. User needs to pass a JSON string containing the query with the customized search settings. This API is not synchronous. A callback onSingleSearchFinished will be fired once web service gives the response back.
Supported Since Version 10.9
Platforms Supported Android, Linux
Type Method
Package com.alk.cpik

Syntax - static void singleSearchJSON(String settingsJSON)

Parameters String: A json string that contains query string as well as search settings. Below is an example:

{
  "Query": "1 independence way princeton nj",
  "MaxResults":20,
  "Location":{
   "Address":{
     "StreetAddress":"1 independence way",
     "City":"Princeton",
     "State":"NJ",
     "Zip":"08540",
     "County":"Mercer",
     "Country":""
   },
   "Coords":{
    "Lat":"40.361076",
    "Lon":"-74.601515"
   }
  },
  "Searchtype":1,
  "PoiCategories":["Airport", "bank", "CAT scales"],
  "Countries":["CA", "US", "GL"],
  "States":["NJ", "NM"]

Sample Code

CopilotMgr.getSingleSearchPOICategories #

Overview
Description This API is used to get a list of POI categories that can be recognized by Single Search web service. This is used to form the json string for singleSearchJSON API, specifically the “PoiCategories” field.
Supported Since Version 10.9
Platforms Supported Android, Linux
Type Method
Package com.alk.cpik

Syntax - static List getSingleSearchPOICategories()

Return Values - List

Sample Code

CopilotMgr.getSingleSearchCountries #

Overview
Description This API will return the list of countries the user is able to search within. User may need it to form the json string (the “Countries” field) for singleSearchJSON API.
Please note the countries that are returned must have been licensed, map data present on the device and those countries supported by the Single Search Web service.
Supported Since Version 10.9
Platforms Supported Android, Linux
Type
Package com.alk.cpik

Syntax - static List getSingleSearchCountries ()

Return Values - List

Sample Code

Last updated June 8, 2021.