Launching CoPilot from Another App

CoPilot's URL launch feature allows you to open CoPilot and pass in a location from another application without integrating the two apps. (The apps must be on the same device.) The location is passed with one of three actions:

  • VIEW: Show the location on the map.

  • GOTO: Clear the current trip and set the location as the only destination.

  • ADDNEXTSTOP: Add the location as a new stop ahead of any stops currently in the trip itinerary.

The location can be entered as GPS coordinates or as a street address. If both are entered, the coordinates will be used. Once the location has been identified, CoPilot will perform the corresponding action passed in by the action parameter. If a location cannot be found, CoPilot will ignore the location and no action will be taken.

Note

The URL Launch is only supported on our Truck licensed application.

URL Format

copilot://mydestination?type=LOCATION&action=%act&lat=%la&long=%lo&name=%name&address=%addr&city=%city&juris=%jurisdiction&state=%state&zip=%zip

This format is supported on Android, iOS and Windows platforms. For CoPilot 9, the base URL copilotv9:// can also be used.

Example Strings

copilot://mydestination?type=LOCATION&action=VIEW&lat=+40388249&long=-74654724 
copilot://mydestination?type=LOCATION&action=ADDNEXTSTOP&address=1000 Herrontown Road&city=Princeton&state=NJ&zip=08540 
copilot://mydestination?type=LOCATION&action=GOTO&lat=+40388249&long=-74654724

URL Parameters

Parameter Description Required?
action The action performed with the location in CoPilot.

VIEW: Show the location on the map.

GOTO: Clear the current trip and set the location as the only destination.

ADDNEXTSTOP: Add the location as a new stop ahead of any stops currently in the trip itinerary.

Y
lat Latitude, expressed as an integer value in millionth of a degree or a decimal value Y, if no address is provided
long Longitude, expressed as an integer value in millionth of a degree or a decimal value Y, if no address is provided
name The name of the location N
address The street address of the location Optional if latitude and longitude are supplied
city The city of the location Optional if latitude and longitude are supplied
juris The jurisdiction of the location Optional if latitude and longitude are supplied
state The state of the location. State = Country when outside of North America. Optional if latitude and longitude are supplied
zip The ZIP or Postal code of the location. Optional if latitude and longitude are supplied

Notes on Parameters

  1. When latitude and longitude values are sent as long integers, they are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, our London office is located at 0.122805W & 51.518220N so it should be passed as a -122805 longitude & +51518220 latitude. Conversion to long integers is not mandatory as coordinates sent in a decimal format are also supported within CoPilot.
  2. When entering latitude and longitude, “+” is optional however “-“ is mandatory where required.
  3. Query names are case sensitive.
  4. To best find a destination, you should supply one of the two following combinations of data:
    • Latitude and Longitude
    • Address, City, State/Jurisdiction, ZIP
  5. GOTO and ADDNEXTSTOP will work as described if user is on navigation mode. If user is in planning mode they may get different result.
  6. The Name field is limited to 164 characters.
  7. When a stop is passed to CoPilot with action command ADDNEXTSTOP, the device's GPS fix status may affect this command:
    • With a GPS fix, action commands will take effect as described above.
    • Without a GPS fix and gpssave.dat/gpstrip.trp files in CoPilot folders: Next Stop function will not add a stop but replace the existing one.
    • With a GPS fix and a stop set: When a house number is included with an address, the CoPilot UI ask to set the stop as the destination, but when you use the ADDNEXTSTOP action it will be added as the next stop, not the destination.

GEO URI Format

CoPilot also supports the use of the Geo URI scheme on the Android platform. Coordinates as well as address can be passed in this format. If lat/long is provided, the address is ignored. The exact lat/long should be passed using a decimal place and a comma to separate.

Example Strings

geo:0,0?q=35 Network Dr, Burlington, 01803, MA 
geo:42.496652,-71.228454?q=35 Network Dr, Burlington, 01803, MA 

Legacy Format

Some existing Android implementations may use the copilotlive.com format below for URL Launch. It will continue to be supported, but we recommend that all new implementations use the copilot:// format listed above.

http://www.copilotlive.com/copilot/android?type=LOCATION&action=%act&lat=%la&long=%lo&name=%name&address=%addr&city=%city&juris=%jurisdiction&state=%state&zip=%zip

Example Strings

http://www.copilotlive.com/copilot/android?type=LOCATION&action=VIEW&lat=+40388249&long=-74654724 
http://www.copilotlive.com/copilot/android?type=LOCATION&action=ADDNEXTSTOP&address=1000 Herrontown Road&city=Princeton&state=NJ&zip=08540 
http://www.copilotlive.com/copilot/android?type=LOCATION&action=GOTO&lat=+40388249&long=-74654724 

FleetPortal Connection

Available in CoPilot 10.9.0.1098 or Higher

URL launch can also be used to set up a device so it can connect to CoPilot FleetPortal. CoPilot FleetPortal is a web-based fleet management solution that extends the functionality of CoPilot. It allows fleet managers to remotely configure CoPilot vehicle settings and vehicle routing profiles to be used by the fleet and assign specific routing profiles to vehicle and driver groups within the fleet.

Example Format

copilot://options?type=FLEETPORTAL&action=Set&DriverID=99999&DeviceID=1111&PartnerID=XYZXYZ&EnableCompliance=true&EnableFleetPortal=true&ShowConfirmation=false&ShowCompliancePopup=true

This format is supported on Android, iOS and Windows platforms. For CoPilot 9, the base URL copilotv9:// can also be used.

Parameter Description Type
DriverID Identifies a specific driver within a company alphanumeric
DeviceID Identifies a specific CoPilot device within the partner domain alphanumeric
ParterID An identifier created by Trimble MAPS and supplied to the partner for use in identifying their customers' CoPilot units within CoPilot FleetPortal alphanumeric
EnableCompliance Set to true to turn on route compliance boolean
EnableFleetPortal Set to true to enable FleetPortal on the device boolean
ShowConfirmation Set to true for the confirmation message, “FleetPortal settings have been updated” to appear on the device boolean
ShowCompliancePopup If turned on (true), the user will be asked, "Enable compliance for this route?" before the route is converted to a compliance route. This setting is off (false) by default. boolean