Multimap XML Data Upload Version 2.1 Implementation Guidelines

This document describes how to set up and use Version 2.1 of Multimap's XML Data Upload service and how to activate your data using Multimap's Client Zone extranet portal.

Who should read this documentation?

This documentation is for programmers, developers, webmasters, project managers and other IT personnel who are implementing Version 2.1 of Multimap's XML Data Upload service. The Multimap services that work with XML Data Upload are:

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

Assumptions

The document assumes that you:

• have a working knowledge of HTTP client components and XML;
• are familiar with the Multimap service with which you are combining XML Data Upload; and
• already have a Multimap service with a data structure defined in Client Zone, preferably populated with some test data using Client Zone.

You need a Multimap service client account and an XML Data Upload password, which is distinct from your Client Zone password. 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 the mechanics of Version 2.1 of Multimap's XML Data Upload service and examples and descriptions of the structure of the XML documents used.

This document does not provide instruction in XML, recommend a specific programming or scripting language or give guidelines on how to customize your Multimap services. Please see Multimap's online documentation for guidelines on using Multimap DTDs.

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 and editing table structure;
• Inserting, updating and deleting records;
• Responses from the XML Data Upload service; and
• Error codes and error messages.

What is XML Data Upload?

How XML Data Upload Works

The XML document sent in the HTTP request to the XML Data Upload service must conform to the MultimapXDU DTD. For details, please see Example XML Document, Inserting, Updating and Deleting Records and http://www.multimap.com/dtd/MultimapXDU_2.1.dtd.

When Multimap servers receive an XML Data Upload HTTP request, they authenticate this request before processing the document. The XML Data Upload service then processes the transactions that the document contains and returns status information in an XML document conforming to the MultimapXDUStatus DTD. For details, please see Responses from the XML Data Upload Service http://www.multimap.com/dtd/MultimapXDUStatus_2.1.dtd.

Uploaded changes are applied to the table of addresses in your preview environment until you send a request to explicitly apply the changes to the table in your live environment. If the table in your preview environment does not already contain data, it is automatically populated with the content of your live table.

Multimap can optionally alter the behavior of your XML Data Upload service so that geocoding is performed offline on your uploaded data as a whole, instead of at the time of each request. This allows you to upload data more rapidly than it would take to geocode online, but means that you do not receive information on geocoding quality and reports of errors for each individual record. If you wish to activate this option, please see Offline Geocoding and contact your Multimap account manager.

How Client Zone works

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

• customize your Multimap service;
• view your service documentation; and
• view your Multimap services' 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 details, please see the relevant sections of the Implementation Guidelines documentation for your service.

Preparing for Upload

Logging in to Client Zone

For details on logging in to Client Zone, please see Multimap's Client Zone documentation.

Creating and editing table structure

Your data table is created in your preview environment initially. To activate your table of addresses in Client Zone, click the link to Copy addresses to your live environment. Alternatively, you can make your table live with an XML 'action' request; please see Copying a table from preview to live for details.

Implementing XML Data Upload

XML Interface

Use this URL to send your XML request to upload your data:

https://www.multimap.com/clients/upload.cgi

You must supply your username and password in an HTTP header along with the request for authentication by Multimap. To send the XML document to the Multimap XML Data Upload service, you need to include some headers of your own with an HTTP component. Most programming languages (such as Java and Visual Basic) and scripting languages (such as Perl and ASP) provide a means of doing this in the form of libraries, packages or modules.

You need to include the following HTTP headers in your request:

Example XML Document

Structure of requests

Your XML Data Upload requests are XML documents that must conform to the MultimapXDU document detailed at:
http://www.multimap.com/dtd/MultimapXDU_2.1.dtd

These XML documents should always begin with the following elements:

<?xml version="1.0" ?> 
<!DOCTYPE MultimapXDU SYSTEM "http://www.multimap.com/dtd/MultimapXDU_2.1.dtd">
<MultimapXDU serviceid="[clientname]">

Multimap's Client Zone supports Unicode encoding; we recommend the use of UTF-8. This supports any character in the Unicode standard. If you do not specify a character encoding, the XML document is processed as having UTF-8 encoding (the default for XML).

