Multimap Client Zone V2.2 : Documentation - Introduction to Client Zone

This page provides an introduction to Client Zone, Multimap's password-protected extranet portal.

Who should read this documentation?

This documentation is for programmers, developers, webmasters, project managers and other IT personnel who are implementing any Multimap service that involves the upload and management of address data. These may include:

Multimap API;
In-line with Geocoding;
HTML Location Map;
XML Location Map;
HTML Storefinder; and
XML Storefinder.

Assumptions

The document assumes that you:

are familiar with the basic features and scope of your Multimap service(s); and
have 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; please see the foot of this web page for contact details.

Scope of documentation

This document covers uploading, geocoding and testing address data using Client Zone.

For details of how to incorporate the Multimap API into your own website, please see the Multimap API Implementation Guidelines documentation.

For details of how to incorporate other Multimap services into your own website, please see the Implementation Guidelines documentation that has been provided by your Multimap account manager.

Copyright

Please note that the maps and data used to provide Multimap services represent 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 Multimap services. 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.

A special case – People's Republic of China

If you have a Multimap service that includes records for stores located in the People's Republic of China (PRC) that have been geocoded to street level, legal restrictions mean that Multimap cannot expose those stores' coordinates either to you or to your users by any means, whether via Client Zone, in downloaded files or in any customer-designed interface.

Specifically, this means that you:

must host all your records for stores located in the PRC on Multimap's Chinese servers and host all your other store records on Multimap's global servers;
cannot host any records for stores located in the PRC on Multimap's global servers or host other store records on Multimap's Chinese servers;
must maintain separate Multimap service accounts if you wish to cover locations both inside and outside the PRC; and
cannot have your Multimap service(s) integrate records for stores located in the PRC with records for stores located elsewhere.

Street-level geocoding in the PRC is currently available via the Multimap API only. For further details of how this restriction affects your Multimap service(s), please see:

Logging in to Client Zone;
Creating a table of addresses;
Modifying records manually using Point and Click; and
Uploading static files.

Terminology

Technical Overview

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 latitude and longitude values for each store address.

GeoQuality codes

Multimap uses GeoQuality codes to tell you which elements of your addresses have matched records in our reference databases; for details, please see Multimap's GeoQuality Codes list.

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 (where applicable), state or province (where applicable) and country.

Certain legal restrictions apply to geocoding; for details, please see the section on Limits on Geocoded Data.

For details of how Multimap services interpret names and codes for countries, states and provinces, please see Multimap's online documentation on Countries and States.

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

Australia	Germany	Norway
Austria	Great Britain	Portugal
Belgium	Iceland	Singapore
Canada	Ireland	Spain
Czech Republic	Italy	Sweden
Denmark	Luxembourg	Switzerland
Finland	Netherlands	Turkey
France	New Zealand	United States

Notes

Great Britain	In Great Britain, more precise results are often achievable with postcode searches than with street searches. Multimap does not currently offer street-level maps for the Channel Islands or the Isle of Man. Geocoding is possible to street level in Northern Ireland, but street-level maps are available only for Belfast.
Ireland	Dublin, Cork, Galway, Waterford, Limerick, Arklow, Athlone, Bray, Carlow, Clondalkin, Drogheda, Dundalk, Greystones, Kildare, Kilkenny, Killarney, Leixlip, Maynooth, Mullingar, Naas, Navan, Newbridge, Portlaoise, Portmarnock, Skerries, Sligo, Swords, Tralee, Wexford
Turkey	Istanbul, Ankara and coastal or tourist areas

Geocoding of addresses in these countries can be accurate to either the building number or the segment of the street on which the address is located. If a building number is supplied along with a street name, Multimap uses the number to locate the building as precisely as possible within the correct street segment. Where we are not able to geocode an address to its street segment, we geocode it to a nominal street midpoint.

Town-level geocoding

In countries other than those listed above, Multimap geocodes 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 to the record the coordinates of the nominal center of that city.

