CoPilot Navigation

Places and Custom Places

Contents

What is a Place?

Places are preset public locations within the map database, for instance airports, truck stops and restaurants. Places can be searched by name, without having to know exact addresses. They also contain more accurate location as all Places include a latitude/longitude.

CoPilot contains a large number of default Places sorted by category, including fuel stations, restaurants, airports, train stations, etc. Places can be searched from the standard Destination entry screen, with the search location based on either ‘On Route’, ‘Nearby’ or ‘Other City’.

Search Online

CoPilot can also Search Online via Yelp. There is no additional cost but it requires a data connection which may incur charges from your network provider. These can be useful for drivers to find Places that may not be within the standard map dataset. The major advantage of this is the frequency of updates, as this is using the Yelp search engine.

If you want to remove driver access to Search Online see UI Customization.

Displaying Places

All Places categories have a display icon which can be shown on the map to inform drivers of relevant Places. It is possible to configure which Place categories your drivers will find relevant to display on screen and hide other categories. To configure Places within CoPilot, navigate to Settings > Map Display & Guidance > Show Places on Map. On this screen, you can:

  • Select when Places will be displayed during navigation. By default the option is set to When Stopped.
  • Select which categories of Places you’d like to see on the map. Currently Displayed Places will show all categories available (including Custom Places). You can check or uncheck those you’d like to see.

Can CoPilot Places Categories be removed?

Unfortunately it is not possible to remove / rename individual categories from within the core Places delivered with CoPilot. It is possible to remove access to the Places search see UI Customization.

Custom Places within CoPilot

Custom Places are specific public locations important to your business—for instance Store Locations or Supplier Locations etc.

It is possible to import custom Places into CoPilot, these will be available for drivers to search and view. Custom POI’s can be added to a new category including a dedicated icon.

Custom Places are imported into CoPilot. The method for integrating these can be:

  1. Via API CPIK libraries - CopilotMgr.integrateCustomPOIs or SDK App - Msg_ImportPOISet
  2. ContentTools
  3. CoPilot POI Wizard
  4. XML POI Integration
  5. POI Desktop Integration Tool

Custom Places Input File Requirements

The .csv input file

The application supports integration for .csv / .ezp / .ov2 – further reference will only state .csv. In order to create the .csv file please open MS Excel and enter the following headings in separate columns:

  • Name - Required. Refers to the individual name for the Place
  • Street - Optional. Refers to the street address where the Place is located
  • Postal - Optional. Refers to the Postcode where the Place is located
  • City - Optional. Refers to the City where the Place is located
  • County - Optional. Refers to the County where the Place is located
  • State - Optional. Refers to the State or Country where the Place is located
  • Longitude - Required.
  • Latitude - Required
  • Phone - Optional. Refers to the Place Phone number, will be used to hyperlink to the device phone application if set up.

Please do not use any comma (“,”) in any of the cells as this character is used to delimit the columns and will cause errors during the integration.

Once the data has been created, save the file as “.CSV” (Comma delimited file). For best practice it is recommended to name the .CSV file to match the category name. CoPilot has a maximum 25 character length for custom Place category names, the actual Place location name can be longer but in most views these will be truncated to 25.

Places categories are displayed in alphabetical order, if you wish for this category to appear at the top of the Places list, insert a space at the beginning of the name. This will be removed from sight but will ensure the custom Places are top of the standard category list.

The Custom Place Icon

  1. CoPilot supports the following image files: .png / .jpg / .bmp.
  2. Creating your own icon. Icons can be created in Adobe Illustrator, Photoshop or any design application that allows for the file saving to be 24-bit transparent. The sample image is 44x44, but they can be different in size, CoPilot will size your icon appropriately to fit. Note if the custom icon is rectangular, CoPilot will reshape the icon to a square.
  3. Please ensure that you save the image with the same name as the .csv

Note: SVG format is not supported in CoPilot as we create images in pixels as appose to shapes and curves (used for SVG).

Custom Place Folder Locations

All future locations referenced in this document will be labelled as ‘Save Folder’ and ‘UI Folder’. Save Folder = Location of ‘Save’ folder within the Maps Directory. UI Folder = Location of ‘Skin’ folder within the CoPilot Installation Directory.

The below shows the default locations of the folder paths for each platform, if you have installed or created custom locations for your installation these will be referenced in CoPilot’s user.cfg in the [Directories] section for “LRSaveDir” and “SkinDir”.