Multimap also supports uploading of XML documents encoded in ISO-8859-1 (Latin-1) but, because UTF-8 is the default, you must specify the encoding at the head of your XML document with the line <?xml version="1.0" encoding="ISO-8859-1"?>. Whichever encoding is used for uploading the data, Multimap stores it as UTF-8 encoded data.

An exception to the scope of Unicode support in XML Data Upload is for the field names of header rows in your table of addresses (and, therefore, for the Name attributes of the XML elements that correspond to them); these should use only characters within the Latin-1 encoding character set. For details of the Latin-1 encoding character set, please see the World Wide Web Consortium reference page.

To complete your XML MultimapXDU document after you have appended your Store elements (as described elsewhere in this section) add the following closing tag: </MultimapXDU>

Please note that you can place up to 100 Store elements within each XML request document.

Here is a typical XML Data Upload HTTP request:

<?xml version="1.0" ?>
<!DOCTYPE MultimapXDU SYSTEM "http://www.multimap.com/dtd/MultimapXDU_2.1.dtd">
  <MultimapXDU serviceid="[clientname]">
   <Stores>
    <Store mode="insert" uniqid="17">
    <Info><Name>country</Name><Value>GB</Value></Info>
    <Info><Name>fax</Name><Value>No fax recorded</Value></Info>
    <Info><Name>name</Name><Value>My Store</Value></Info>
    <Info><Name>street</Name><Value>150 Holborn</Value></Info>
    <Info><Name>telephone</Name><Value>020-7430-5454</Value></Info>
    <Info><Name>town</Name><Value>London</Value></Info>
    <Info><Name>pc</Name><Value>EC1N 2NS</Value></Info>
    </Store>
    <Store mode="update" uniqid="18">
    <Info><Name>name</Name><Value>My New Store - updated</Value></Info>
    </Store>
    <Store mode="delete" uniqid="19" />
  </Stores>
</MultimapXDU>

Notes on the code

Inserting, Updating and Deleting Records

• inserting records;
• updating records; and
• deleting records.

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.

Inserting records

Please include address details in each record's Info elements. When uploaded, Multimap geocodes and populates the lat and lon values for the record if the geocoding is successful. For details, please see Geocoding results.

Example - inserting a record:

<Store mode="insert" uniqid="17">
<Info><Name>country</Name><Value>GB</Value></Info>
<Info><Name>name</Name><Value>My New Store</Value></Info>
<Info><Name>street</Name><Value>150 Holborn</Value></Info>
<Info><Name>town</Name><Value>London</Value></Info>
<Info><Name>pc</Name><Value>EC1N 2NS</Value></Info>
<Info><Name>telephone</Name><Value>020-7430-5454</Value></Info>
<Info><Name>fax</Name><Value>No fax recorded</Value></Info>
</Store>

Updating records

<Store mode="update" uniqid="18">
<Info><Name>name</Name><Value>My New Store - updated</Value></Info>
</Store>

Deleting records

<Store mode="delete" uniqid="19">

<Store mode="delete" uniqid="all">

Geocoding results

When we update your table of addresses with geographic coordinates, the level at which we match your address is recorded in the GeoQuality field in your table. For a full list of GeoQuality codes, please see Multimap's GeoQuality Codes list.

If you have activated Multimap's XML Data Upload Offline Geocoding feature (as described in Offline Geocoding), you should send a separate request to start the geocoding process; otherwise, geocoding takes place automatically. If this feature is activated, record-level geocoding information as described in this section cannot be returned in response to your requests. You can, however, view this information in Client Zone when your offline geocoding has finished.

Any records that Multimap cannot geocode successfully are listed in the Stores section of the MultimapXDUStatus document with a GeoQuality child element with a value of "0" or "7" and an appropriate Warning error code. Records that cannot be geocoded are inserted into the table of addresses but are not returned in any set of search results until the address details are updated or a manual geocode is provided.

Geocoding may be unsuccessful if:

• no addresses in our databases match the address details of your record, in which case the GeoQuality element has the value "0" and a Warning element is present with the error code "MM_XDU_GEOCODING_FAILED"; or
• the address provided matches multiple locations in our databases, in which case the GeoQuality element has the value "7" and a Warning element is present with the error code "MM_XDU_GEOCODING_MULTIPLE_RESULTS".

A list of matching place names and geocodes is provided in the MultimapXDUStatus document when multiple locations match your address details; for details, please see Structure of responses to successful requests to update data. You can update your record with the correct coordinates from this list, (unless your Multimap service covers the People's Republic of China to street level).

The Multimap Customer Support team can activate a feature whereby the first matching address is used in cases where multiple addresses match the criteria. To supply your own geocode, send lat and lon values in the record's Info elements:

<Info><Name>lon</Name><Value>-0.111</Value></Info>
<Info><Name>lat</Name><Value>51.5184</Value></Info>

Please note that, if your Multimap service covers the People's Republic of China to street level, the fields that contain the coordinates of your store records are hidden from view in Client Zone for legal reasons and cannot be downloaded again. When the process of geocoding your data in your preview environment is complete, copy your data to your live environment; please see Copying a table from preview to live.

Copying a table from preview to live

<?xml version="1.0" ?>
<!DOCTYPE MultimapXDU SYSTEM "http://www.multimap.com/dtd/MultimapXDU_2.1.dtd">
<MultimapXDU serviceid="[clientname] ">
<Action type="MAKE_TABLE_LIVE" />
</MultimapXDU>

Please see Responses to MAKE_TABLE_LIVE 'action' requests for a typical response to this request.

Processing records in batches

The service can process up to 100 database operations (delete, update and insert) for each XML request. This means that, for example, if you wish to update 247 records, you must update the first 100 records in one XML request, the next 100 records in a second request and the final 47 records in a third request. Regardless of the order in which an XML document specifies its operations, they are grouped by the mode of operation, with the predefined order being delete, update, insert and then the order that the operations appear in the XML document.

We recommend that, for performance reasons, you make multiple requests of up to 100 operations until you have completed all your changes, and then issue a MAKE_TABLE_LIVE 'action' request, rather than after each 100-operation request.

Offline Geocoding

<?xml version="1.0" ?>
<!DOCTYPE MultimapXDU SYSTEM "http://www.multimap.com/dtd/MultimapXDU_2.1.dtd">
<MultimapXDU serviceid="[clientname] ">
<Action type="START_GEOCODING" />
</MultimapXDU>

Please see Responses to START_GEOCODING 'action' requests for a typical response to this request.

GEOCODING_STATUS 'action' requests

To check on the status and GeoQuality codes of your geocoded data, send the following request:

<?xml version="1.0" ?>
<!DOCTYPE MultimapXDU SYSTEM "http://www.multimap.com/dtd/MultimapXDU_2.1.dtd">
<MultimapXDU serviceid="[clientname] ">
<Action type="GEOCODING_STATUS" />
</MultimapXDU>

Please see Responses to GEOCODING_STATUS 'action' requests for a typical response to this request.

Please contact your Multimap account manager if you wish to activate the Offline Geocoding option for your XML Data Upload service.

Responses from the XML Data Upload Service

Structure of responses to successful requests to update data

The end of an XML response document includes a summary of all geocoded records. When we update your table of addresses with geographic coordinates, the level at which we matched your address is recorded in the GeoQuality field in the table. For details, please see Multimap's GeoQuality Codes list.

All changes have been successful, with no errors or warnings:

<?xml version="1.0" ?> 
<!DOCTYPE MultimapXDUStatus SYSTEM "http://www.multimap.com/dtd/MultimapXDUStatus_2.1.dtd">
<MultimapXDUStatus>
 <Stores>
   <Store uniqid="a" status="OK">
    <GeoQuality>4</GeoQuality>
   </Store>
   <Store uniqid="b" status="OK">
    <GeoQuality>1</GeoQuality>
   </Store>
</Stores>
<GeoQualitySummary>
<GeoQualityCount code="1">1</GeoQualityCount>
<GeoQualityCount code="4">1</GeoQualityCount>
</GeoQualitySummary>
</MultimapXDUStatus>>

This means the change for Store element "a" has been successful; it has geocoded to a GeoQuality value of "4". The change for Store element "b" has also been successful with a GeoQuality value of "1". The GeoQualitySummary element provides counts of records that matched the GeoQuality geocoding match types achieved for this XML Data Upload request. In this example one record had a GeoQuality of "1" and one record had a GeoQuality of "4".

Two changes have been successful (one with a warning) and one has failed because of an error:

<?xml version="1.0" ?>
<!DOCTYPE MultimapXDUStatus SYSTEM "http://www.multimap.com/dtd/MultimapXDUStatus_2.1.dtd">
<MultimapXDUStatus>
 <Stores>
   <Store uniqid="a" status="OK">
    <GeoQuality>4</GeoQuality>
   </Store>
   <Store uniqid="b" status="OK">
    <GeoQuality>1</GeoQuality>
    <Warning code="MM_XDU_INTERNAL_COLUMN_CHANGE_ATTEMPT" />
   </Store>
   <Store uniqid="c" status="ERROR">
    <Warning code="MM_XDU_INTERNAL_COLUMN_CHANGE_ATTEMPT" /> 
    <Error code="MM_XDU_INVALID_STOREFINDER_FIELD">Unknown column 'fax_number' in 'field list'</Error>
   </Store>
</Stores>
<GeoQualitySummary>
    <GeoQualityCount code="1">1</GeoQualityCount>
    <GeoQualityCount code="4">1</GeoQualityCount>
</GeoQualitySummary>
</MultimapXDUStatus>

In this example:

• the change to Store element "a" has updated correctly;
• the change to Store element "b" has been applied, but the XML request has uploaded a value for the internal Multimap column GeoQuality (as described in Error Codes and Error Messages); and
• the change to Store element "c" has failed because a value has been provided for the fax_number field, but this field does not exist in the table of addresses.

Two changes have been successful, but the first failed to geocode and the second had multiple address matches:

<?xml version="1.0" ?>
<!DOCTYPE MultimapXDUStatus SYSTEM "http://www.multimap.com/dtd/MultimapXDUStatus_2.1.dtd">
<MultimapXDUStatus>
 <Stores>
   <Store uniqid="a" status="OK">
    <Warning code="MM_XDU_GEOCODING_FAILED" />
   </Store>
   <Store uniqid="b" status="OK">
    <GeoQuality>7</GeoQuality>
    <Warning code="MM_XDU_GEOCODING_MULTIPLE_RESULTS" />
    <Locations>
     <Location>
       <PlaceName>Brighton,Brighton & Hove</PlaceName>
       <GeoQuality>3</GeoQuality> 
       <lon>-0.13400</lon> 
       <lat>50.82410</lat> 
     </Location>
    <Location>
       <PlaceName>Brighton,Cornwall</PlaceName> 
       <GeoQuality>3</GeoQuality> 
       <lon>-4.94740</lon>
       <lat>50.35180</lat>
    </Location>
   </Locations>
  </Store>
 </Stores>
<GeoQualitySummary>
<GeoQualityCount code="7">1</GeoQualityCount>
</GeoQualitySummary>
</MultimapXDUStatus>

In this example the Store element "a" has been inserted but did not match a location in Multimap's databases. The record is not returned in the set of results. In such cases, you should check the address details or provide a manual geocode. In the same example the Store element "b" has been inserted but the address details provided matched multiple locations in our databases. The record is not returned in the set of search results. You can manually geocode the Store record by updating it with the coordinates of one of the potential matches in the Locations element.

Please note that, if your Multimap service covers the People's Republic of China to street level, the XML responses that you receive do not include the lat and lon elements for legal reasons.

Structure of responses to failed requests to update data

The second type of response to a request to update a table of addresses is a major error that prevents any of the requested changes being processed.

No authorization header has been provided:

<?xml version="1.0" ?>
<!DOCTYPE MultimapXDUStatus SYSTEM "http://www.multimap.com/dtd/MultimapXDUStatus_2.1.dtd">
<MultimapXDUStatus>
   <RequestError code="MM_XDU_UNAUTHORIZED">Authorization failed, as no HTTP authorization 
header was received.  If you are sending this header, check whether any firewalls or 
proxies on your network are removing it from the HTTP request.</RequestError>
</MultimapXDUStatus>

No data table is present:

<?xml version="1.0" ?>
<!DOCTYPE MultimapXDUStatus SYSTEM "http://www.multimap.com/dtd/MultimapXDUStatus_2.1.dtd">
<MultimapXDUStatus>
   <RequestError code="MM_XDU_NO_STOREFINDER_TABLE">Storefinder table missing, use Client Zone
 to create and activate your Storefinder table.</RequestError>
</MultimapXDUStatus>

Please see Error Codes and Error Messages for a full list of errors and warnings. The body of the RequestError element of the response contains additional information.

Responses to MAKE_TABLE_LIVE 'action' requests

This an example of an XML response to a request to copy a table of addresses to a live environment, as described in Copying a table from preview to live:

<?xml version="1.0" ?> 
<!DOCTYPE MultimapXDUStatus SYSTEM "http://www.multimap.com/dtd/MultimapXDUStatus_2.1.dtd">
<MultimapXDUStatus>
<ActionStatus type="MAKE_TABLE_LIVE">SUCCEEDED</ActionStatus>
</MultimapXDUStatus>

Valid values for the ActionStatus element are "SUCCEEDED" or "FAILED". You must upload some changes before requesting this action. If you have uploaded some changes successfully to your preview environment and you see the result "FAILED" in response to a MAKE_TABLE_LIVE 'action' request, please contact the Multimap Customer Support team.

Responses to START_GEOCODING 'action' requests

This an example of an XML response to a request to start the process of geocoding records independently of Client Zone, as described in the section on Offline Geocoding:

<?xml version="1.0" ?> 
<!DOCTYPE MultimapXDUStatus SYSTEM "http://www.multimap.com/dtd/MultimapXDUStatus_2.1.dtd">
<MultimapXDUStatus>
<ActionStatus type="START_GEOCODING">SUCCEEDED</ActionStatus>
</MultimapXDUStatus>

Valid values for the ActionStatus element are "SUCCEEDED" or "FAILED". This action is available only if you have had Multimap activate the optional feature described in Offline Geocoding, and you must upload some changes before requesting this action. If you have uploaded some changes successfully to your preview environment and you see the result "FAILED" in response to a START_GEOCODING 'action' request, please contact the Multimap Customer Support team.

Responses to GEOCODING_STATUS 'action' requests

This an example of an XML response to a request to view the status of an earlier request to geocode records, as described in the section on Offline Geocoding:

<?xml version="1.0" ?>
<!DOCTYPE MultimapXDUStatus SYSTEM "http://www.multimap.com/dtd/MultimapXDUStatus_2.1.dtd">
<MultimapXDUStatus>
<GeocodingStatus>
<State>IN_PROGRESS</State>
<PercentageComplete>55</PercentageComplete>
</GeocodingStatus>
<GeoQualitySummary>
<GeoQualityCount code="1">100</GeoQualityCount>
<GeoQualityCount code="4">234</GeoQualityCount>
</GeoQualitySummary>
</MultimapXDUStatus>

Valid values for the State element are shown in the table below:

The GeoQualitySummary section is present in the response only after the process of geocoding has begun and the State element has a value of "IN_PROGRESS", "FINISHED" or "PAUSED". This action is available only if you have had Multimap activate the optional feature described in Offline Geocoding.

Error Codes and Error Messages

Frequently Asked Questions

I wish to upload records for stores that are located in the People's Republic of China. Can I combine these with my records for other stores that are located elsewhere?

No. For legal reasons, records for stores that are located within the People's Republic of China must be stored separately on dedicated servers that are physically located in that country. For further details, please see the Limits on geocoded data section.

Further Help

If you require further help with your Multimap services, please contact the Multimap Customer Support team:

For general account enquiries or further services, please contact the Multimap Sales team: