File Under: Location

Multi-map with Mapstraction

It seems every mapping website has an API these days. Google, Yahoo, Microsoft, Mapquest… how do you choose? With Mapstraction, you don’t have to.

Mapstraction is an open source abstracted JavaScript mapping library. You can write mapping code once, then switch between map providers by only changing two lines. Mapstraction is maintained by a group of geocode lovers who want to give developers options when creating maps.

To help you on your way to using Mapstraction, we’ll simply create a map we can display on a web page, and then add a marker to denote a particular location.


  1. What You’ll Need
  2. How to Proceed
    1. Step 1: Get started
    2. Step 2: Adding in the Map
    3. Step 3: Adding Markers
    4. Step 4: Changing Map Providers
  3. Where to go from here

What You’ll Need

  • Knowledge of JavaScript, CSS and HTML
  • Mapstraction JavaScript file
  • At least one map provider API key (they’re free). I’ll be using Google in most examples. Get a Google API key here.

How to Proceed

Step 1: Get started

Once you have a Google API key, you’ll need to grab the latest Mapstraction JavaScript file. Got it?

Now create a file in the same directory as mapstraction.js containing the following HTML:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "">

<html xmlns="" xml:lang="en" lang="en">


<title>My Mapstraction Map</title>

<script src="" type="text/JavaScript"></script>

<script src="mapstraction.js"></script>


<h1>My Mapstraction Map</h1>

<div id="mapstraction"></div>



Remember to put your API key in place of YOURAPIKEYHERE. The above code loads the Google API and the Mapstraction library, but we don’t have a map just yet.

Mapstraction is loaded, but we have yet to add the map

Mapstraction is loaded, but we have yet to add the map

Step 2: Adding in the Map

To tell Mapstraction how and where to add a map, we need to include some JavaScript between the head tags near the top of our HTML file. Try this function, initialize_mapstraction:

<script type="text/JavaScript">
var mapstraction;

function initialize_mapstraction()
	// Create a map object
	mapstraction = new Mapstraction('mapstraction', 'google');
	// Create a latitude/longitude point
	var ll = new LatLonPoint(37.780764,-122.395592);
	// Display map centered on above point, zoomed to show most of San Francisco
	mapstraction.setCenterAndZoom(ll, 12);

Here, we tell Mapstraction to use the element with the id “mapstraction” as our map. In the HTML code we created in step one, we included an empty div with the “mapstraction” id. In the second part of the script, we create a latitude/longitude point that represents the Webmonkey offices. Then, we set that point as the center and set a zoom level of 12, which is enough to still see most of San Francisco.

Mapstraction requires us to set the size of our map. We use a little CSS to do this. You can add this to your CSS file, or add this code between your head tags:

	width: 500px;
	height: 300px;

Finally, we need to call the initialize_mapstraction function. To do this, add an onload attribute to the body tag of your HTML document, like so:

	<body onload="initialize_mapstraction()">

Reload the HTML file and you should see San Francisco. You may notice that your map looks exactly like a Google Map. That’s the point. Mapstraction doesn’t have any maps of its own. It merely provides a way to easily switch between map providers. I’ll show this later in the tutorial and explain why you might want to do this.

Mapstraction adds a Google map to the web page

Mapstraction adds a Google map to the web page

Step 3: Adding Markers

So far we’ve created a very simple map. You can click and drag it around to see more of the Bay Area, but for the most part our map is boring. Let’s spice it up with a map marker.

To place marker on our map, we’ll need to add some more JavaScript code to the initialize_mapstraction function. Add these lines after the setCenterAndZoom line:

// Create map marker from above point
var marker = new Marker(ll);

// Include text in info bubble shown when marker is clicked
marker.setInfoBubble("<h2><strong></strong></h2><p>Home of Monkeys</p>");

// Add marker to the map

Reload your HTML file and you’ll see a little red marker in the center of the map. That’s the Webmonkey offices. Our marker uses the same latitude/longitude point we created in the previous step to center the map.

Now try clicking the marker. Surprise! We also included an interactive message. Mapstraction calls this an info bubble. In the code, you may notice the setInfoBubble line. You can put anything you want between the quotes. Try changing the text–we don’t mind!

A red marker is added to the map

A red marker is added to the map

Step 4: Changing Map Providers

Now that we have a working Mapstraction example, let’s use the full power of an abstracted library by switching map providers.

There are many reasons you might decide to change providers down the line:

  • Current provider might change the terms of service
  • Your map could become too popular and use up too many map views
  • Current provider quality might get worse, or they might put ads on your map
  • New provider might have prettier maps
  • You might get bored of current provider, or come up with a reason that makes sense to you

The promise of Mapstraction is to only have to change two lines of code. Imagine if you had a large map with many markers and other features. It could take a lot of work to manually convert the map code from one provider to another.

In this example, we’ll be switching to Microsoft Virtual Earth, which happens to not even require an API key.

The first line you need to change is the call to the API JavaScript. Remove the script line that calls to and replace it with this line:

<script src=""></script>

Then, inside the initialize_mapstraction function, replace “google” with “microsoft” where the new map object is created. Here’s the entire line to include:

	mapstraction = new Mapstraction('mapstraction', 'microsoft');

Reload the HTML file and like magic, the same map is now displayed as a Virtual Earth map.

A simple edit to the code changes our map provider from Google to Microsoft

A simple edit to the code changes our map provider from Google to Microsoft

Where to go from here

Despite showing off Mapstraction’s provider-switching magic, our map is still fairly simple. Here are a few ways to jazz it up.

Give your users a way to zoom in an out. Mapstraction provides both large and small zoom controls. This line adds the large one:


And this the small one:


You can add these, and several other controls, in one line using the addControls function

One of my favorite Mapstraction features is automatic centering and zooming. When called on a map with multiple markers, Mapstraction calculates the center point of all markers and the smallest zoom level that will contain all the markers. So much snazziness, in one simple line:


Draw lines on a map, automatically filtered out certain markers, and more. The Mapstraction community is continually adding new features. Check out their homepage or their API documentation.