If you are showing locations in the People's Republic of China, the level of geocoding accuracy depends on the source data that is available, as it does in other countries. However, certain legal restrictions apply; for details, please see the section on Limits on Geocoded Data - PRC.

How Client Zone works

Client Zone 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;
upload templates (where applicable), icons, static files and images;
manage users, logins and passwords;
view your service documentation; and
view traffic reports for your Multimap service(s).

If you have an HTML Multimap service that uses templates, you can also manage these templates through Client Zone; for details, please see the Implementation Guidelines documentation for the relevant service(s).

Preview and live environments

You can test any changes made to your Multimap services in a preview environment before making them live. For details, please see the relevant sections of the Implementation Guidelines documentation for your service.

Service enhancements

Multimap offers extra features to enhance Client Zone:

Shared Record Checking Version 1.0

Shared Record Checking (SRC) is a feature of Client Zone that enables an administrator to enlist the assistance of local experts to check store records; SRC automates the process of sending store details to recipients for verification.

If you would like to add this module, please contact your Multimap account manager.

XML Data Upload Version 2.1

The Multimap XML Data Upload service is a tool that lets customers manipulate and substitute data in their table of addresses on Multimap‘s servers directly over the Internet, uploading larger amounts of data more quickly than would otherwise be possible.

If you would like to use XML Data Upload to upload your addresses, please speak with your Multimap account manager to add this service. Instructions for uploading addresses can be found in the Implementation Guidelines documentation for your XML Data Upload service.

Implementing Your Multimap Service

Implementation stages

These are the stages in setting up your Multimap data:

Preparing your table of addresses
Uploading, adding and geocoding addresses
Reviewing geocoded results
Activating your table of addresses

Preparing your table of addresses

To display stores on maps, and the information about the stores in your results page, you need to create a simple database and load that onto Multimap's servers for geocoding.

To see an example of Multimap's default table structure, please see Example Museum and Art Gallery Addresses.

Logging in to Client Zone

To log in to your Client Zone account, visit:

https://cz.multimap.com/clients/cz.cgi

If you are logging in to Client Zone for a Multimap service that contains records of stores in the People's Republic of China that have been geocoded to street level, the URL that you should use instead is:

https://china.cz.multimap.com/clients/cz.cgi

From the login page, enter the username and password of your company. This takes you to the Select a service to manage page.
From the Select a service to manage page, click on the service to which your data applies.

Creating a table of addresses

Before creating your table of addresses, please take time to review the Address table preparation guidelines. This should help simplify the process of subsequently geocoding your addresses.

The files of data that you upload must be either tab-delimited text files with a ".txt" file extension or CSV (Comma-Separated Values) text files. You can export data to these formats from Microsoft Excel spreadsheets. Valid file extensions are ".xls", ".csv", ".tsv", ".tab" and ".txt".

For details of character encoding, please see the relevant paragraph in the Address table preparation guidelines. For details of recommended file sizes and the specification we follow when parsing files containing comma- or tab- separated values, please see the Specification of Comma- or Tab-separated Files page.

The default fields in Client Zone for new services are client_id, name, street, town, pc, state, country, id, GeoQuality, GeocodeSource, GeocodeDate, lat and lon.

Multimap populates the id, GeoQuality, GeocodeSource, GeocodeDate, lat and lon fields.

The client_id field is for you to populate with your store's unique identifier. The name, street, town, pc, state and country fields are for you to add your store address details.

Please note that, if your Multimap service covers the People's Republic of China to street level, you cannot see the lat and lon fields in Client Zone; they are hidden, for reasons explained in the section on Limits on Geocoded Data.

You can choose whether to retain the name field in your table of addresses but, if you do, it must not be NULL. To enable addresses to be geocoded to street level, your table of addresses must contain values in the street, town and country fields. In countries that use postal codes, you should also include the pc field. If your service covers a country that has states, territories or provinces, you should populate the state field. If these values are not in your table, the geocoding accuracy is likely to be reduced.

In this field	Enter this	Example
`Client_id`	Your own unique record identifier	331578
`Name`	A name or description of your store	Top Rank Hotel
`Street`	Building numbers and street names	1605 Adams Drive
`town`	Town, suburb or city name	Menlo Park
`pc`	Postal (or ZIP) code	02129 or 77380-2758
`state`	Full names or abbreviations for states, provinces, territories and territorial areas For details of those countries to which this field applies, please see Multimap's online documentation on Countries and States.	CA or California
`country`	Country names, abbreviations or two-letter ISO codes	United States, America, USA or US

Enter building numbers in the street field either before or after the street name. Add postal codes and town names in separate fields. For a set of sample data, please see Example Museum and Art Gallery Addresses.

Reviewing your table structure

Before uploading your table of addresses, make sure its structure is suitable for uploading.

The fields in the Client Zone table structure that you should not rename or remove are client_id, street, town, pc and country. It is possible to remove the name field but we do not recommend it.

We recommend that you include a header row at the beginning of your data file at the top of your spreadsheet. This should contain fields for at least street, town, postal code and country to ensure the best geocoding of your addresses.

If you include a header row your uploaded table structure can replace the existing Client Zone table structure.
If you do not include a header row, your table must contain columns in exactly the same order as the fields in the table structure in Client Zone; it cannot override the existing Client Zone table structure.

If for some reason you are unable to add a header row to your table of addresses or change its table structure, you should adapt the table structure in Client Zone to match your data before uploading it.

For details of character encoding in table header rows, please see the relevant paragraph in the Address table preparation guidelines.

Adding and deleting table fields

To add fields to your table:

Select your service from the Select a service to manage page, click on the links to Management Menu, Data Actions in the Preview Environment column and then View or change address table structure.
From the View or change address table structure page:
- To add a field, click the Add a field button to create another column for your data. From the Add field to database table page, enter the field details then click the Add field button.
- To delete a field, click the Edit button. From the Edit [fieldname] database field page, use the Delete field button then click OK to confirm deletion. This takes you back to the View or change address table structure page.
Where you have changed the order of column names and you want to retain this structure, make a note of the final order as the files you upload that contain new addresses must have exactly the same structure.
Click Back to Menu.

This returns you to the Management Menu page.

Editing table fields

To edit database fields for your selected service:

Select your service from the Select a service to manage page, click on the links to Management Menu, Data Actions in the Preview Environment column and then select View or change address table structure.
From the View or change address table structure page, click the Edit button alongside the field you want to change. This displays the Edit fieldname database field page.
Make changes as indicated in the Guidelines for Editing Address Table Structure and click the Update field button to save each change. This commits the modification and takes you back to the View or change address table structure page.
When you have finished making changes, click the Back to Menu button to return to the Management Menu page.

Address table preparation guidelines

Character encoding

Client Zone supports Unicode encoding; we recommend the use of UTF-8. This supports any character in the Unicode standard.

However, the following items of data should use only characters within the Latin-1 encoding character set:

field names of header rows in your table of addresses;
the Comments sections for uploading static files, templates and images; and
the Comments section for reverting static files, templates and images.

For details of the Latin-1 encoding character set, please see the World Wide Web Consortium reference page.

Preparing addresses for successful geocoding

To improve your geocoding success rate, use full names instead of abbreviations and omit information that is not part of a formal postal address. For instance, providing the names of two streets that intersect, as in "Stadhouderskade 7 (Leidseplein), Amsterdam", presents difficulties that you could avoid by providing a single street name.

For full details on GeoQuality codes, please see Multimap's GeoQuality Codes list.

Reviewing syntax of addresses

We recommend that you review the syntax of your address data and make changes where necessary, before uploading the addresses for geocoding. When reviewing your addresses:

Check for	How Multimap interprets addresses when geocoding
Abbreviations	Words that are commonly abbreviated are recognized, such as "St" instead of "Saint" or "Street".
Characters specific to individual languages	Client Zone supports Unicode character encoding; additionally, conventional alternative spellings for accented characters are recognized in the German, Danish and Swedish languages. For instance, "ue" is an acceptable substitute for "ü" .
Misspellings	Misspelled words are accepted, where a close but not exact match is found.
Validity	A town with a name that sounds similar is offered as an alternative, where no town is found.