Windows 10

Save Folder = Program Data/Alk Technologies /CoPilot/[Region code]/save
UI Folder = Program Files(x86)/Alk Technologies/ CoPilot/Skin

Android

Save Folder = com.alk.copilot/[Region code]/save
UI Folder = com.alk.copilot/CoPilot/Skin

Note: Enterprise Licensed builds may include the enterprise name within the installation name

Import Methods

ContentTools

ContentTools is a web tool where you can create, manage and share custom location and routing content. Using Account Manager, this content can be share with CoPilot for use in navigation.

If you are interested in ContentTools please speak to your account manager. Learn more about ContentTools.

If you have a ContentTools account, log in here.

CoPilot Places Wizard at Launch

This method is rarely used in Enterprise deployments, as it relies on the user to manually select the appropriate categories after launch.

The .CSV and Places Icon need to be added directly into CoPilot folders prior to launch.

  1. .CSV to be added to Save Folder
  2. Places Icon to be added to the Skin Folder

At launch, CoPilot will identify new raw files and begin the Places wizard, taking the user through a few steps before converting the raw files into CoPilot proprietary format. Once launched, users will be able to search and use the Places in exactly the same way as all standard CoPilot Places.

CoPilot APIs

Available in CoPilot 10.9 and Later

This method uses existing APIs whereby passing a JSON file into CoPilot will load the custom Places set. Please note the JSON format can be found within the API details. For further information on the APIs please see the respective sample applications and further information via the links below:

SDK App: Msg_IntegrateCustomPOI
CPIK Libraries: CopilotMgr.integrateCustomPOI

XML Places Integration Process

Utilizing an XML file, loaded along with the CSV and image file can automate the integration process, bypassing the manual Places Wizard, please allow additional time for first launch. The contents of the XML will define to CoPilot how to integrate the .CSV and Places Icon. Processing of Places files will only take place on startup of CoPilot, please ensure you exit CoPilot and restart to validate the changes.

The .CSV and Places Icon need to be added directly into CoPilot folders prior to launch.

  1. .XML file to be added to Save Folder
  2. .CSV to be added to Save Folder
  3. Places Icon to be added to the Skin Folder

Note: The name of the XML file should be exactly the same as the .CSV
Each individual Place Category requires an individual XML and .CSV

Creating XML Places File

  1. Create the .CSV as described in Creating the Input File file with the custom Places and name it. If you have more than one csv file of Places, make sure that you give it a different name than any other csv files being used
  2. Create the .XML file with the necessary information, an example is provided below, details are provided for each of the fields: 
<poi_set_configuration name="my new Places set" use_existing_type="Italian" deleteSet="0" >
  <type name="my type" image="my_type_image" OR builtin_image="other">
    parent="safety camera"
    safetycam="0"
    display_on_map="1"
    searchable="1"
    alertable="1"
    max_zoom_level="6"
    importance="18"
  </type>
</poi_set_configuration>

  • poi_set_configuration - Required

  • name - Optional. Defines the Category Name. If not specified will utilize the CSV’s name

  • use_existing_type - Required, unless type is defined. This can only match an existing Sub-Category for instance Italian is OK, but Restaurants is not.

  • deleteSet - Optional. Default is 0, set this to 1 if you want to delete the set instead of integrating a new set

  • type – Optional but is required if use_existing_type has not been provided.

  • name - Required. Refers to the Category Name

  • image or builtin_image – Required. Defines the Places Icon to be displayed relating to this category. The image needs to be copied into the region/save folder. builtin_image should be used if you wish to use the CoPilot default image for the custom Places, this should be set to “other”.

  • parent - Optional – Use this if you want this set to be a sub-category. If not specified, type will be top-level. Can be in either English or current CP language

  • safetycam - Optional – default: 1. This should be set to 0 unless this set of safety cameras that includes warning alerts.

  • display_on_map - Optional – default: 1. This should be set to 1 if these Places are to be drawn on the map

  • searchable - Optional – default: 1. This should be set to 1 for the Places to appear in the Places searches

  • alertable – Optional – default: 1. Places Alerts be set on this type when set to 1

  • max_zoom_level - Optional – default: 6 (range: 0-7) larger numbers allow the type to be drawn while map is zoomed out further

  • importance - Optional – default: 18 (range: 0-255). Smaller numbers make the type more important, thus more likely to be drawn when Places are clustered]

  1. Name the XML file with the same name as the CSV that it is paired with
  • If this is an updated set of Places, you still need to name the CSV file the same as it was before
  • The name of the XML must match the name of the CSV
  1. Copy both of these files into the region/save directory in your CoPilot root folder. If you do not include the XML file, you will be sent to the manual integration wizard when starting CoPilot
  2. If you are using a custom image, then you must have a .bmp file of the image that you want to use. This file should be copied into the region/save folder and the filename must match with the “image” parameter in the XML file.
  3. If you are integrating more than one Places set, then repeat steps 1-5 for the rest of your set using different named files for each set
  4. Start CoPilot and the Places will be integrated

Updating and adding new sets

If you would like to update an existing set, you will need to add the new CSV file into the region/save directory. It should have the same name as the XML file, which should still be in the region/save folder. Ensure that the XML file and .bmp file for this set is present in the region/save as well. If you need to add more categories after the initial setup, you can repeat the process with new csv/xml/bmp files and when you start CoPilot again, it will integrate the new sets for you. Make sure that you give the new files unique names.

Removing a custom set

If you need to remove a set that you have already added, edit the XML file for that set to include the “deleteSet” config to =1. Further details on this config can be found as option d above.

Please ensure csv file with the same name containing at least one Place and your new xml file are saved to region/save. Once you have confirmed everything is in the correct folder location when CoPilot is launched it should remove the custom category from the Places menu and remove all of the Places that used to be in that category.

Places Desktop Integration Tool

The desktop Places tool should only really be used if the number of custom Places reaches a level above 10,000 to be integrated as this can slow the first launch significantly. This tool is a small script that can be used in the back office to convert Places from .CSV to the proprietary CoPilot format. Once created the converted files will need to distributed to CoPilot folders, at next launch the user will be able to search or display the Places as required.

Download the tool

Steps to create Places via desktop application:

Note: Please use appropriate Places integrator tool depending on the version of CoPilot you are using.

  1. Create the .CSV and Places Icon as directed earlier on this page.
  2. Download and add the Places desktop application to your required directory e.g. C:\poi_integrator\
  3. CoPilot map data is made up of a series of grids, new Places are added to the grid corresponding to the location and therefore it is essential for the Places desktop tool to allocate the correct grid to the Places being converted. Incorrect grid allocation is likely to result in the Places not being correctly searchable after completion
  4. To ensure the Places files are converted correctly you will need to add a few files from the CoPilot map data being used on the device to the Places tool.
  5. From your Data folder copy the following three files: a. 00000000.hsh, b. 00000000.qd, c. version.dat The Data folder is found on the same folder structure level as the Save Folder
  6. Copy the three files to C:\poi_integrator\data
  7. Place the input files into C:\poi_integrator\save.
  8. If you require multiple customer Places categories it is essential you process all the Places categories at the same time, as a unique ID will be assigned to each category. Creating Places separately will cause issues as the ID will no longer be unique.
  9. Run POI_integrator.bat
  10. The completed integrated Places files will appear C:\poi_integrator\output, please see notes below on where output files should be saved within programme files. a. Save folder within ‘User Places’ b. UI folder within ‘User’
  11. See section on Sharing Custom Places with other CoPilot users for adding the Places into CoPilot Note: Once the output file has been created, folders need to be saved within the programme files.
  12. Within output > save > user_places the folder “Integrated POIs” should be copied and saved within EU > save > user_places. If the user_places folder is not present within the “save” folder, a new folder should be created with the name “user_places”.
  13. Within output > skin_v9 the folder “User” should be copied and saved within the folder “Skin”
  14. Within output > skin_v9 the folder “User” should be copied into the following location Library > Application Support > com.alk.copilot.

Please note the Places Integrator will create 3 types of Places Icons, a general icon, as well as a 3D and 2D strip. The 2D and 3D icons are done in a strip so they scale up/down depending on the map zoom level.

Maximum number of Places

CoPilot does not have a limit on the number of Places that can be stored on a device or for the searching database, by this we mean the number of Places CoPilot will search in order to find the drivers destination. For example the European map data contains more than 12 million Places. There can be an issue with the map drawing if there are too many Places held on CoPilot. Too many on screen floods the screen to stop the user from viewing the roads but also has a CPU/frame rate drawing impact too as all Places need to be drawn in real-time.

Last updated July 2, 2024.
Contents