HTML Location Map Version 1.0 Implementation Guidelines / Software Development Kit (SDK)

Who should read this document?

This documentation is for developers and webmasters implementing the Multimap HTML Location Map service.

Assumptions

The document explains how to set up and use Multimap's HTML Location Map service and assumes that, as a developer, you:

• have a good working knowledge of HTML; and
• are familiar with the basic features and scope of Multimap’s HTML Location Map service.

You need a Multimap service client account. If you do not yet have one, please contact your Multimap account manager or the Multimap Sales team for your account information, or a free trial account and password.

Scope of document

This document explains how to set up the Multimap HTML Location Map service and covers:

• downloading, uploading and testing the service's HTML template;
• editing the service's HTML template; and
• customizing map images.

This document provides implementation guidelines on how to incorporate Multimap's services into your own website or services. We do not suggest how you design your own web pages.

Copyright

Please note that the maps and data used to provide this service represents copyrighted information, which is owned by our data partners. Do not copy, store, cache, or manipulate in any way any of the maps generated by this service. Any violation of this instruction could result in the cancellation of your service.

Please ensure that every web page that you use to provide a Multimap service for your users maintains a link to Multimap’s Terms and Conditions of Use of map images and data.

Limits on geocoded data

Please note that any geocoding provided by Multimap may be used only as part of a Multimap service. If you wish to use the geocoded information for any application other than a Multimap service, additional charges apply. The fee charged is based on the data used and the number of addresses geocoded. This limitation is necessary because of contractual requirements of our data partners.

Terminology

The HTML Location Map service is generally used to show the location of one or more stores, such as shops, properties, hotels or dealerships on a map. It includes features that let users navigate north, south, east and west (known as panning) and zoom in and out.

Multimap’s HTML Location Map service also provides traffic reports of the number of deliveries of maps this service provides.

Geographic coverage

Multimap provides maps of most of the world, although map coverage varies by country and region. This section lists the countries where our customers typically have stores, for which Multimap provides full or partial support for HTML Location Map customers.

Multimap currently provides street-level mapping and geocoding for over 35 countries. The lists in this section are not exhaustive and are updated continually as new countries are added. Please contact your Multimap account manager if you require the latest update or if you discover that you are not able to search for streets in a country: your account may need to be activated to access that country.

Street-level mapping

Full coverage

Here is a list of countries for which Multimap's HTML Location Map service can offer full street-level map coverage:

Countries indicated with an asterisk (*) in this list are included in Multimap's 'pan-European' coverage option.

Partial coverage

Where street-level maps do not cover an entire country, these are the locations for which street-level maps are available:

Street-level geocoding

Multimap's geocoding is currently accurate to street level in the following countries:

Street-level geocoding - notes

How the HTML Location Map service works

Multimap provides the HTML Location Map service as an HTML template which you can customize to match the appearance of your own website.

To show a map of one or more locations in your Multimap database, geocode your addresses with the Multimap geocoding engine. Your service can then request the map using your unique identifier of each location record. The request is achieved by adding, as a parameter in a URL, client_id, a field in your table of addresses which has a unique value for each record.

Alternatively, you can request a map to show a location by its geographic coordinates; for details, please see the Example map using coordinates.

How Client Zone works

Client Zone acts as a password-protected extranet portal which lets you view and manage your Multimap services. Specifically, Client Zone lets you:

• change the structure of your table of addresses;
• upload, geocode and edit addresses;
• view your service documentation;
• use your own icons, instead of our default red circle and numbers; and
• view your traffic reports.

Preview and live environments

You can test any changes made to your Multimap services in a preview environment before making them live. For an example of this, please see the section on Testing your template.

How geocoding works

To present your stores or assets accurately on a map, Multimap must first geocode your table of addresses. This involves comparing the addresses of your stores with our extensive database of addresses and locations, and generating longitude and latitude values for each store address. We use a GeoQuality code to tell you which elements of your addresses have matched records in our reference databases; for details of these codes, please see Multimap's Client Zone documentation.

Street-level geocoding

The success of geocoding depends on the structure of your table of addresses. The information required for geocoding to street level is street, town, postal code and country.

Countries outside UK with street-level data

Geocoding of addresses in countries can be accurate to building number, or to the segment of the street on which the address is located. Where we are not able to geocode addresses to the street segment, we geocode them to a nominal street midpoint.

Great Britain and Northern Ireland (UK)

First we try to match the full postcode in the pc field against the most up-to-date postcode database. If the postcode is not matched, we use the street and town, if they exist and are in your table of addresses. If building numbers are supplied along with street name, we use the numbers to locate the building as precisely as possible within the correct street segment.

Town-level geocoding

In countries other than those listed in the section on Geographic coverage, we geocode addresses to town level. The fields required for geocoding are town and country.

For example, if you have an address in Nairobi, Kenya, our geocoding tools assign the record the coordinates of the nominal center of that city.

Insert a link to maps on your website using <iframe> or <href> HTML tags.

Example map using a unique record identifier

To request a location from your database in Client Zone, identify that location in an HTTP request by specifying in a URL a database field that identifies that location uniquely.

The default field in your table of addresses for requesting a map is client_id and is reserved for the unique identifying field of each record on your database, such as the unique code of a property, a directory listing, a store, dealer, stockist, hotel or guesthouse. Ensure that you include the parameter f_client_id in an HTML tag.

Please note that this parameter is case-sensitive, so that the value that you supply in your URL must match your template. Additionally, this field must always contain data and should never have a NULL value.

Here is an example of a table used in Client Zone to create coordinates from an address:

To request the map of a specific location, include the unique identifier f_client_id as a parameter in a URL embedded in an <iframe> or <href> tag.

The code to insert your map template in your web page would resemble:

<iframe src="http://classic.multimap.com/clients/browse.cgi?client=[clientname] 
&amp;f_client_id=331578"> </iframe>

If you have subscribed to the Secure version of the service, replace http in the code with https:

<iframe src="https://classic.multimap.com/clients/browse.cgi?client=[clientname] 
&amp;f_client_id=331578"> </iframe>

Example map using coordinates

If you know the coordinates for your location, the code to show a map on your template would resemble:

<iframe src="http://classic.multimap.com/clients/browse.cgi?client=[clientname] 
&amp;lon=2.3552&amp;lat=48.8606&amp;icon=x"> </iframe>

The icon parameter determines where to place the icon that marks a location on a map that has been supplied via coordinates. Please see the section on Customizing your images for details of how to change the default red circle, and also the full List of Parameters.

Longitude and latitude coordinates need to be stated as decimal degrees (not degrees, minutes and seconds). Please note that longitudes east of the Greenwich Meridian have negative values, as do latitudes south of the Equator, for example:

Notes on the examples

The src attribute (or <href> tag, if applicable) contains a URL that determines where the web page should look for the map image. It is made up of two parts:

• http://classic.multimap.com/clients/browse.cgi
  specifies the location of our mapping software. You should not change this.
• ?client=[clientname]&lat=48.8606&lon=2.3552 and
  ?client=[clientname]&f_client_id=1234
  are query strings containing name=value pairs that tell the software what your service client name is and which location you are looking for. The name=value pairs are separated by &. This is the HTML way of specifying an ampersand (&) character and must be written in this way to ensure that your HTML is valid.

Please note that you should always supply the parameter &icon=x if you wish to show the Multimap default red circle on your map.

To use a different icon, please see the section on Customizing your images.

Here are some more examples, showing URLs in <href> tags:

• A street-level map of a location in Lyon, France:
  
  <a href="http://classic.multimap.com/clients/browse.cgi?client=[clientname]
&amp;lon=4.8342&amp;lat=45.7679&amp;scale=5000&amp;icon=x"></a>
• A city-level map of Canberra, Australia:
  
  <a href="http://classic.multimap.com/clients/browse.cgi?client=[clientname]
&amp;lon=149.0414&amp;lat=-35.3514&amp;scale=100000&amp;icon=x"></a>
• A national map of Switzerland, specifying the map’s size:
  
  <a href="http://classic.multimap.com/clients/browse.cgi?client=[clientname]
&amp;lat=46.625&amp;lon=8.0848&amp;width=200&amp;height=200
&amp;scale=10000000&amp;icon=x"></a>

Please see the List of Parameters for a full description of all the HTML Location Map service’s URL parameters and their explanations.

Showing multiple locations

If you would like to show more than one location on your map, supply a URL that contains a list of either client_id fields or coordinates. The map scales itself automatically to show all your locations; if you wish to specify a scale, use the optional scale parameter.

If a map shows multiple locations, your users can click on any of those icons to display a new map centered on that location at a scale of 1:10,000. Users can also use the controls on the template to pan north, south, east or west or to zoom in and out.

Showing multiple locations on a map using f_client_id

To display multiple geocoded locations on a map, concatenate the client_id fields of the records you wish to show in a comma-separated list:

<a href="http://classic.multimap.com/clients/browse.cgi?client=[clientname] 
&amp;f_client_id=01,02,03,04"></a>

Showing multiple locations on a map using coordinates

Show multiple locations on a single map by concatenating all coordinates in the lllist parameter. This parameter supplies coordinates in a list of longitude and latitude pairs:

• Passing coordinates for a set of locations in Denmark:
  
  <a href="http://classic.multimap.com/clients/browse.cgi?client=[clientname]
&amp;lllist=11.8618,55.9461,12.6167,56.0392,12.5989, 55.6927"></a>

Please note, however, that using the lllist parameter method to show more than a few locations is inefficient and may affect the performance of your service. If you wish to show many locations on maps on a regular basis, we recommend that you use the f_client_id parameter method.

This section describes how to integrate the Multimap HTML Location Map service in your own website and customize its appearance:

• Customizing your template; and
• Customizing your images.

For details of how to set up the data for your HTML Location Map service, please see Multimap's Client Zone documentation.

Logging in to Client Zone

To log in to Multimap’s Client Zone, use the username and password given to you by your Multimap account manager:

https://cz.multimap.com

1. From the login page, enter the username and password of your company. This takes you to the Select a service to manage page.
2. From the Select a service to manage page, select your HTML Location Map service.

Customizing your template

The Multimap HTML Location Map service uses an HTML template called browse.htm to show a map of the location(s) that you have specified. Please see the Example map using a unique record identifier and the Example map using coordinates for examples of this template.

There are four steps to managing your template:

1. Downloading
2. Editing
3. Uploading
4. Testing

Downloading your template

To download a template:

1. Go to the Management Menu page of Client Zone.
2. Click on the Download Files link.
3. Find the links to the browse.htm template.
4. Click on the template's Download button to copy it to your computer.
5. Make a back-up copy of your template (recommended).
6. When you have finished downloading, click on the Back to Menu button to return to the Management Menu page.

Editing your template

When you have downloaded a copy of your template to your own computer, you are free to edit it to your own specification using any text HTML editing tool. You can also use WYSIWYG editors, although you should ensure that any additional HTML code you create through these programs does not interfere with the operation of your Multimap templates.

Please note that you must not change the name of your template.

Place holders

To change the appearance of your template, you can edit any of the underlying HTML code.

However, you must leave all the place holders intact. Place holders take the form <%place holder%>. Examples of place holders include:

When your HTML Location Map service is live, place holders are replaced with HTML code or data generated by Multimap’s software.

Uploading your template

To upload a template:

1. Go to the Management Menu page of Client Zone.
2. Click on the Upload File link.
3. Browse or type the target template's path and filename.
4. Enter a reason for your upload in the Comment field. (This is mandatory.)
5. Click on the Upload button to upload your file to your preview environment and proceed to the Copy review templates to live page.
6. Click on the Copy button to copy your file to your live environment.
7. When you have finished uploading, click on the Back to Menu button to return to the Management Menu page.

Testing your template

To view any changes you make to your template in your preview environment, copy the following address into your browser, replacing [clientname] with your own HTML Location Map service client name:

