Skip to content

RouteMgr

Note

All React Native methods are async functions.

Overview
Description A native module containing methods related to a route, defined as a list of stops and a route that is calculated between them.
Supported on React Native Since Version 10.14
Type Native Module

Methods

Method Name Return Type Description
setActiveVehicleRoutingProfile(VehicleRoutingProfile) void Sets the active VehicleRoutingProfile to be used in routing.
getActiveVehicleRoutingProfile() VehicleRoutingProfile Gets the active VehicleRoutingProfile being used in routing.
resetVehicleRoutingProfileToDefault(String profileName) boolean Resets the specified VehicleRoutingProfile to the default for that vehicle type.
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.
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.
isCopilotReadyToAddStops() boolean Returns whether or not CoPilot is ready to add stops
getRouteLegs() List<​JSON Object (Leg)> Returns a list of each leg along the current route.

Hooks and Callbacks

Hooks and Callbacks related to routing can be found below.

RouteListener
onGPSFixChanged
onStopsAdded
onStopsDeleted
onStartRouteCalculation
onCompleteRouteCalculation
onFailedRouteCalculation
onStopArrivalStatusChange

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 on React Native Since Version 10.14
Type Method

Syntax

void setActiveVehicleRoutingProfile(JSONObject)

Parameters

VehicleRoutingProfile JSON Object - The profile to set in CoPilot

Return Value

None

Sample Code

const RouteMgr = NativeModules.RouteMgr;
const VehicleRoutingProfile = NativeModules.VehicleRoutingProfile;
const VehicleType = NativeModules.VehicleType;

var profile = await VehicleRoutingProfile.createNewProfile(
  "CPIK Test",
  VehicleType.TRUCK_HEAVY_DUTY
);
RouteMgr.setActiveVehicleRoutingProfile(profile);

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 on React Native Since Version 10.14
Type Method

Syntax

JSONObject getActiveVehicleRoutingProfile();

Parameters

None

Return Value

VehicleRoutingProfile - CoPilot’s currently selected routing profile.

Sample Code

const RouteMgr = NativeModules.RouteMgr;
var currentProfile = await RouteMgr.getActiveVehicleRoutingProfile();

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 on React Native Since Version 10.14
Type Method

Syntax

JSONArray getVehicleRoutingProfiles()

Parameters

None

Return Value

JSON Array of VehicleRoutingProfile JSON objects - A list of all routing profiles in CoPilot

Sample Code

const RouteMgr = NativeModules.RouteMgr;
var allProfiles = await RouteMgr.getVehicleRoutingProfiles();

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 on React Native Since Version 10.14
Type Method

Syntax

getVehicleRoutingProfile(string profileName)

Parameters

string profileName - The profile name to search for.

Return Value

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

Sample Code

var profile = await RouteMgr.getVehicleRoutingProfile(name);

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 on React Native Since Version 10.14
Type Method

Parameters

String profileName - The profile name to reset

Return Value

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

Sample Code

const RouteMgr = NativeModules.RouteMgr;
var result = await RouteMgr.resetVehicleRoutingProfileToDefault("ResetTest");

VehicleRoutingProfile

Overview
Description A native module describing a vehicle routing profile in CoPilot. 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 JSON 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.

Supported on React Native Since Version 10.14
Type Native Module

Methods

Method Name Return Type Description
createNewProfile(String, VehicleType) VehicleRoutingProfile Create a new VehicleRoutingProfile

VehicleRoutingProfile.createNewProfile

Overview
Description Create a new VehicleRoutingProfile.
Supported on React Native Since Version 10.14
Type Method

Syntax

JSONObject createNewProfile(profileName, vehicleType)

Parameters

profileName - A string with the profile name.

vehicleType - The vehicle type to be used to create the routing profile.

Return Value

A VehicleRoutingProfile JSON Object

Sample Code

const VehicleRoutingProfile = NativeModules.VehicleRoutingProfile;
const VehicleType = NativeModules.VehicleType;

var rpTruckDef = await VehicleRoutingProfile.createNewProfile(
  "HeavyDutyDefaults",
  VehicleType.TRUCK_HEAVY_DUTY
);

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.

Supported on React Native Since Version 10.14
Type Method

Syntax

void resetUserRoadSpeeds(vehicleType, jurisdiction)

Parameters

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 Value

None

Sample Code

const RouteMgr = NativeModules.RouteMgr;
const VehicleType = NativeModules.VehicleType;

RouteMgr.resetUserRoadSpeeds(VehicleType.TRUCK_MEDIUM_DUTY, "New Jersey");
RouteMgr.resetUserRoadSpeeds(VehicleType.TRUCK_HEAVY_DUTY, "");

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 on React Native Since Version 10.14
Type Method

