Skip to content

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=1000HerrontownRoad&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:
  5. Latitude and Longitude
  6. Address, City, State/Jurisdiction, ZIP
  7. GOTO and ADDNEXTSTOP will work as described if user is on navigation mode. If user is in planning mode they may get different result.
  8. The Name field is limited to 164 characters.
  9. When a stop is passed to CoPilot with action command ADDNEXTSTOP, the device's GPS fix status may affect this command:
  10. With a GPS fix, action commands will take effect as described above.
  11. 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.
  12. 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 an 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


Available in CoPilot 10.14.0.368 and Higher
Geo URIs also support usage of the '@' character to separate coordinates and address. When using the '@' character, the coordinates provided after "geo:" should be "0,0". See below for examples. Note how the order of the address and the coordinates before or after the '@' character does not matter. Both methods are supported.

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

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

License Activation with URL Launch

Available in CoPilot 10.14 and Higher with Account Manager Licensing Only

The Account Manager is a web tool that allows you to distribute and manage the product licenses your fleet has purchased for CoPilot Truck With ActiveTraffic. In the Account Manager, you can create lists of users (either drivers, devices or vehicles), remotely distribute software licenses to those users, and then re-assign your licenses as needed when your devices or staffing change.

After the licenses are distributed, the CoPilot app itself is downloaded onto a device and requires a login. With URL launch, the login process is automated and drivers can open CoPilot and begin navigation without needing to enter login credentials.

Example Format

copilot://options?type=AMS&action=Set&CompanyID=JTEVJA&Username=user1&ShowConfirmation=true
Parameter Description Type Required
CompanyID The company identifier for Account Manager assigned by Trimble MAPS. alphanumeric Y
Username The External ID for the user that was created in Account Manager. (The External ID could be a company issued device ID, driver ID, email address, phone number, etc.—depending on how you chose to identify users when you set up your account.) alphanumeric Y
ShowConfirmation If set to true, a confirmation message will be shown if CompanyID and Username are correctly set. Default is false. boolean N

FleetPortal Connection

Available in CoPilot 10.9.0.1098 and 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.

If you are using URL launch and the Account Manager to assign CoPilot licenses to vehicles or drivers, these FleetPortal settings are applied automatically. A second call to the FleetPortal URL is not needed. An exception would be if you are using unique device IDs rather than vehicle or driver IDs to track your licenses in Account Manager. In that case, you would:

  • Call the Account Manager URL with Username set to the device ID used in Account Manager.
  • Call the FleetPortal URL below with DeviceID set to the appropriate vehicle ID used in FleetPortal. That ensures CoPilot has the correct settings if the device is moved from vehicle to vehicle.

Example Format

copilot://options?type=FLEETPORTAL&action=Set&DriverID=99999&DeviceID=1111&PartnerID=XYZXYZ&EnableCompliance=true&EnableFleetPortal=true&ShowConfirmation=false&ShowCompliancePopup=true
Parameter Description Type
DriverID Identifies a specific driver within a company alphanumeric
DeviceID Identifies a specific CoPilot device within the partner domain alphanumeric
PartnerID 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

Last update: April 7, 2020