http://preview.multimap.com/clients/browse.cgi?client=[clientname]
&lat=51.5184&lon=-0.111&icon=x

To view the active data in your live environment, use the URL:

http://classic.multimap.com/clients/browse.cgi?client=[clientname]
&lat=51.5184&lon=-0.111&icon=x

Please note that, when you deploy your template to your live environment for the first time, there may be a short delay before it becomes visible at this location.

Requesting alternative templates

A request to browse.cgi loads the browse.htm template by default. To create printer-friendly pages that print the map or route to a store, you can request alternative templates that contain only the details you wish to show and upload these alternative templates via Client Zone. To request the templates, pass an rt (return template) parameter in the query component of the HTTP request.

Here is a standard request to browse.cgi which loads browse.htm:

http://classic.multimap.com/clients/browse.cgi?client=[clientname]
&lat=51.5184&lon=-0.111

This is a request to browse.cgi including the rt parameter, which loads alternate.htm:

http://classic.multimap.com/clients/browse.cgi?client=[clientname]
&lat=51.5184&lon=-0.111&rt=alternate.htm

You can use this method to render templates you are testing or to preview or print additional templates.

Customizing your images

You can deactivate all the icons that Multimap displays by default and replace them with dynamic icons. These icons can carry 'mouse-over' attributes and 'click-through' actions.

Customizing the default red circle for single locations

The following style sheet can be found within the <HEAD> section of your browse.htm template; this code is used to control the look of the red circle that shows a single location on a map:

<style type="text/css"> 
#mapLayer { 
position: relative;width: <%map.width%>px; 
height: <%map.imheight%>px; 
} 

.posiMarker { 
position: absolute; width: 32px; height: 32px; border: 0; 
} 
</style>

The corresponding HTML code in the body of the template is as follows:

<div class="posiMarker" style="left: <%xpix.sub(16)%>px; 
top: <%ypix.sub(16)%>px; visibility: <%pix_visible%>;"> 

<a href="browse.cgi?client=<%map.client%> 
&amp;f_client_id=<%form.f_client_id%> 
&amp;lat=<%lat%>&amp;lon=<%lon%>&amp;scale=5000 
&amp;width=<%map.width%>&amp;height=<%map.height%>" 
title="<%name%>"><img src="/images/X.gif" alt="X" /></a> </div>

The style attribute of this element contains the position and visibility of the icon. Please note that the sub(16) template tag modifiers, which are used to center the icon over the location, should be equal to half the width and half the height of your icon respectively.

To replace the red circle with an image of your own, edit the <img> tag to point to an icon on your own server:

<img src="http://www.myserver.com/my_icon.gif" alt="marker" /> 

The anchor tag surrounding this image makes the icon clickable and causes the map to center and zoom in to a street-level map of this location by default.

Customizing icons for multiple locations

The following style sheet can be found within the <HEAD> section of your browse.htm template; this code is used to control the appearance of the numbered icons that show multiple locations on a map.

<style type="text/css"> 
#mapLayer { 
position: relative; 
width: <%map.width%>px; height: <%map.imheight%>px; 
} 

.posiLayer { 
position: absolute; border: solid 1px #000; background-color: #fff; 
color: #000; width: 13px; height: 13px; text-align: center; 
} 
</style>

This is used in conjunction with the following HTML code:

<div class="posiLayer" style="left: <%xpix.sub(6)%>px; top: 
<%ypix.sub(6)%>px; visibility: <%pix_visible%>;"> 
<a href="browse.cgi?client=<%map.client%> 
&amp;f_client_id=<%form.f_client_id%> 
&amp;lat=<%lat%>&amp;lon=<%lon%>&amp;scale=5000 
&amp;width=<%map.width%>&amp;height=<%map.height%>" 
title="<%name%>"><%CurrentRecord%></a> 
</div>

The <%CurrentRecord%> tag is a place holder for a server-side variable which is a numerical identifier for each result, such as 1, 2 or 3.

The first result from the data table has a <%CurrentRecord%> value of 1; this value can be used to retrieve a corresponding icon:

