MapBox

Why Use Google Maps API and MapBox Together?

Google Maps and MapBox are not mutually exclusive tools, you can use both to create custom, fast maps for your website. If you already use Google Maps on your website but would like your map to look like the "World Dark" maps here http://mapbox.com/tileset/world-dark or if you'd like to add a transparent overlay like the US Congressional Districts tiles here http://mapbox.com/tileset/us-congressional-districts you can do so using MapBox tiles while keeping the rest of your Google code.

There are advantages to using the Google Maps API, such as its speedy javascript library which makes navigating and zooming a map very quick. Google's API also provides for numerous other options like adding markers and popups to your map. There are also advantages to using MapBox custom tiles, such as showing specific details on the map which are pertinent to your application and not offered by Google's default map types.

How It Works - High Level Overview

When you use the Google Maps API, Google offers a handful of map types which you can use as the map type for your maps implementation. If you look at the "Constants" section on http://code.google.com/apis/maps/documentation/reference.html#GMapType you will see the names of several map types, including map types for the sky, moon, and mars. There are about six map types that work for the regular world. When you make a map with the Google Maps API, you can specify which map type you want to use. You can choose from one of the types Google provides, or, you can choose to use a custom map type provided by a third party, like MapBox.com. In order to use a custom map type, you must change some of the code used to implement the map you currently use. The following examples describe how to create an entirely new map implementation with Google's Maps API and MapBox, but if you have an existing Google Map this documentation should give you enough information to conjecture what you need to change to get your custom maps loading from MapBox instead of using one of Google's default map types. At the end of this example is another short example on how to add transparent overlay tiles from MapBox, like the US Congressional Districts or the Afghanistan MRGS tiles.

A basic implementation of a Google Map that uses a custom map type requires you to inform the Google API of a few details:

• Where to find the custom tiles for your custom map type
• The maximum, minimum, and default zoom levels supported by the custom map type
• The map center latitude and longitude you want to use

The follow examples also do the following:

• Adds the default Google Maps UI to the map

Hello, World with MapBox and Google Maps API

Google provides a "Simple Map" example of implementing a Google Map at http://code.google.com/apis/maps/documentation/examples/index.html. The following example will start with the code from the "Simple Map" example and show you how to modify it to use a custom map type using tiles from MapBox.com.

MapBox "World Light" tiles and Google Maps API

Google's "Simple Map" example code consists of the following:

You will need to follow these steps in relation to the "Simple Map" code above in order to implement the same example using the MapBox "World Light" tile set instead of Google's default map type.

1. Swap out the API key ABQIAAAAzr2EBOXUKnm_jVnk0OJI7xSosDVG8KKPE1-m51RBrvYughuyMxQ-i1QfUnH94QxWIa6N4U6MouMmBA to match your own API key(go here if you need to sign up for a google maps api key).

   <script src="http://maps.google.com/maps?file=api&amp;v=2&amp;sensor=false&amp;key=PASTE-YOUR-KEY-HERE" type="text/javascript"></script>

2. Add the MapBox layer helper Javascript to your page, below the Google Maps javascript

   <script src="http://js.mapbox.com/g/2/mapbox.js" type="text/javascript"></script>

3. Add the MapBox layer to your Google Map so the javascript in the head of the page should look like

       function initialize() {
      if (GBrowserIsCompatible()) {
        var options = {minZoom: 11, maxZoom: 17};  
        var custommap = GMapBox('dc-nightvision', 'Night', options);
        map.setCenter(new GLatLng(38.9168770,-77.0359010), 15)
        map.addMapType(custommap);
        map.setMapType(custommap);
        map.setUIToDefault();
      }
    }


   Note the arguments to the GMapBox object:

   var custommap = GMapBox('dc-nightvision', 'Night', options);


"options" should be an object that may contain:

• minZoom - the minimum zoom of the map
• maxZoom - the maximum zoom of the map
• overlay - true or false, whether a transparent overlay or not (more on this below)
• type - filetype, default png (only for transparent overlays)
• opacity - int opacity of tile overlays (only for transparent overlays)
• osm - true or false, whether to credit OpenStreetMap for map data

The final code should look like the following, but using your own API key instead of the placeholder text:

Add transparent overlay to Google Map

You can use most of the same code above to add a transparent overlay to a Google Map instead of adding a whole custom map type.

An example that adds the US Congressional Districts overlay to the map is as follows:

Notice you must provide more options in the options object, and that you must call addOverlay() with the GMapBox object instead of calling addMapType()

You can find other examples which implement the "World Light", "DC Nightvision" and "Afghanistan Winter" tile sets at on GitHub at http://github.com/developmentseed/GMapBox

Related Resources and Sources

• Google Maps API Reference http://code.google.com/apis/maps/documentation/reference.html
• Google Maps API Examples http://code.google.com/apis/maps/documentation/examples/index.html
• Google Maps API Custom Map Types Reference http://code.google.com/apis/maps/documentation/overlays.html#Custom_Map_...
• Google Maps API Tutorial - Custom Map Types http://econym.org.uk/gmap/custommap.htm
• Mapki - Add Your Own Custom Map http://mapki.com/wiki/Add_Your_Own_Custom_Map