How to Import Markers

This tutorial will guide you through all the steps required to prepare data and to import it into a Click2Map map. Importing new markers and updating them when necessary is a simple process that however requires some attention.

We'll base this tutorial on a simple example: a list of homes and condos in the San Diego area that we'd like to locate on a map to provide potential buyers with an easy geographical overview and a simple description of each property. We'd of course like to provide them with a link to our website and our contact e-mail address in case they need additional information.

Click2Map is able to import data from external files, provided they are in a compatible format. The main import format is the CSV format: CSV is the acronym for Comma Separated Values which is a standard text file format used to exchange data between different applications. CSV files are easy to edit in standard spreadsheet applications such as MS Excel, OpenOffice or Google Spreadsheet.

CSV files are text files that can be opened in almost any text editor such as Notepad, SimpleText… They however differ from standard text files in that they are used to store organized data and have a specific structure:

• The first line provides the general structure of the file.
• A specific character is used to separate different elements. This character can be a comma, a semicolon or tabulation. The standard American delimiter is the comma, for example.

The first line of a Click2Map CSV file contains the following elements:

Name,Title,Latitude,Longitude,Description,Address,Street,City,State,Zip,Country, Icon_uri,IconSizeW,IconSizeH,Url_text,Url,Email_text,Email,Group

This first line is not as abstract as it may seem: it is a list of all the information that can be associated with each marker on a map. The order in which elements are organized is not important; you should just make sure that the same order used in the first line is also used for all markers. The first line describing the structure of you data (Name, Title, etc.) is not necessary if you use the structure described above: Click2Map will automatically associate matching columns. If this is not the case, you'll have the possiblity to manually make associations during the import process.

Note: All elements are not mandatory: some can be ignored, in which case Click2Map will consider them to be empty or fill them with default values.

• Name: The name of each marker should be unique. It is the primary information used to identify a specific marker. You can use this field to store a name in clear or a unique identification number.
• Title: The title field can be used to provide information about a marker. Titles do not have to be unique and can be used to create categories, for example.
• Description: This field can be used to associate a longer description with a marker. This field can contain HTML content.
• Address: This field is designed to contain full street addresses: if your addresses are made of separate street, zip code and city fields, use the appropriate fields described below. Any street address entered in this field is automatically geocoded during the import process. This means that you do not need to know the geographical coordinates of a place to locate it on a map: Click2Map does the conversion for you. This is a great feature for real estate agents!
• Street: This field can contain the number, type and name of a location in street address form, for example: “1428 Elm Street”. It needs to be associated with the other address fields (City, State, Zip, Country) if you want Click2Map to be able to geocode its content. If your addresses are not split into different columns, your can put them in full in the Address field; in this case, leave the present field empty.
• City: This field contains the name of the city in which the Street is located. It needs to be associated with the other address fields (City, State, Zip, Country) if you want Click2Map to be able to geocode its content. If your addresses are not split into different columns, your can put them in full in the Address field; in this case, leave the present field empty.
• State: This field contains the name of the state in which the Street is located. It needs to be associated with the other address fields (City, State, Zip, Country) if you want Click2Map to be able to geocode its content. If your addresses are not split into different columns, your can put them in full in the Address field; in this case, leave the present field empty.
• ZIP: This field contains the ZIP code corresponding to the specified Street. It needs to be associated with the other address fields (City, State, Zip, Country) if you want Click2Map to be able to geocode its content. If your addresses are not split into different columns, your can put them in full in the Address field; in this case, leave the present field empty.
• Country: This field contains the name of the country in which the Street is located. It needs to be associated with the other address fields (City, State, Zip, Country) if you want Click2Map to be able to geocode its content. If your addresses are not split into different columns, your can put them in full in the Address field; in this case, leave the present field empty.
• Latitude: If you know the geographical coordinates of a place, use this field to enter its latitude.
• Longitude: If you know the geographical coordinates of a place, use this field to enter its longitude.

• Url_text: If you wish to provide your visitors with a direct link to your website, use this field to store the visible hyperlink text. For example: 'Click2Map Website'. If this field is left empty, any link stored in the following Url field will appear in its original form.
• Url: Use this field to store the desired Internet web address. For example: 'http://www.click2map.com'.

• Email_text: If you wish to provide your visitors with a contact e-mail link, use this field to store the visible e-mail text. For example: 'Contact us'. If this field is left empty, any e-mail link stored in the following Email field will appear in its original form.
• Email: Use this field to store the desired e-mail address. For example: 'info@click2map.com'.

• Group: This field contains a marker's group/subgroup information. If this field is left empty, the corresponding marker will be placed at the root of the target map. If you wish to place a marker in a specific group, simply enter the corresponding group name in the 'Groupname' form. Groups can also contain subgroups: to place a marker in a specific subgroup, simply enter the corresponding subgroup name in the 'Groupname/Subgroupname' form.