<img src="http://www.myserver.com/icon_1.gif" width="15" height="15" 
alt="Icon <%CurrentRecord%>" /> 

Please note the anchor tags wrapped around the image. You can associate a static HTTP request with every icon or you can obtain a dynamic value from your table of addresses.

For example, if your table contained a field called "website", you could write the div element like this:

<div class="posiLayer" style="left: <%xpix.sub(7)%>px; top: 
<%ypix.sub(7)%>px; visibility: <%pix_visible%>;"> 
<a href="<%website.escape(html)%>"> 
<img src="http://www.yourserver.com/icon_<%CurrentRecord%>.gif" 
width="15" height="15" alt="<%website%>" /></a> </div>

The escape(html) modifier on the <%website%> dynamic tag ensures that the URL is in the correct format for a HTML page.

If you require more information on how to implement dynamic map icons, please contact the Multimap Customer Support team.

Using field values to display images

Field values can be used to display specific images within the browse.htm template. For example, a table of addresses may contain a field called carpark. This field may contain either "no" or "yes".

In the browse.htm template, each record is displayed in the results section, between the <%begindetail%> and <%enddetail%> tags.

To use the field value, add an <img> tag with the same name as the field in your table of addresses:

<img src=http://www.[myserver].com/images/parking_<%carpark%>.gif> 

The <%carpark%> tag is rendered as a "no" or a "yes" value, so either one of the following images is selected for each record:

• http://www.[myserver].com/images/parking_no.gif; or
• http://www.[myserver].com/images/parking_yes.gif.

When a user searches for a store that has a car park, the appropriate image is displayed. No image is displayed for stores that are not marked as either having or not having a car park.

To prevent a blank image marker being displayed, you can either ensure "yes" or "no" is entered in your table of addresses for every record, or you can add the appropriate code to hide the default blank image marker or show a blank field where no value exists in the carpark field.

Multiple markers

If your map shows more than one store, outlet or attraction, you can mark each one with its own image.

The GIF file only replaces the red circle, which indicates the position of the first result, so all remaining results are still shown as small yellow boxes.

To replace the default images for maps showing multiple locations, create each image you require as a GIF file and upload it via the Management Menu page of Client Zone.

To specify a series of icons for an ordered list of locations, use the gif_array parameter. You can re-use the same GIF image repeatedly or use a separate image for each location:

• Using f_client_id identifiers to show several castles in Wales, using the same image for each location:
  
  <a href="http://classic.multimap.com/clients/browse.cgi?client=[clientname]
&amp;scale=500000
&amp;f_client_id=castle_01,castle_02,castle_03
&amp;gif_array=my_icon,my_icon,my_icon"></a>
• Using lon and lat coordinates for the same locations, using a distinct image for each:
  
  <a href="http://classic.multimap.com/clients/browse.cgi?client=[clientname]
  &scale=500000
&lllist=-3.8272,53.2795,-4.0899,53.2645,-4.2782,53.1388
&amp;gif_array=my_icon01,my_icon02,my_icon03"></a>

Why can't I host my templates on my own web server?

By locating the templates on Multimap servers, we can serve web pages to your users more rapidly and in larger volumes than would otherwise be the case.

Why is my marker in the wrong place?

Your icon (the Multimap red circle, by default) seldom appears exactly in the middle of a map. It is more noticeable with small-sized large-scale maps. This is why the icon sometimes looks off-center on very small maps.

To improve the appearance of the icon on your map, try enlarging your map with the width and height parameters, or use the scale parameter to specify a smaller scale. For the full range of map scales that are available, please see Multimap’s online List of Map Scales.

In Great Britain, for example, postcodes may cover a wide area, especially in rural areas where they may cover an area half a mile across. The icon is normally placed in the center of this area of the map.

Geocoding of addresses in some European countries can be accurate to the segment of the street on which an address is located. In certain areas we may not be able to geocode to the street segment because our underlying data is incomplete, in which case we geocode to a nominal street midpoint.

Further Help

If you require further help with your Multimap service implementation, additional Multimap services or general account enquiries, please contact Multimap: