Multimap API v1.1 Example

Using the Multimap API Geocoder

This example shows how to work directly with Geocoding functionality of the Multimap API. It shows how to work directly with the MMGeocoder class, including the handling of multiple results from the geocoder.

The geocoder returns results in UTF-8 format. You should ensure that the encoding of your HTML page is set to UTF-8 using a header similar to the following:

<meta http-equiv="content-type" content="text/html;charset=UTF-8">

What You Should See

If you enter an address into the form, you will be presented with a map of your address, a list of possible matches or an error message (typically if no matches were found)

Please note that the list of countries presented is purely for demonstration purposes and is not an exhaustive list. Please contact your Multimap account manager for further information.

The Map

Address:
Town:
State:
Postal Code:
Country:

The Code

There are three parts to the code below. The first part shows the headers that you should have in your page, to ensure your page uses UTF-8 encoding, and to link to the Multimap API. The second is an example of the HTML you must have in your page. The third is an example of the JavaScript required to implement the page.

The header code

<meta http-equiv="content-type" content="text/html;charset=UTF-8">

<script type="text/javascript" src="http://clients.multimap.com/API/maps/1.1/demo"></script>

The body code

<!-- The Multimap Map-->
<div id="mapviewer" style="width : 500px; height : 420px;"></div>

<!-- The Query Form -->
<form action="#" onsubmit="callGeocoder(); return false;">
  <p>
     Address:
     <input size="10" name="street" id="street"/><br/>
     Town:
     <input size="10" name="city" id="city"/><br/>
     State (code):
     <input size="3" maxlength="3" name="state" id="state"/><br/>
     Postal Code:
     <input size="10" name="postal_code" id="postal_code"/><br/>
     Country:
     <SELECT name="country_code" id="country_code">
         <OPTION VALUE="AU">Australia</OPTION>
         <OPTION VALUE="AT">Austria</OPTION>
         <OPTION VALUE="BE">Belgium</OPTION>
         <OPTION VALUE="CA">Canada</OPTION>
         <OPTION VALUE="CZ">Czech Republic</OPTION>
         <OPTION VALUE="DK">Denmark</OPTION>
         <OPTION VALUE="FI">Finland</OPTION>
         <OPTION VALUE="FR">France</OPTION>
         <OPTION VALUE="DE">Germany</OPTION>
         <OPTION SELECTED="SELECTED" VALUE="GB">Great Britain</OPTION>
         <OPTION VALUE="GL">Greenland</OPTION>
         <OPTION VALUE="IS">Iceland</OPTION>
         <OPTION VALUE="IE">Ireland</OPTION>
         <OPTION VALUE="IT">Italy</OPTION>
         <OPTION VALUE="LI">Liechtenstein</OPTION>
         <OPTION VALUE="LU">Luxembourg</OPTION>
         <OPTION VALUE="NIR">Northern Ireland</OPTION>
         <OPTION VALUE="NL">Netherlands</OPTION>
         <OPTION VALUE="NO">Norway</OPTION>
         <OPTION VALUE="NZ">New Zealand</OPTION>
         <OPTION VALUE="PT">Portugal</OPTION>
         <OPTION VALUE="ES">Spain</OPTION>
         <OPTION VALUE="SE">Sweden</OPTION>
         <OPTION VALUE="CH">Switzerland</OPTION>
         <OPTION VALUE="TR">Turkey</OPTION>
         <OPTION VALUE="US">USA</OPTION>
     </SELECT>
     <input type="submit" id="searchbtn" value="Search"/>
  </p>
  <img id="geocodestatus" style="display : none;" src="/share/mapviewer/i/loading.gif" alt="Loading..." />
  <div id="message" ></div>
  <div id="resultsPane" style="width : 250px; height : 300px; overflow: auto;"></div>
</form>

The JavaScript code

var mapviewer, geocoder
var street, city, state, postal_code, country_code, searchbtn
var geocodestatus, message, resultsPane;
var results = new Array();
var markers = new Array();

function onLoad()
{
  //Add the map 
  mapviewer = new MultimapViewer( document.getElementById( 'mapviewer' ) );
  mapviewer.drawAndPositionMap( new MMLocation( new MMLatLon( 51.5145, -0.1085 ) ,15 ) );
  
  // Setup some references that will be useful later.
     street = document.getElementById( 'street' );
     city = document.getElementById( 'city' )
     state = document.getElementById( 'state' );
     postal_code = document.getElementById( 'postal_code' );
     country_code = document.getElementById( 'country_code' );
     searchbtn = document.getElementById( 'searchbtn' );
     geocodestatus = document.getElementById( 'geocodestatus' );
     message = document.getElementById('message');
     resultsPane = document.getElementById('resultsPane');
     
  //Create a new geocoder object specifying a callback function
     geocoder = new MMGeocoder(processResults);
  
  // Add an Event Handler to show info boxes when the markers are clicked
     mapviewer.addEventHandler( 'click', function( type, target, point )
     {
        if( ! point && target.infobox_html )
        {
          if( target.infoBoxOpened() )
          {
             target.closeInfoBox();
          } else {
             target.openInfoBox( target.infobox_html );
          }
        }
     });
}

  function callGeocoder()
  {
     // create a new address object
     var address = new MMAddress();
     address.street = street.value;
     address.city = city.value;
     address.state = state.value;
     address.postal_code = postal_code.value;
     address.country_code = country_code.value;
    
     // clear any existing items from previous geocoding requests
     cleanUp();
     
     // inform the user a geocode is occuring
     updateGeocodeStatus('startGeocode');
     
     // perform the geocode
     geocoder.geocode(address);
  }

  function processResults() {
  // callback function registered with the Geocoder to handle geocoding results
     // inform the user a geocode has finished
     updateGeocodeStatus('endGeocode');
     // if an error occured, inform the user
     if (geocoder.error_code && geocoder.error_code != 'MM_GEOCODE_MULTIPLE_MATCHES') {
        message.innerHTML = 'We\'re sorry, the following error occured:<B>' + geocoder.error_code + '</B>';
        return false;
     }
     results = geocoder.result_set;
     var ol = document.createElement('ol');
     
     //loop through the result set
     for (var count=0; count < results.length && count < 10; count++) {
        var address = results[count].address;
        var li = document.createElement('li');
        //add a link for each result
        var anchor = document.createElement('a');

        anchor.href = '#';
        anchor.result_count = count;
        anchor.onclick = function () { moveToResult(this.result_count); return false; };
        anchor.appendChild(document.createTextNode(address.display_name));
        li.appendChild(anchor);
        ol.appendChild(li);
        
        //add a marker for each result
        var icon = MM_DEFAULT_ICON.copy();
        icon.image = 'http://www.multimap.com/share/mapviewer/i/q4/sm-marker'+(count+1)+'.png';
        var marker = mapviewer.createMarker(results[count],address.display_name,icon);
        //add an infobox for each result
        marker.infobox_html = address.display_name;
        markers.push(marker);
     }
     
     resultsPane.appendChild(ol);
     resultsPane.style.display = 'block';

     //display all the results
     var location = mapviewer.getAutoScaleLocation( markers );
     if( location.zoom_factor > 17 )
        location.zoom_factor = 17;
     mapviewer.goToPosition( location );
  }
  
  function moveToResult (count) {
     //move the map specified location and open the infobox
     mapviewer.goToPosition(results[count]);
     markers[count].openInfoBox(markers[count].infobox_html);
  }
             
  function cleanUp() {
     // Clean up the HTML containers
     message.innerHTML = '';
     while (resultsPane.firstChild) {
        resultsPane.removeChild(resultsPane.firstChild);
     }
     //remove any markers
     mapviewer.removeAllOverlays();
     markers = new Array();
  }
     
  function updateGeocodeStatus( type )
  {
     if( type == 'startGeocode' ) {
        // if the geocode is starting, disable the form inputs and inform the user
        geocodestatus.style.display = 'inline';
        disableFields(true);
     } else {
        // if the geocode is ending, enable the form inputs and inform the user
        geocodestatus.style.display = 'none';
        disableFields(false);
     }
  }
  
  function disableFields( bool )
  {
     // disable the user inout fields
     street.disabled = bool;
     city.disabled = bool;
     state.disabled = bool;
     postal_code.disabled = bool;
     country_code.disabled = bool;
  }

MMAttachEvent( window, 'load', onLoad );

For more information on the subject of Multimap API JavaScript code, please read the API Documentation at: http://www.multimap.com/share/mapviewerapidocs/1.1/index.html.

Note on Geocoding with the Multimap API V1.1

Please note that the Multimap API Version 1.2 is now available and we recommend that you upgrade to it: please contact your Multimap account manager for details, and review the example documentation for that version of the product at http://www.multimap.com/share/documentation/api/1.2/index.htm.

If you do not upgrade to the Multimap API Version 1.2, you must specify a country whenever you use Version 1.1 to geocode an address.

Further Help

If you require further help with your map API implementation, please contact our Customer Support team:

Australia, Sydney + 61 (0) 2 9262 6551
Great Britain, London +44 (0)20 7632 7777
United States, Boston + 1 617 423 4510
email: info@multimap.com

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

Australia, Sydney + 61 (0) 2 9262 6551
Great Britain, London +44 (0)20 7632 7800
United States, Boston + 1 617 423 4510
email: sales@multimap.com