Uploading, adding and geocoding addresses

Uploading and geocoding addresses

To upload and geocode addresses:

Select your service from the Select a service to manage page, click on the links to Management Menu, Data Actions in the Preview Environment column and select Upload addresses.
From the Upload addresses page, use Browse... to select the file containing your table of stores, locations or assets. Check that the file has a valid file extension (".csv", ".tsv", ".tab" or ".txt").
If your table of addresses already contains one or more records, a pair of radio buttons appears on the page, prompting you to Add new addresses or Replace all addresses. If you see these buttons you must make a selection:
- Add new addresses appends to your existing table of addresses all the records in the data file that you are uploading; and
- Replace all addresses deletes all existing records from your table of addresses and overwrites them with the records in your new data file.
Click the Upload button. This uploads your new address data, geocodes it into geographic coordinates and displays a summary of the results on the Geocoding status page.
If the table structure of your data file does not match that of your Client Zone table of addresses, Client Zone displays a warning to this effect:
- if you have selected Add new addresses, Client Zone prevents you from uploading your new file, as this might change the structure of the existing table of addresses; and
- if you have selected Replace all addresses, Client Zone asks you if you wish to overwrite your existing data. If your data file contains a header row, you can use this option to override the existing structure of your table of addresses table with that of your new data file.

If you select the Add new addresses option, please do not include in your upload file any records that already exist in your table of addresses, since this might create duplicate records there.

Please note that, during the geocoding process, a "Please wait..." message might remain visible on the Geocoding status page for up to five minutes, after which time the page shows the percentage of the geocoding process that has completed already. Meanwhile, if necessary, the geocoding process continues in the background; so, for example, if you check back again later or refresh your page after the geocoding process has finished after 15 minutes, you should see that all your records have been geocoded.

Adding addresses manually

If you wish, you can add addresses to Client Zone manually. To add an individual address:

Select your service from the Select a service to manage page, click on the links to Management Menu, Data Actions in the Preview Environment column and select Add address.

Enter the details of your new address in the text fields on the Add address page.

Use the drop-down lists to select values for your country field (and state field, if applicable — for details of states, please see online documentation on Countries and States).
Click the Add address button. This uploads your new address data to your preview environment, geocodes it into geographic coordinates and displays the results on the Edit Record page along with a map.
If you wish to change any of the field values, edit the relevant fields.
If you wish to change the position of the icon on the map, click once on the correct location to reposition the icon and re-geocode the coordinates (as demonstrated in the section on Modifying records manually using Point and Click).
When you are satisfied that your record is correct, click the Update Record button to save your changes.
Click the Back to Menu button to return to the Management Menu.

Reviewing geocoded results

View the Geocoding status page, which shows the progress of geocoding and the quality of the results of geocoding.

Select your service from the Select a service to manage page, click on the links to Management Menu, Data Actions in the Preview Environment column and then select Geocoding status. The geocoding process can take some time, from a few seconds to a few hours, depending on the number of records to be geocoded and the accuracy of the addresses. If the structure of the table of addresses you uploaded is different from the existing one, you can click the Continue geocoding button to accept the new structure or click Back to Menu to upload a file of the same structure. When you upload a file of addresses, they are automatically geocoded, finding latitude and longitude coordinates for each address.
On the Geocoding status page, GeoQuality codes group the results according to how closely the coordinates assigned to your addresses match all the address elements.

For a full list of GeoQuality codes, please see Multimap's GeoQuality Codes list.

Improving geocoding quality

Client Zone provides a way to check or improve the geocode quality of coordinates provided as a result of geocoding the address, using GeoQuality codes.

Improvements are most commonly required where our system cannot match a specific location to an address (there may be no matches, indicated by GeoQuality code "0", or multiple matches indicated by a GeoQuality code with the prefix "7").

These codes are the most important to understand and act upon:

