Adding custom background layers to Leaflet or Google Maps

When you create a Leaflet or Google Map with GPS Visualizer, the "map type" menu in the upper-right corner of the map contains many options. (And the list is always growing; if you find out about a publicly-accessible map layer that might be a good addition, send a note to the contact address at the bottom of this page.)

But sometimes you might have a specific need for a layer that doesn't warrant inclusion in the universal list. No problem: you can alter your map to include any map server that uses Google-style "Web Mercator" tiles, either by entering some code in the "Custom JavaScript before the map loads" box in the map input form, or by editing the source of the map after you create it. This page will show you how.

Got a tile URL already?

If you just need to add one simple custom layer to a Leaflet or Google map and you already have a URL template with places for {x}, {y}, and {z}, enter the URL here:

Editing a map's HTML to add one simple layer

First, open your HTML map in a text editor and look for the section of code containing gv_options.map_type_control. In the first example, we'll create a map with a very specific custom layer: aerial photos of the damage done by a tornado in Moore, Oklahoma in May 2013.

The map tiles are stored on the Google Crisis Response server, and each tile's URL looks something like this:

http://mw1.gstatic.com/crisisresponse/2013/2013-oklahoma-tornado/digitalglobe/OK_PO_1194054_GE1_2013_05_23_maptiles/1877_3235_13.png

Those last three numbers are the X (longitude), Y (latitude), and Z (zoom) "coordinates" of the tile. Typically, Z will be the smallest number (almost always between 0 and 20); the others are X and Y, but not always in that order. (Sometimes there will be documentation that tells you explicitly which is which.) In the custom code that you insert into your map, you'll replace the numbers with {X}, {Y}, and {Z}; those curly brackets are important.

For our simple tornado damage example, we can incorporate the tiles into our map by adding a statement like this:

gv_options.map_type_control.custom = [
  {
    id:"MOORE_TORNADO"
    ,menu_name:"Moore tornado"
    ,url:"http://mw1.gstatic.com/crisisresponse/2013/2013-oklahoma-tornado/digitalglobe/OK_PO_1194054_GE1_2013_05_23_maptiles/{X}_{Y}_{Z}.png"
    ,credit:"Imagery from Google Crisis Response"
  }
];

The url parameter is the most important; menu_name is useful because it defines how your new map shows up in the map type menu; credit is what shows up at the bottom of the map, and it can include HTML code such as hyperlinks. You'll want to remember what you choose for the id if you want the map to initially load with your custom map visible, because you would place that value in the gv_options.map_type variable.

Putting an existing background behind the custom layer

There's an minor problem with the example map above: the custom layer only covers a small area, and it's blank outside that area. Ideally, we'd like to show a normal map background "behind" the tornado damage imagery. We can do that by adding a background parameter to the gv_options.map_type_control statement. The value of background will be one of GPS Visualizer's map codes or map code aliases; you can find a list of all the current map types here. In this case, we'll use a "hybrid" map view; GPS Visualizer's shortcut for that is "GV_HYBRID".

Adjusting the opacity of the custom layer

You can also have your custom layer be less than 100% opaque, so that the background partially shows through. To do that, just add an opacity parameter to your custom map definition.

[Return to top]

[Return to the Tutorials index]

Return to the GPS Visualizer home page