Skip to content

URL Launch

CoPilot's URL launch feature allows you to launch and manage CoPilot from another application on the same device.

URL launch is most commonly used with our CoPilot Standalone App as a way of automating the CoPilot login process; identifying which vehicle or driver is using CoPilot; and adding a button to CoPilot that sends it to the background and returns to the mobile app from which it was launched.

Depending on your implementation, URL launch can be used for a wide range of tasks and settings. Passing information to CoPilot via URL, you can:

  • Activate a license. This automates the process of activating licenses that you have distributed to your devices using the Trimble MAPS Account Manager. Available in CoPilot 10.19 and Higher with Account Manager Licensing Only

  • Identify the vehicle and driver using CoPilot. Each instance of CoPilot needs to know which Vehicle or Driver is using it any given time. CoPilot will update its settings according to the configuration in FleetPortal for the vehicle or driver associated with that instance of CoPilot. Available in CoPilot 10.19 and Higher with Account Manager Licensing Only

  • Set configurations. CoPilot can be configured to meet your fleet's specific needs. Settings are available that allow to you to customize everything from the information that appears on the CoPilot screen to the language CoPilot uses for voice guidance. Available in CoPilot 10.19 and Higher

  • Send a single stop or multiple stops to CoPilot to build a route. Pass a single stop or multiple stops into CoPilot, all at once, to build a full trip.

  • Send a single stop to CoPilot and view it on the map. This feature, which is compatible with older versions of CoPilot, allows you add stops on an itinerary, one-by-one, as GPS coordinates.

  • Connect to FleetPortal. URL launch can be used set up a device so it can connect to FleetPortal, a web tool that allows fleet managers to remotely configure CoPilot vehicle settings and vehicle routing profiles to be used by the fleet. Available in CoPilot 10.9.0.1098 and Higher

Note

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

Activate a License

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 vehicles, devices, or drivers), 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.

URL Format for Direct CoPilot Customers

Available in CoPilot 10.19 and Higher

copilot://options?type=CONFIG&CompanyID=trimble-defined.customer.id&AssetID=customer-defined.asset.id&showconfirmation=true
Parameter Description Type Required
CompanyID The company account identifier assigned by Trimble MAPS. alphanumeric Y
AssetID The identifier for the asset to which a license is assigned in the Account Manager. (Often, but not always, a Vehicle ID) alphanumeric Y
ShowConfirmation If set to true, a confirmation message will be shown if CompanyID and AssetID are correctly set. Default is false. boolean N

URL Format for Partners Reselling CoPilot

Available in CoPilot 10.19 and Higher

copilot://options?type=CONFIG&PartnerID=sample-partner&ExternalAccountID=partner-defined.account.id&AssetID=partner-defined.asset.id&showconfirmation=true
Parameter Description Type Required
PartnerID The partner identifier assigned by Trimble MAPS.. alphanumeric Y
ExternalAccountID The partner’s existing account identifier for their customer who is deploying CoPilot. alphanumeric Y
AssetID The identifier for the asset to which a license is assigned in the Account Manager. (Often, but not always, a Vehicle ID) alphanumeric Y
ShowConfirmation If set to true, a confirmation message will be shown if CompanyID and AssetID are correctly set. Default is false. boolean N

Identify the Vehicle and Driver

Available in CoPilot 10.19 and Higher

Each instance of CoPilot needs to know which Vehicle or Driver is using it any given time. CoPilot will update its settings according to the configuration in FleetPortal for the vehicle or driver associated with that instance of CoPilot. CoPilot also uses this vehicle and driver identification to populate reports in the various web tools, including add-on RouteReporter compliance reporting and for tagging driver feedback in the MapSure web tool.

copilot://options?type=CONFIG&VehicleID=partner-defined.vehicle.id&DriverID=partner-defined.driver.id
Parameter Description Type
VehicleID The identifier for the vehicle as defined by the partner or direct customer. alphanumeric
DriverID The identifier for the driver as defined by the partner or direct customer. alphanumeric

Set Configurations

Available in CoPilot 10.19 and Higher

CoPilot offers a wide variety of configuration settings that allow you to customize how the app looks and how certain features behave. With URL launch, the same settings can be deployed for each device when rolling out a deployment to multiple users.

URL Format

The format below allows you to pass as many configuration settings as you need, all at once.

copilot://options?type=CONFIG&ConfigName=ConfigValue&ConfigName=ConfigValue

Examples

Single Configuration

copilot://options?type=CONFIG&DownloadDataOnSDCard=true

Multiple Configurations

copilot://options?type=CONFIG&DownloadDataOnSDCard=true&SayWelcome=true&FlowTrafficEnabled=false

Config Names and Values

The Configname parameter can be entered as:

  • The configuration name used in the user.cfg file. (Generic Style)

  • The name used in passing that configuration via our SDK Libraries APIs. (CPIK Style)

  • A combination of both. See a full list of configuration settings.

For example, to enable traffic on a device, you can enter either:

  • &FlowTrafficEnabled=true (Generic Style)

  • &FLOW_TRAFFIC_AVAILABILITY=true (CPIK Style)

The ConfigValue parameter can entered as:

  • True/false, if it is a boolean value.

  • One of the values used in our SDK Libraries APIs.

For example, for that same traffic setting above, you can enter either:

  • &FlowTrafficEnabled=true

  • &FLOW_TRAFFIC_AVAILABILITY=FLOW_TRAFFIC_ENABLED

Confirmation Message

You can add a "show confirmation" parameter to your URL if you would like a message displayed in CoPilot that confirms the settings you passed have been successfully configured.

Examples

//Generic Style
copilot://options?type=CONFIG&FLOW_TRAFFIC_AVAILABILITY=true&ShowConfirmation=true

//CPIK Style
copilot://options?type=CONFIG&FLOW_TRAFFIC_AVAILABILITY=true&SETTINGS_CONFIRMATION_DIALOG=true

Global Restart

Some configuration settings don't take effect until CoPilot has been restarted. You can add a restart parameter to your URL to restart CoPilot after a configuration is set.

//Generic Style
copilot://options?type=CONFIG&FLOW_TRAFFIC_AVAILABILITY=true&RestartCoPilot=true

//CPIK Style
copilot://options?type=CONFIG&FLOW_TRAFFIC_AVAILABILITY=true&RESTART_COPILOT=true

Return to Previous App Button

Available in CoPilot 10.19 and Higher (Android Only)

A button can be added to the CoPilot user interface that allows the user to return to the application from which CoPilot was launched. Two configuration settings are required to add this button.

To enable the button:

  • &EnableCustomButton=1

To set which app should be switched to when pressing the button:

  • &AppLaunchBundleID=bundle.id.of.application
Parameter Description
EnableCustomButton Set to “1” to enable the “return to partner app” button as shown below.
AppLaunchBundleID The bundle ID of the mobile application you wish to return the user to.

Custom Button

Send Stops

Available in CoPilot 10.19 and Higher

URL launch can pass a single stop or multiple stops into CoPilot, all at once, to build a full trip. All successfully geocoded stops are shown in the PLAN screen once CoPilot is launched, and driver just needs to tap the green navigate button to get started on his or her route.

The list of stops passed via URL replace any existing stops in CoPilot. Stop location information can be passed into CoPilot in any of the following ways:

  • As a full address
  • As lat/lon coordinates only
  • As a partial address
  • As an address and a single search string
  • As a single string search only

URL Format

The base URL for entering multiple stops is:

copilot://options?type=STOPS

There are two parameters available to enter stops:

  • stop The stop parameter allows you to enter details about a location as individual "fielded" values—name, address, city, ZIP/postcode, etc. CoPilot will geocode the location using the map data stored on the device before adding it to a route.

  • query The query parameter allows you to enter details about a location as a single string of text, similar to how you query an internet search engine. CoPilot will query our single search web service to geocode the location before adding it to a route. This method requires a reliable internet connection on the device.

Using the Stop Parameter

A stop is entered using the following format:

copilot://options?type=STOPS&stop=name|address1|city1|zip1|juris1|state1|lat1|long1&stop=name|address2|city2|zip2|juris2|state2|lat2|long2

Each field in a stop is segmented with a “|” (Pipe) and an ampersand (&) is used to separate the stops from each other. In addition, you can add a name field for each stop to help differentiate them.

  • If you send a single stop, CoPilot will insert the Current (GPS) Location as the first stop (origin) of the trip on the PLAN screen and the stop you entered via URL as the destination.

  • If you send more than one stop, the Current (GPS) Location will not be added in the PLAN screen until you tap the navigation button to begin the trip.

Note

There is no limit on the number of stops you can pass when sending them in an Android or iOS environment. Some web browsers, however, limit URIs to 2,000 characters.

Stop Fields

Parameter Description Example
name The name of the location Company Headquarters
address The street address of the location 25 Main Street
city The city of the location Omaha
zip The ZIP code or postal code for the location GU16 7HF
juris The jurisdiction of the location. For the U.S., this is the state; for Canada and Mexico, the provinces; and for Australia, the territory. ON
state The state of the location. (State = Country when outside of North America.) GB
lat The latitude of the location, expressed as an integer value in millionth of a degree or a decimal value. 46.813962
long The longitude of the location, expressed as an integer value in millionth of a degree or a decimal value. -71.208012

Stop Examples

There are no required fields when passing a location, although we recommend entering as much information as possible to improve location accuracy.

Full Address

copilot://options?type=STOPS&Stop=City Hall|1400 John F Kennedy Blvd|Philadelphia|19107|PA|PA|39.9527572|-75.1638264&stop=Yankee Stadium|1 E 161 St|The Bronx|10451|NY|NY|40.829611|73.926211

Partial Address

Partial address information can be passed by leaving empty the fields you are not including.

copilot://options?type=STOPS&Stop=Old Office|||WC1A 2RP||GB|||

Lat/Lon Coordinates Only

Coordinates can be sent in a decimal format (ex. 51.518220, -0.122805,) or as long integers (+51518220, -122805). When entering latitude and longitude, “+” is optional however “-“ is mandatory where required.

copilot://options?type=STOPS&Stop=Old Office||||||51.51880|-0.122805&stop=New Office||||||51.51883|-0.122890

Note

When you pass 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, please note they 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. 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.

  • If you pass a UK postcode, optional extras include House Number, Street Name, City Name, Country.

Using the Query Parameter

A single string location query can be sent on its own or in addition to address information.

Search Query Alone

copilot://options?type=STOPS&query=Rogers Centre|1 Blue Jays Way, Toronto, ON M5V 1J1, Canada

Combination Address and Single Search

Combining address information with a single string query can help narrow and improve your results. For example:

copilot://options?type=STOPS&Stop=Old Office|||WC1A 2RP|||GB||&query=Office|29 Bloomsbury Square, London

In the example above, the search engine will only look for a match to "29 Bloomsbury Square" in the "WC1A 2RP" postal code in the country of "GB" (Great Britain).

Similarly, if you add a lat/lon to the search, it will be set as the center of the search area. If a street matching the address you entered is found nearby, the address will be used. If a street match is not found, the lat/long is reverse geocoded and the address portion of the string is returned as the street.

Send a Single Stop

With older versions of CoPilot (below 10.9), URL launch was used only to launch CoPilot, send in a single stop on a route, or view a single location on the map. These features are still available with the latest versions of CoPilot.

A single location is passed via URL 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.

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.

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

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

@ Character

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

Available in CoPilot 10.19.0.1360 and Higher

If a GEO URI includes an address in addition to the GPS coordinates of a stop, the address will be used as the stop name label shown in CoPilot.

Example

geo:0,0?q=123 Main St Seattle@131.6565232,-50.4546454 // "123 Main St" will be used as the stop label

Connect to FleetPortal

Available in CoPilot 10.9.0.1098 and Higher

URL launch can be used to set up a device so it can connect to FleetPortal. FleetPortal is a web tool 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.

Account Manager Users

If you are using URL launch and the Account Manager to assign CoPilot licenses to vehicles or drivers, these FleetPortal settings are applied automatically. After activating a CoPilot license via URL, a second call to the FleetPortal URL (below) 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 AssetID 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.

URL 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: November 12, 2020