GeoQuality code	Meaning and action required
0	If your address has a code of "0", we have not been able to geocode it at all. Please check the validity of the address to determine whether it contains enough information for geocoding. The information required for geocoding to street level is street, town, postal code, state (where applicable) and country.
7 (prefix)	Found a list of alternatives. Alternative addresses are found when a location cannot be resolved to a single address. For example: Via Bianchini 15, 00142, Rome, IT. Found alternative 1: VIA FRANCESCO BIANCHINI, 00142, ROMA Via Bianchini 15, 00142, Rome, IT. Found alternative 2: VIA MARIO BIANCHINI, 00142, ROMA Via Bianchini 15, 00142, Rome, IT. Found alternative 3: VIA EMILIO BIANCHI, 00142, ROMA It is not clear whether "Via Bianchini" refers to "Via Francesco Bianchini", "Via Mario Bianchini" or "Via Emilio Bianchi" so the three alternatives are shown on the Edit record page. Check the address to make sure it is complete and accurate. This is especially important where there are several streets in the same vicinity with similar names.

GeoQuality code

Meaning and action required

If your address has a code of "0", we have not been able to geocode it at all. Please check the validity of the address to determine whether it contains enough information for geocoding.

The information required for geocoding to street level is street, town, postal code, state (where applicable) and country.

7 (prefix)

Found a list of alternatives. Alternative addresses are found when a location cannot be resolved to a single address.

For example:

Via Bianchini 15, 00142, Rome, IT. Found alternative 1: VIA FRANCESCO BIANCHINI, 00142, ROMA

Via Bianchini 15, 00142, Rome, IT. Found alternative 2: VIA MARIO BIANCHINI, 00142, ROMA

Via Bianchini 15, 00142, Rome, IT. Found alternative 3: VIA EMILIO BIANCHI, 00142, ROMA

It is not clear whether "Via Bianchini" refers to "Via Francesco Bianchini", "Via Mario Bianchini" or "Via Emilio Bianchi" so the three alternatives are shown on the Edit record page.

Check the address to make sure it is complete and accurate. This is especially important where there are several streets in the same vicinity with similar names.

We recommend that you check any records with a GeoQuality code with the prefix "7" and, if necessary, that you manually edit these records using our Point and Click tool before making your data live. If you do not edit these records, Multimap uses the first alternative as the store's location.

If you would prefer not to have coordinates added automatically to your table of addresses in the event of multiple matches, and to check the alternatives yourself, please contact Multimap's Customer Support team to change this.

Modifying records manually using address fields

To open the Edit record page:

From the Management Menu, Geocoding status page, click the View records button next to each record in the GeoQuality results table. This opens the Find and edit addresses page.
From the Find and edit addresses page, to improve the GeoQuality of the record, click Edit. The Edit record page displays the geocoded location (or several, where alternatives were found) on a map.
Where a single address is found, change the address and click the Update record button to re-geocode it. Alternatively, edit coordinates manually. Either:
- use Client Zone's Point and Click tool to re-position the icon on the map (as described in the section on Modifying records manually using Point and Click), dragging and zooming the map as required; or
- enter coordinates in the lat and lon fields yourself, if you know the geographical coordinates of the record.
When you are satisfied that the location is correct, click Update record.

This saves the new coordinates to your table of addresses.

Modifying records manually using Point and Click

Client Zone lets you modify the position of an icon on your map by either clicking on the map to move the location marker or dragging the marker across the map. You can also drag the map and use its controls to pan north, south, east or west and zoom in and out. To improve geocoding results, you can use Point and Click to change any record on the Edit record page.

Please note that, if your Multimap service covers the People's Republic of China to street level, you cannot see the lat and lon fields in Client Zone; they are hidden, for reasons explained in the section on Limits on geocoded data.

Selecting an address from multiple records

A GeoQuality code with the prefix "7" means that the system has come up with multiple matches. You will need to select the address you require from a list (see below). Please note that if you do not edit these records, when your data goes live, Multimap will take the first alternative as the store's location.

After selecting an address from a list of alternatives, you can use the Point and Click feature to modify the coordinates manually, or drag the map or the icon that it displays. If you perform these actions and cannot find the location, at any time you can re-geocode on the address fields. Click the Geocode record button to re-geocode the address. This button is only present where the GeoQuality code for an address has the prefix "7", or is "8" or "9".

To view records with a GeoQuality with the prefix "7" and select an address:

From the Management Menu, Geocoding status page, click the View records button next to records with a GeoQuality with the prefix "7". This opens the Find and edit addresses page.
Click Edit on the Find and edit addresses page to open the Edit record page. This displays on a map all the possible alternative locations that were found.

Where there is no match and the record has no coordinate associated with it (GeoQuality code "0"), if you cannot improve the GeoQuality code for these records, we recommend removing them from your table.

Activating your table of addresses

When you are satisfied that the locations in your table of addresses are correct, you can copy the table to your live environment. From the Management Menu, Data Actions section in your preview environment:

Click the Copy your data link to open the Copy addresses to your live environment page where you can:
enter the reason for uploading the new data in the Notes on data changes field; and
click the Copy addresses to your live environment button.
Click the Back to Menu button to return to the Management Menu.

Restoring addresses uploaded previously

To revert to previous live addresses:

From the Management Menu, Data Actions section of the Live Environment column, select Revert to previous live addresses.
From the Revert to previous live addresses page, you can undo a Copy addresses to your live environment operation.

When you copy data from your preview environment to your live environment, Multimap retains a 'snapshot' copy of the live data that is being replaced. When you revert to previous addresses, you replace the table of addresses in your preview environment with the previous live environment table.

Downloading addresses

You can download copies of the tables of addresses in both your preview and live environments. These are available in ".xls" and ".csv" formats. Multimap recommends that you select the ".xls" format, since Microsoft Excel and some other spreadsheet applications cannot process data in ".csv" format as efficiently as in others.

To download your data:

Click on the relevant Download addresses link on the Management Menu page.
Click on the file you wish to download and follow your browser‘s prompts.
Repeat this action for each file you wish to download.
Click the Back to Menu button to return to the Management Menu.

For details of contractual limits on the use of geographic data contained in these tables, please see the section on Limits on geocoded data.

Managing HTML templates and icons

If you have a Multimap service that uses HTML templates and custom icons, such as Storefinder, Location Map, Portal, Travel Directions or Weather, please see that service's separate Implementation Guidelines documentation for details of uploading and managing those files in Client Zone.

Please note that any text you enter in the Comments field when uploading or reverting static files, templates or images should use only characters within the Latin-1 encoding character set.

Managing static files and images

The Static File Upload feature allows you to store static files, such as style sheets, images and JavaScript files, on Multimap's servers by uploading them through Client Zone.

If your Multimap service was created before October 2006 and you cannot see the options on your Management Menu page that mention static files, please contact your account manager.

File types supported

You can use Client Zone to upload files with any of these extensions:

.css	.gif	.jpe	.pjp
.js	.jpeg	.jfif	.png
.txt	.jpg	.pjpeg

Client Zone can handle the following MIME types:

text/plain	image/jpeg
text/html	image/pjpeg
text/css	application/octet-stream
image/gif

Uploading static files

To upload a file to your live environment:

On the Management Menu screen, follow the Upload static files link to browse for a file on your own computer or network.
Select the file and enter a comment. (This comment appears on the Revert static files page.)
Click the Upload button to upload the file to your preview environment.
Click the Copy button to copy the file to your live environment.
Repeat these actions for each file you wish to upload.
Click the Back to Menu button to return to the Management Menu.

The current version of Client Zone does not fully support the testing of static files in its preview environment. This means that, to view the static files that you have uploaded, you should copy them from your preview to your live environment and then use the URL:

http://www.multimap.com/share/[clientname]/[filename]

If you are logging in to Client Zone for a Multimap service that contains records of stores in the People's Republic of China that have been geocoded to street level, the URL that you should use instead is:

http://china.multimap.com/share/[clientname]/[filename]

Reverting static files

Uploading an existing file creates a new version of that file. You can revert to an older version using the Revert static files link on the Management Menu page.