How To Overlay Custom Maps Using the Google Maps API

By popular request here is a tutorial on how to use the Google Maps API to put in your own maps (tiles). You can put in transparent tiles over the Google Tiles, put your tiles under the Google road tiles (from Hybrid mode), put transparent tiles over your own base tiles, or simply replace Google’s tiles all together. Your choice.

Warning: For this tutorial I assume you know how to make a function that returns the correct image URL for each tile based on Google’s numbering system. I explain how to use a WMS service to generate tiles for you here.


There has been a crazy amount of people using the Google Maps API to integrate their own data into a Google Maps type application. This has been accomplished by mainly using Google’s Overlays. Initially Google documented the Marker type and the Polyline type. However, if you shove a ton of these overlays on a single map, your browser gets bogged down very quickly. Here lies a problem. JavaScript has limitations with speed. It just can’t do things that fast. There are many solutions. One, outlined below, uses image tiles, either pre-rendered like Google or rendered on-the-fly via a server-side script.


To implement this solution here’s what you need:

  • Access to a web server
  • A Google Maps API Key
  • A unique URL for each tile of your custom map. (images themselves or by using a server-side scripting language)
  • A JavaScript function that maps Google’s x, y, and zoom coordinates along with possible other parameters (tile size, etc) to that URL

You could make a bunch of tiles, but if you know what you are doing it would be a lot easier if you set up a WMS service and possibly a caching system like I have done. I’ll explain the details of this later. Subscribe to my Google Maps Blog via RSS or HTML for updates.

Before you start

  1. learn the basics of the Google Maps API.
  2. Figure out the URL to your custom map tiles and the function to map them

In the code

  1. Create a new Gmap object with some standard controls like so
  2. var map = new GMap(document.getElementById("map")); //associate the Gmap object with your div with an id of map

  3. Create a new map spec based on one of the existing ones.
  4. Here, we use a special function which will copy all of the properties of one of the mapTypes to your new map type.

    // Copy Object Function from
    function copy_obj(o) {
    var c = new Object(); for (var e in o) { c[e] = o[e]; } return c;
    var umType = copy_obj(map.mapTypes[2]); //currently set to the hybrid mode, but could change

  5. Tell the spec if you want an overlay or not
  6. umType.hasOverlay = function () {return true;};

  7. Tell the spec what URL(s) to use
  8. There are two function which tell Gmaps where images are located: getTileURL and getOverlayURL. Since you copied an existing mapType, these function will already be defined, and if you want to stick with the default, just don’t override the function. But, if you want to override both the tiles and the overlay tiles, define the following functions like so.

    umType.getTileURL = function (x, y, zoom){
    //put your function code here which returns the URL to the image you want as your base
    umType.getOverlayURL = function (x, y, zoom){

    //put your function code here which returns the URL to the image you want overlayed

  9. Add the map spec to the list
  10. map.mapTypes.push(umType);

  11. Set the map type to be the current map type if you wish
  12. map.setMapType(umType);

  13. Put some controls on your map if you wish
  14. map.addControl(new GLargeMapControl());
    map.addControl(new GMapTypeControl());

  15. Focus your map on the University of Michigan Campus… hehe… GO BLUE!
  16. map.centerAndZoom(new GPoint(-83.7381362915039, 42.27702299695707), 2); //University of Michigan Campus

That’s about it. Leave comments if you have questions. More details about the function that I use to get images will be coming later this week.

Update: Here is how to get the Google Maps interface to take images from WMS.

© 2005 Kyle Mulka

16 Responses to “How To Overlay Custom Maps Using the Google Maps API”

  1. Hao Says:

    mmm. very cool. you are a genius.

  2. JC Says:

    Yup, this is excellent. Looking forward to the next installment for working out getting the images. Can we get this info on Mapki also?

  3. Massimo Says:

    Hi, I like the idea a lot and I’d really like to see how you interact with a Map Server.
    I’ve done some testing to bridge a WMS service with GoogleEarth and I’d like to see how you did it with GMaps.

    thanks and kudos

  4. Kiran Patravali Says:

    i want help in using google maps

  5. jane Says:

    Cool! Thanks, I borrowed your code on how to set the mapType mode.

    look what I did:
    you can change zip code in houston, like 77027, 77025, 77479, etc to see random top 10 MLS listings on market.

  6. subu Says:

    I hav to send a request through google,which accesses the map server and this map server should call my shape file and then retrive the request…can that be done???

  7. Kyle Mulka Says:


    In order to for me to help you, you will need to be more specific and explain what it is you want to do. Are you taking about UMN MapServer?



  8. nelson Says:

    Hello Kyle,

    Thanks so much for your excellent work. I am putting together a map site for a non-profit, and I adapted the javascript that Just ( adapted from you).

    The map works great, but I am trying to add some functionality. I am not a javascript programmer and I am getting frustrated.

    I’d like to add a pull-down list that will take you to pre-set locations on the map, so I adapted a script from google pedometer that does this by doing a GotoAndZoom ( However, the map can’t re-initialize. I can’t see what is wrong.

    I also incorporated a function to allow url queries to set the location and zoom. This works great when the page is loaded, but if you then try to switch between map types the zoom goes to the max.

    Any thoughts? The page is:
    Here is the link to the scripts:

    Thanks much,

  9. nelson Says:

    I changed the address of the page with the non-working pull-down list to this:


  10. nelson Says:

    Okay, i got the pulldown menu to function. But the map still redraws at full zoom when you change map types after going to a queried location. Somehow the extent isn’t being remembered.

    Also, at higher zooms (further out) the wms served shapefiles render further and further to the north. This must be a problem with the projection, but I can’t figure out what it should be.

    Any help would be greatly appreciated.


  11. Harish Balakrishnan Says:


    I do not know why mine is not working. I have created a folder scvmap in which i have index.php , and few images renamed 1_1_X where X

  12. Kyle Mulka Says:

    Hi Harish,

    You’ll have to give more detail. Please email me with questions.


  13. Harish Balakrishnan Says:

    Hi Kyle,

    Hope you had a great weekend with a wonderful sunday.
    Wishes and thanks in advance for the consideration and
    I had send a query mail to your email box.Looking forward to hear from you where did i go wrong while implementing thie ‘custom maps’

    Thanking you once again and wishing a great weekahead,


  14. Kyle Mulka’s Weblog » WMS in Google Maps Says:

    […] As a follow up to my previous tutorial on how to use your own custom map tiles in Google Maps, here’s the code (function) you need to convert Google tile x, y, and zoom into a suitable WMS URL. Just stick this code in the getTileURL(x, y, zoom) or getOverlayURL(x, y, zoom) functions and tweek some of the parameters to your needs. […]

  15. Gaurav Says:

    sir i want to use google map API with my mapserver layers can u give me some demo code please so that i can do it

    waiting for your reply

  16. Mir Nauman Tahir Says:

    solves basic issues with using overlays. and gives a step by step way of adding images to google maps

Leave a Reply