Multimap API v1.1 Example

Geocoding - Basic example

This example shows the simplest way of combining the Mapping and Geocoding functionality of the Multimap API, including the use of the events startGeocode and endGeocode.

Addresses can be passed directly within any function that supports MMLocation; such as drawAndPositionMap and goToPosition.

mapviewer.drawAndPositionMap( new MMLocation( new MMAddress( { city : 'London', country_code : 'GB'} ), 11 ) );

The event types startGeocode and endGeocode are provided to allow you to detect when the asynchronous geocoding process has started and ended.

It should be noted that this is a very basic example of using the Multimap API Geocoder and should be used with great care. When used in this fashion, if the Geocoder returns multiple results the map viewer will automatically select the first entry, which may not be the result the user was expecting.

If you would like to learn how to handle multiple results by working directly with the Multimap API Geocoder, take a look at the Using the Multimap API Geocoder page.

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 view this in your browser you should see a Multimap draggable map initialy centered as a result of a geocoding request for Multimap's UK office in London, Great Britain.

Links are provided to move the map to Multimap's offices in Boston MA, US and Sydney, NSW, AU, all of which are automatically generated as a result of a geocoding request.

The Map

Go to London

Go to Boston

Go to Sydney

The Code

There are three parts to the code below. The first is the line that links 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

<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 Movement Links -->
<p><a href="#" onclick="mapviewer.goToPosition( new MMLocation( new MMAddress( { street : '165 Fleet Street', city : 'London', postal_code : 'EC4A 2DY', country_code : 'GB'} ) ) ); return false;">Go to London</a></p>
<p><a href="#" onclick="mapviewer.goToPosition( new MMLocation( new MMAddress( { street : '31 St James Avenue', city : 'Boston', state : 'MA', postal_code : '02116', country_code : 'US'} ) ) ); return false;">Go to Boston</a></p>
<p><a href="#" onclick="mapviewer.goToPosition( new MMLocation( new MMAddress( { street : '36 Carrington Stree', city : 'Sydney', state : 'NSW', postal_code : '2000', country_code : 'AU'} ) ) ); return false;">Go to Sydney</a></p>
<img id="geocode_status" style="display : none;" src="/share/mapviewer/i/loading.gif" alt="Loading..." />

The JavaScript code

var mapviewer, marker;

function onLoad()

{
  //Add the map 
  mapviewer = new MultimapViewer( document.getElementById( 'mapviewer' ) );

  //Add three new event handlers to detect when a geocode request has been made so we can inform the user
  mapviewer.addEventHandler( 'startGeocode', updateGeocodeStatus );
  mapviewer.addEventHandler( 'endGeocode', updateGeocodeStatus );
  mapviewer.addEventHandler( 'endGeocode', endGeocode );

  mapviewer.drawAndPositionMap( new MMLocation( new MMAddress( { city : 'London', country_code : 'GB'} ), 11 ) );
}

function updateGeocodeStatus( type )
{
  var gs = document.getElementById( 'geocode_status' );

  if( type == 'startGeocode' ) {
     //if we are starting a geocode request, display the flashing "Geocoding..." message
     gs.style.display = 'inline';
  } else {
     //if we are ending a geocode request, hide the flashing "Geocoding..." message
     gs.style.display = 'none';
  }
}
  
function endGeocode( type, target, location, error_code ) {
  if( error_code ) {
     alert( 'There was a problem geocoding that address: '+error_code );
  } else {
     mapviewer.removeOverlay( marker );
     marker = mapviewer.createMarker( location, location.address.toString() );
  }
}

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