Simple introductory tutorial for Mapstraction

| | |

It was time to start moving my old Google Maps pages over to version 2 of the API, and I thought I'd consider using another mapping solution (maybe Yahoo Maps or Microsoft). But then fate intervened and I happened to listen to a podcast from the Where 2.0 conference by Steve Coast. He talked about Open Street Map and more importantly to me, Mapstraction.

From their homepage

    Mapstraction is a library which provides a common API for Google, Yahoo! and Microsoft's javascript mapping APIs to enable switching from one to another as smoothly as possible.

This was just what I was looking for, so I thought I'd give it a try and detail the steps I took to get a simple map up and running:

Step 1: Get access to your Map API of choice

  1. Decide on the URL directory path where you are going to host your Maps -- the Google key is valid for a single directory. I decided on
  2. Sign up for the Google Maps API at
  3. You'll be given a (long) key that you include in the Javascript that loads the Google Map Javascript. Make a note of it, and the demo code they provide.
  4. Save the demo code on your web-server in the URL you provided, and give it a try -- mine is still online here - until this works, there is no point in getting into Mapstraction.

Step 2: Get the Mapstraction code and start the basic file

  1. I got the code from and saved it in the directory /common/
  2. My initial HTML file includes the initial call to the Google Maps Javascript (that contains our API key) as well as the Mapstraction Javascript:

    <title>First Mapstraction example</title>
    // We'll start out using Google
    <script src=""
    <script type="text/javascript" src="/common/mapstraction.js"></script>

Step 3: Get our basic 'hello-world' map running

We have our Map API Key, and the Mapstraction code in place, now lets create our first simple map. Open the complete sample code and follow along:

  1. The map will appear in a simple xHTML <div> element, with an ID that we'll set to 'simplemap' and use css to size:
         <div id="simplemap" style="width: 500px; height: 300px"></div>
  2. Time for more Javascript: We'll connect the 'simplemap' division we created above to a Google Map, using Mapstraction:
         var mapstraction = new Mapstraction('simplemap','google');
  3. Next we'll create a point called 'firstPoint' located in the middle of Toronto, to serve as the centre of our map when it is displayed:
         var firstPoint = new LatLonPoint(43.671844983221604,-79.38823699951172);
  4. Finally, we'll tell Mapstraction to display the map centered on the 'firstPoint' we created above, with a Google zoom level of 15
         mapstraction.setCenterAndZoom(firstPoint, 15);
  5. Upload your file and give it a try -- mine is still online here (Now might be a good time to remind you that Web browsers tend to have JavaScript consoles to help you troubleshoot any problems you may have, like forgetting to transfer the mapstraction.js over to the server...)

(Note that a lot of this content came from reverse-engineering

Next step: Tutorial part 2 - Adding map controls and markers