• Icon_uri: The complete Internet address of the icon associated with a marker. For example: http://editor.click2map.com/files/3077/icons/icon10.png. If this field is left blank, the target map's default icon will be used. See also: list of the standard Click2Map icons
• IconSizeW: Width of a marker's icon in pixels. Do not fill in this field unless you wish to deform the original image. When this field is left empty, Click2Map automatically resizes the image to the correct size, preserving its width/height ratio.
• IconSizeH: Height of a marker's icon in pixels. Do not fill in this field unless you wish to deform the original image. When this field is left empty, Click2Map automatically resizes the image to the correct size, preserving its width/height ratio.

The first step will be to organize the property information we already possess and see how it would fit in the Click2Map CSV structure. The following elements are available for each home:

• Type: All our properties belong to one of these types: Single-Family Home, Multi-Family Home, Condominium or Townhouse. We have several properties matching each type, so we know the Type can't be used in the Name field, because it has to be unique. We'll then put the Type information in the Type field.
• Reference: The reference corresponds to the agency's internal reference number. This unique reference will be used to identify each marker. We'll save it in the Name field because it fits the unique ID criteria.
• Address: This field will be used to store each property's full address.
• Title: Each property for sale already has a title that we'll store in the Title field.
• Description: The description of each property will nicely fit in the Description field.

Now that we know how to organize our data, it's time to create the file that will contain it. It is of course possible to create a blank text file and start entering data in it. Spreadsheet applications make editing data much easier: we'll then use MS Excel or any other spreadsheet program to create a new file and enter the information about our properties.

1. Start your spreadsheet application, create a new blank file and save it in your application's standard file format.
2. On the first line, enter the following in the first five horizontal cells: Type, Reference, Address, Title, Description
   • Type: The Type column will be used to sort properties according to their nature: condo, townhouse, single-family home, etc.
   • Reference: The Reference column corresponds to the Name field and must contain unique names or IDs. We'll use imaginary references here.
   • Address: The Address column will be used to store the full postal address of each property.
   • Title: We'll use the Title column to briefly describe each property.
   • Description: The Description column will be used to store each property's full description
3. Save the file in your application's standard file format.

To retrieve the content of the sample file in CSV format (semi-colon delimited), click here.

Note: At this stage, you already have enough information in your CSV file to perform a first import. If you wish to start importing your data immediately, you can jump to Step 4: Saving the CSV file.

If you would like to create richer markers, with additional information, Internet and E-mail links, please read on.

The five columns created in the preceding sections of this tutorial contain the main elements necessary to locate and describe markers on a map. Click2Map allows you to add more optional information to offer your visitors ways to visit your website or contact you via e-mail. To do so, we simply need to add a few columns and enter some more information:

1. If you had closed it, reopen the spreadsheet file you created in Step 2. To retrieve the content of the sample file in CSV format (semi-colon delimited), click here.
2. On the first line, enter the following in the next four blank horizontal cells: Url_text, Url, Email_text, Email.
   • Url_text: In the Url_text column, enter the text that should be used as the visible hyperlink text: when your visitors click on this text, they'll be directed to the Internet address specified in the Url column.
   • Url: In the Url column, enter the full Internet address to which your visitors should be directed when they click on the hyperlink defined in the Url_text column.
   • Email_text: In the Email_text column, enter the text that should be used as the visible e-mail hyperlink text: when your visitors click on this text, a new message will be created in their e-mail client. The To: field will contain the e-mail address specified in the Email column.
   • Email: In the Email column, enter the e-mail address to which your visitors' messages should be sent when they click on the hyperlink defined in the Email_text column.
3. Save the file in your application's standard file format.

To retrieve the content of the sample file in CSV format (semi-colon delimited), click here.

For easier editing, we've chosen to prepare our data in a spreadsheet application like MS Excel, OpenOffice or Google Spreadsheet using our application's default file format. To be able to import our data, we need to save it in a format that Click2Map understands: the CSV format.

1. To start exporting your data, use your spreadsheet application's File > Save as… or Export command and select the CSV (*.csv) file format as the target format. Please note the type of separator (comma, semicolon or tab) used by your application during the process: this information will be necessary when you import the file in Click2Map.
2. Follow the steps described in the following section.

CSV files include marker, group and subgroup information, but no map information: you should always select or create the correct target map in the Map Explorer before importing markers from a file.

When the target map is selected, use the Tools > Import… command from the main menu and follow the Import Wizard steps.

The CSV file created in this tutorial includes each property's complete street address. The process of converting a street address into the corresponding geographical coordinates is called geocoding. During the import process, the list of all the addresses that couldn't be geocoded is displayed to allow you to modify each address. Most of the time, addresses can't be geocoded because they contain too much information: simplify these addresses and try again.

You can alternatively left-click on a marker and drag it in any direction to fine tune its positioning or move it to the correct location in case of a failed geocoding.