Add Your Own Custom Map

From Google Mapki

Adding a custom map is a very simple process with the latest version of the Google Maps API. The latest revisions of Version 2 implement several JavaScript classes that make the addition of your own custom map layer very simple. This guide is meant to describe how to put these classes together in order to implement the end goal: a custom map layer that users can switch to in your Google Map API application.

[edit] Custom Maps in GMap V2

Google's V2 of the map API implements Map Types very differently than how they implemented them in V1. If you are building a new map or migrating from V1 of the API, there are a few things to be aware of and a new way to create a custom map.

Note: For people migrating a Custom Map from v1 to v2 take note that Google has changed the zoom stack! Under v1 of the API, the furthest out zoom is 17 and the closest is 0. In order to facilitate unlimited zoooming-in Google has wisely flipped the zoom stack so that 0 is the furthest out. This has strong implications for those who have already created map tiles. Current "zoom" values will work in inverse. Google is helping compensate for this change via the method getTileUrl(), as shown below. Ideally, if you already have tiles, you might consider renaming them to make your custom map type implementation as clean as possible. If you are making new tiles, you should number them in accordance with the new zoom schema.

[edit] Overview

Custom Maps require that you instantiate instances of several different classes that have yet to be given examples in the API documentation. First, you must create a collection of copyrights, give those copyright collections to one or more tile layers, then pass those tile layer(s) off to create a map type. Once a map type has been created, it can be added to your map instance in your JavaScript code.

[edit] Copyrights

Google allows every set of tiles to have a string of text associated with it that signifies the copyright owner for that set of tiles. Since there can be more than one owner for a specific set of tiles (this usually happens if your tiles are compiled from several different sources), Google asks that you group the GCopyrights into what they call GCopyrightCollections.

[edit] Create a GCopyright

For each of our tile layers, we need to specify at least one copyright text. The GCopyright constructor follows the following form:

var copyright = new GCopyright(<index>, <bounds[GLatLngBounds()], <minZoom>, <copyrightText>);

For example:

var copyright = new GCopyright(1,
                              new GLatLngBounds(new GLatLng(-90, -180), 
                                                new GLatLng(90, 180)),
                              0,
                              "©2006 RunwayFinder.com");

[edit] Add the GCopyright to a GCopyrightCollection

Next, we need to add the newly-created GCopyright instance to a GCopyrightCollection. We use GCopyrightCollections to allow for showing more than one copyright text for a particular set of tiles. The parameters for the GCopyrightCollection constructor are the following:

var copyrightCollection = new GCopyrightCollection(<prefix>);

Once we create an instance of the GCopyrightCollection, we need to add our previously created GCopyright to the collection. For example:

var copyrightCollection = new GCopyrightCollection('Chart');
copyrightCollection.addCopyright(copyright);

[edit] Tile Layers

Once we create the copyright meta-data, we need to create a layer that will represent the actual images of the custom map type. In order to create a tile layer, you need to know what the minimum and maximum zoom levels are for your tile images, along with the URL that you plan on using for creating or downloading your tile images.

[edit] Create a GTileLayer array

var tilelayers = [new GTileLayer(copyrightCollection , 3, 11)];
tilelayers[0].getTileUrl = CustomGetTileUrl;

function CustomGetTileUrl(a,b) {
	var z = 17 - b;
	var f = "/maps/?x="+a.x+"&y="+a.y+"&zoom="+z;
	return f;
}

The values 3 and 11 specify the minimum and maximum zoom levels. When the user switches to your custom map, the current zoom level will be changed if needed to fit in this range.

A function such as CustomGetTileUrl in the example above can be used to map the tile coordinate "a" and zoom level "b" to an URL for a map tile. This example shows how to map the old v1 zoom levels to the new v2 zoom levels, i.e. newzoom = 17 - b.

[edit] Custom MapType

[edit] Create a GMapType

var custommap = new GMapType(tilelayers, new GMercatorProjection(12), "Chart", {errorMessage:"No data available"});

The value 12 represents the number of zoom levels needed. It needs to be at least one more than the largest zoom level, e.g. (max_zoom_level + 1). If you want polylines to work, it must be 18 or above (see this discussion). The string "Chart" will be prepended to the copyright message specified in the GCopyright constructor. The error message will be displayed if there is an error trying to retrieve the map tile.

[edit] Add the custom map type to the map

map.addMapType(custommap);

[edit] Code Overview

var copyCollection = new GCopyrightCollection('Chart');
var copyright = new GCopyright(1, new GLatLngBounds(new GLatLng(-90, -180), new GLatLng(90, 180)), 0, "©2006 RunwayFinder.com");
copyCollection.addCopyright(copyright);

var tilelayers = [new GTileLayer(copyCollection, 3, 11)];
tilelayers[0].getTileUrl = CustomGetTileUrl;

function CustomGetTileUrl(a,b) {
	var z = 17 - b;
	var f = "/maps/?x="+a.x+"&y="+a.y+"&zoom="+z;
	return f;
}

var custommap = new GMapType(tilelayers, new GMercatorProjection(12), "Chart", {errorMessage:"No chart data available"});
map.addMapType(custommap);

[edit] Improving the Performance in IE

Internet Explorer has a two connection limit per domain name, but allows up to 8 connections total, so when the user is panning and zooming the map, only two tiles can be downloaded at at time. A work around to this is to serve the tiles from subdomains. For instance if your tiles are in located at www.mydomain.com/tiles/, then create 3 subdomains that all resolve to the same location (e.g ts1.mydomain.com/tiles/, ts2.mydomain.com/tiles/,ts3.mydomain.com/tiles/ should all be symlinked to www.mydomain.com/tiles/) The next step is to modify the CustomGetTileUrl function.

function CustomGetTileUrl(a,b) {
	var z = 17 - b;
       var w = ((a.x + a.y) % 3)+1;
	var f = "http://ts" + w + ".mydomain.com/tiles/?x="+a.x+"&y="+a.y+"&zoom="+z;
	return f;
}

[edit] More Info

Mike's custom map tutorial

Tool for easily creating custom maps

Ruby on Rails specific tutorial with detailed steps on how to create custom maps.