HTML Imagemaps

Author:David Fawcett
Contact:david.fawcett at
Last Updated:2008-10-08


The shpxy method of creating imagemaps uses MapServer query functionality to build a html imagemap. Just like a regular MapServer query, you send a query request and MapServer uses the templates to build a block of html that it sends back to the browser. The first example shows you how to build an imagemap based on a point layer. An example template for a polygon layer is also included.


  • MapServer mapfile
  • query template file
  • query header template
  • query footer template

Mapfile Layer Definition

Here is a simple mapfile for our example

NAME "myMapFile
SIZE 200 200
EXTENT 178784 4804000 772653 5483346

SHAPEPATH "/web/maps/data"
IMAGECOLOR 255 255 255

  IMAGEPATH "/web/maps/tmp/"
  IMAGEURL "/maps/tmp/"


  NAME "sites"
  TYPE point
  DATA 'aqiAreas'
      TEMPLATE "bodytemplate.html"
      HEADER "imapheader.html"
      FOOTER "imapfooter.html"

You can see that we have a mapfile with one point layer, and that it contains references to three query templates.


In MapServer, the query header and footers get processed only once. The main query template, ‘bodytemplate.html’ in this example, gets processed once for each record in the record set returned by the query.

Point Layers

Here is the query header, ‘imapheader.html’. It creates the opening tag for your html imagemap.

<map id="mymap" name="mymap">

Here is the query template, ‘bodytemplate.html’. It creates the body of the html imagemap.

<area shape="circle" coords="[shpxy precision=0 proj=image yf=",7" xf=","]" href="http://my.url/mypage.cfm?region=[NAME]" title="[NAME]" alt="[NAME]">

This template is used to create circular imagemap elements for a point layer. NAME is a fieldname in the data source, the value for NAME for each individual record gets substituted as the template is processed. The href specifies the URL link if the element is clicked. Title and alt will display the value when an element is moused over.

The resulting html element looks like

<area shape="circle" coords="80,103,7" href="http://my.url/mypage.cfm?region=Northern" >

The key part here is

coords="[shpxy precision=0 proj=image xf="," yf=",7"]"

This is where MapServer will substitute the image coordinates for that query record. With Precision=0, the coordinates will be integers.

You also see shpxy template formatting options ‘xf’ and ‘yf’. ‘xf=”,” tells MapServer to place a comma after the x coordinate. ‘yf=”,7” after the y coordinate. This is done to specify a radius of 7 pixels for the circle. More options can be found in the Template Reference.

The query footer template simply adds the closing tag for the html imagemap


Polygon Layers

Here is a query template for a polygon layer

<area shape="poly" coords="[shpxy precision=0 proj=image]" href="http://my.url/mypage.cfm?ID=[SITE_ID]" title="[NAME]" alt="[NAME]">

Request URL

To get the imagemap, you need to send a GET or POST request to MapServer with several URL variables defined. The below URL tells MapServer where the mapfile is located, what layer we are querying, and that we are using nquery mode to return multiple results.


Additional Notes

If you use separate map files to generate your imagemap and your map image, make sure that the EXTENT and SIZE specified in both mapfiles are identical. If they are not, your features will not align properly.