Syntax

void setUserRoadSpeeds(roadSpeedSet)

Parameters

RoadSpeedSet - A JSON Object with the custom road speed set to set in CoPilot.

Sample Code

const RouteMgr = NativeModules.RouteMgr;
const VehicleType = NativeModules.VehicleType;

var roadSpeedsNJ = await RouteMgr.getDefaultRoadSpeeds(
  VehicleType.TRUCK_MEDIUM_DUTY,
  "New Jersey"
);
roadSpeedsNJ.urbanSpeeds.interstate = 30;
roadSpeedsNJ.ruralSpeeds.divided_highway = 25;
await RouteMgr.setUserRoadSpeeds(roadSpeedsNJ);

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 on React Native Since Version 10.14
Type Method

Syntax

JSONArray getUserRoadSpeeds(VehicleType, jurisdiction)

Parameters

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 Value

A JSON array of RoadSpeedSet objects representing the user road speeds that are set in CoPilot.

Sample Code

const RouteMgr = NativeModules.RouteMgr;
const VehicleType = NativeModules.VehicleType;

var userSpeedNJ = await RouteMgr.getUserRoadSpeeds(
  VehicleType.TRUCK_MEDIUM_DUTY,
  "New Jersey"
);
var allUserSpeeds = await RouteMgr.getUserRoadSpeeds(
  VehicleType.TRUCK_MEDIUM_DUTY,
  ""
);

RouteMgr.getDefaultRoadSpeeds

Overview
Description Returns the list of default road speeds in CoPilot per vehicle type.
Supported on React Native Since Version 10.14
Type Method

Syntax

JSONArray getDefaultRoadSpeeds(VehicleType, jurisdiction)

Parameters

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 default road speeds for. Passing null or empty string will return all jurisdictions.

Return Value

A JSON array of RoadSpeedSet objects representing the default road speeds.

Sample Code

const RouteMgr = NativeModules.RouteMgr;
const VehicleType = NativeModules.VehicleType;

var roadSpeedsNJ = await RouteMgr.getDefaultRoadSpeeds(
  VehicleType.TRUCK_MEDIUM_DUTY,
  "New Jersey"
);
var allDefaultRoadSpeeds = await RouteMgr.getDefaultRoadSpeeds(
  VehicleType.TRUCK_MEDIUM_DUTY,
  ""
);

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 React Native Since Version 10.14
Type Method

Syntax

bool isCopilotReadyToAddStops()

Parameters

None

Return Value

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

Sample Code

const RouteMgr = NativeModules.RouteMgr;
var iSReadyToAddStops = await RouteMgr.isCopilotReadyToAddStops();

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 on React Native Since Version 10.14
Type Method

Note

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

Scenario 1 – Only the full address is passed

  • CoPilot will try to geocode the address.

Scenario 2 – Only lat/long is passed

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

Scenario 3 – Both Address and lat/long are passed

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

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

Tip

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

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

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

Syntax

RouteMgr.addStop(AddStopPurpose, Stop, RoutePreviewMode)

Parameters

AddStopPurpose - A native module constant describing how to incorporate a stop into a trip.

Stop - A JSON object with details about the stop.

RoutePreviewMode - A native module constant that tells CoPilot what route preview that user wants to show in CoPilot UI.

Sample Code

const RouteMgr = NativeModules.RouteMgr;
const StopBuilder = NativeModules.StopBuilder;
const GeocodeSearchType = NativeModules.GeocodeSearchType;
const AddStopPurpose = NativeModules.AddStopPurpose;
const RoutePreviewMode = NativeModules.RoutePreviewMode;

var latlon = {};
latlon.latitude = 40.368273;
latlon.longitude = -74.654965;
var stopBuilder = await StopBuilder.fromLatLon(latlon);
var stops = await StopBuilder.geocode(
  stopBuilder,
  GeocodeSearchType.BEST_MATCH
);
RouteMgr.addStop(
  AddStopPurpose.NEW_TRIP,
  stops[0],
  RoutePreviewMode.NO_PREVIEW
);

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 on React Native Since Version 10.14
Type Method

Note

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

Scenario 1 – Only the full address is passed

  • CoPilot will try to geocode the address.

Scenario 2 – Only lat/long is passed

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

Scenario 3 – Both Address and lat/long are passed

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

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

Tip

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

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

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

Syntax

void addStops(AddStopPurpose, stopList, RoutePreviewMode)

Parameters

AddStopPurpose - A native module constant describing how to incorporate a stop into a trip.

stopList - A JSON array of Stop objects with details about the stop.

RoutePreviewMode - A native module constant that tells CoPilot what route preview that user wants to show in CoPilot UI.

Return Value

None

Sample Code

const RouteMgr = NativeModules.RouteMgr;
const StopBuilder = NativeModules.StopBuilder;
const GeocodeSearchType = NativeModules.GeocodeSearchType;
const AddStopPurpose = NativeModules.AddStopPurpose;
const RoutePreviewMode = NativeModules.RoutePreviewMode;

var stopList = [];

var latlon = {};
latlon.latitude = 40.368273;
latlon.longitude = -74.654965;
var stopBuilder = await StopBuilder.fromLatLon(latlon);
var stops = await StopBuilder.geocode(
  stopBuilder,
  GeocodeSearchType.BEST_MATCH
);
stopList.push(stops[0]);

latlon.latitude = 40.345621;
latlon.longitude = -74.645877;
stopBuilder = await StopBuilder.fromLatLon(latlon);
stops = await StopBuilder.geocode(stopBuilder, GeocodeSearchType.BEST_MATCH);
stopList.push(stops[0]);

RouteMgr.addStops(
  AddStopPurpose.AFTER_FINAL_DESTINATION,
  stopList,
  RoutePreviewMode.NO_PREVIEW
);

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.

Supported on React Native Since Version 10.14
Type Method

Syntax

void removeAllStops()

Parameters

None

Return Value

None

Sample Code

NativeModules.RouteMgr.removeAllStops();

RouteMgr.getStopList

Overview
Description Returns a list of stops currently added to the trip.
Supported on React Native Since Version 10.14
Type Method

Syntax

JSONArray getStopList()

Parameters

None

Return Value

A JSON array of Stop objects that represent the stops on the current route.

Sample Code

var stops = await NativeModules.RouteMgr.getStopList();

RouteMgr.calculateRoute

Overview
Description If valid stops have been added, this causes a route to be calculated between them.
Supported on React Native Since Version 10.14
Type Method

Syntax

void calculateRoute()

Parameters

None

Return Value

None

Sample Code

const RouteMgr = NativeModules.RouteMgr;
const StopBuilder = NativeModules.StopBuilder;
const GeocodeSearchType = NativeModules.GeocodeSearchType;
const AddStopPurpose = NativeModules.AddStopPurpose;
const RoutePreviewMode = NativeModules.RoutePreviewMode;

RouteMgr.removeAllStops();

var stopList = [];

var latlon = {};
latlon.latitude = 40.36842;
latlon.longitude = -74.655036;
var stopBuilder = await StopBuilder.fromLatLon(latlon);
var stops = await StopBuilder.geocode(
  stopBuilder,
  GeocodeSearchType.BEST_MATCH
);
stopList.push(stops[0]);

latlon.latitude = 40.36853;
latlon.longitude = -74.6552036;
stopBuilder = await StopBuilder.fromLatLon(latlon);
stops = await StopBuilder.geocode(stopBuilder, GeocodeSearchType.BEST_MATCH);
stopList.push(stops[0]);

RouteMgr.addStops(
  AddStopPurpose.AFTER_FINAL_DESTINATION,
  stopList,
  RoutePreviewMode.NO_PREVIEW
);

RouteMgr.calculateRoute();

RouteMgr.optimizeStops

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

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

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

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

Refer to OptimizationMgr for the advanced optimization options.

Supported on React Native Since Version 10.14
Type Method

Syntax

bool optimizeStops(bKeepFinalDestination)

Parameters

bool bKeepFinalDestination- Set to true to keep optimization from changing the final stop.

Return Value

True on success

Sample Code

const RouteMgr = NativeModules.RouteMgr;
var routeOptimizationSuccessful = await RouteMgr.optimizeStops(true);

RouteMgr.getRouteLegs

Overview
Description Returns a list of each leg along the current route.
Supported on React Native Since Version 10.14
Type Method

Syntax

JSONArray getRouteLegs(ignoreWaypoints)

Parameters

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

Return Value

A JSON Array of Leg JSON objects

Sample Code

const RouteMgr = NativeModules.RouteMgr;
var legList = await RouteMgr.getRouteLegs(false);

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 React Native Since Version 10.14
Type Method

Syntax

bool hasDestination()

Parameters

None

Return Value

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

Sample Code

const RouteMgr = NativeModules.RouteMgr;
var navigatingToDestination = await RouteMgr.hasDestination();

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 React Native Since Version 10.14
Type Method

Syntax

constant deleteRoutingProfile(profileName)

Parameters

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

Return Value

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

Sample Code

const RouteMgr = NativeModules.RouteMgr;
var result = await RouteMgr.deleteRoutingProfile("ProfileName B");

Last update: August 24, 2020