Points (POIs) and InfoWindows

Points of Interest, commonly referred to as POIs, are specific locations that someone may find useful or interesting. In mapping applications, POIs and InfoWindows are usually paired to visually show locations and location detail.

This page covers the creation and stylization of the POI objects and InfoWindows. If you're interested in adding a group of POIs, GeoRSS or KML files to a map, see the Collections and KML and GeoRSS pages. Similarly, if you're interested in searching for POIs from MapQuest's hosted data or your own custom data tables and adding them to the map, see the Search page.

 

Basic POI

POI support is built into the basic API download. To place a POI on a map, use the following code where map is a reference to MQA.TileMap.

  /*An example using the MQA.Poi constructor. You will need to pass in an object containing 
  the lat (Latitude) and lng (Longitude) property defining where to place the POI on 
  the map.*/ 
  var basic=new MQA.Poi( {lat:39.743943, lng:-105.020089} );

  /*This will add the POI to the map in the map's default shape collection.*/ 
  map.addShape(basic);
 

 

 

 

Custom POI

In addition to the provided POI icon, it is possible to use custom images instead.

  /*An example using the MQA.Poi constructor. You will need to pass in an object containing the 
  lat (Latitude) and lng (Longitude) property defining where to place the POI on the map.*/ 
  var custom=new MQA.Poi( {lat:39.743943, lng:-105.020089} );

  /*An example using the MQA.Icon constructor. This constructor takes a URL to an image, 
  and the image's height and width.*/ 
  var icon=new MQA.Icon("http://developer.mapquest.com/content/documentation/common/images/smiley.png",32,52);

  /*This tells the POI to use the Icon object that was created rather than the default POI icon.*/ 
  custom.setIcon(icon);

  /*Set the shadow offset for your custom icon if necessary.*/ 
  custom.setShadowOffset({x:10,y:-25});

  /*This will add the POI to the map in the map's default shape collection.*/ 
  map.addShape(custom);
 

 

 

 

POI Alternate States

You can set an alternate state for a POI under certain conditions. The following example alternates the POI based on the mouseover and mouseout events by changing the icon used. All of the customizable attributes of a POI can have an alt state set by using the setAltPropertyName convention (e.g. setAltIcon is the alternate for setIcon). The MQA.Poi.setAltState(true||false) can be called directly -- no event is needed to use this functionality.

  /*Construct the POI*/ 
  var poi=new MQA.Poi( {lat:39.743943, lng:-105.020089} );
  poi.setAltIcon(new MQA.Icon("http://developer.mapquest.com/content/documentation/common/images/smiley.png",32,52));
  poi.setAltShadowOffset({x:10,y:-25});

  /*Sets the state of the POI to the alternate on mouseover*/ 
  MQA.EventManager.addListener(poi, 'mouseover', function(evt){
    evt.srcObject.setAltStateFlag(true);
  });

  /*Sets the state of the POI back to the original state on mouseout*/ 
  MQA.EventManager.addListener(poi, 'mouseout', function(evt){
    evt.srcObject.setAltStateFlag(false);
  });

  map.addShape(poi);
 

 

 

 

POI Decluttering

You can automate the decluttering of POIs when multiple locations are plotted in the same spot or close to one another.

  /*Construct the POIs and set automatic decluttering for each.*/ 
  var declutter1=new MQA.Poi( {lat:39.743943, lng:-105.020089} );
  declutter1.setDeclutterMode(true);

  var declutter2=new MQA.Poi( {lat:39.743943, lng:-105.020089} );
  declutter2.setDeclutterMode(true);

  var declutter3=new MQA.Poi( {lat:39.753012, lng:-105.018542} );
  declutter3.setDeclutterMode(true);

  /*This will add the POIs to the map in the map's default shape collection.*/ 
  map.addShape(declutter1);
  map.addShape(declutter2);
  map.addShape(declutter3);
 

 

 

 

InfoWindow

InfoWindows are the tooltips that pop up when the POI receives a mouseover event (default). Notice the difference between the mouseover and click actions on this POI as opposed to the example above.

Support of InfoWindows are included in the basic API download.

  /*Using the MQA.Poi constructor*/ 
  var info=new MQA.Poi({lat:39.743943, lng:-105.020089});

  /*Sets the rollover content of the POI.*/ 
  info.setRolloverContent('Sports Authority Field at Mile High');

  /*Sets the InfoWindow contents for the POI. By default, when the POI receives a mouseclick 
  event, the InfoWindow will be displayed with the HTML passed in to MQA.POI.setInfoContentHTML method.*/ 
  info.setInfoContentHTML('Home of the Denver Broncos');

  /*This will add the POI to the map in the map's default shape collection.*/ 
  map.addShape(info);
 

 

 

 

InfoWindow Configuration Options

You can configure InfoWindows in several ways and the below sample will give you an idea of its capabilities. To learn more about customizing the look and feel of your mapping application, visit the Customizing the User Interface page.

  /*Rollovers on hover and content on clicks*/ 
  var info1=new MQA.Poi({lat:39.740115, lng:-104.984898});
  info1.setRolloverContent('Rollover for Denver, CO');
  info1.setInfoContentHTML('Content for Denver, CO');

  var customIcon1=new MQA.Icon('http://www.mapquestapi.com/staticmap/geticon?uri=poi-1.png',20,29);
  info1.setIcon(customIcon1);
  map.addShape(info1);

  /*Setting only the content will display text in both the rollover and click window*/ 
  var info2=new MQA.Poi({lat:40.014981, lng:-105.269985});
  info2.setInfoContentHTML('Rollover & Content for Boulder, CO');

  var customIcon2=new MQA.Icon('http://www.mapquestapi.com/staticmap/geticon?uri=poi-2.png',20,29);
  info2.setIcon(customIcon2);
  map.addShape(info2);

  /*Setting only the rollover*/ 
  var info3=new MQA.Poi({lat:39.481706, lng:-106.037783});
  info3.setRolloverContent('Rollover for Breckenridge, CO');

  var customIcon3=new MQA.Icon('http://www.mapquestapi.com/staticmap/geticon?uri=poi-3.png',20,29);
  info3.setIcon(customIcon3);
  map.addShape(info3);

  map.bestFit();
 

 

 

 

Manual InfoWindow Toggling

You can toggle an InfoWindow using the MQA.Poi.toggleInfoWindow() and MQA.toggleInfoWindowRollover() functions.

  window.poi=new MQA.Poi({lat:39.743943, lng:-105.020089});
  poi.setRolloverContent('Sports Authority Field at Mile High');
  poi.setInfoContentHTML('Home of the Denver Broncos');
  map.addShape(poi);
  poi.toggleInfoWindow();
 

 

Toggle InfoWindow | Toggle InfoWindow Rollover

 

 

HTML POI

HTML POIs are essentially regular POIs except there are no icons and you are required to provide the HTML for the content. These are ideal for labeling and when simply changing the icon is not sufficient for your needs.

  /*This module isn't included with the base download so we need to load it prior to the first use on the page.*/ 
  MQA.withModule('htmlpoi', function() {
	
    /*Construct an instance*/ 
    var poi=new MQA.HtmlPoi( {lat:39.743943, lng:-105.020089} );

    /*MQA.HtmlPois will have their upper left corner placed with the lat/lng provided in the constructor. 
    Use the xOffset & yOffset to reposition. The final argument 'mqa_htmlpoi' is the default className 
    for MQA.HtmlPois. 
      ('valid HTML for your POI', xOffset, yOffset, 'CSS classNamne for div')*/ 
    poi.setHtml('Sports Authority Field at Mile High', 0, 0, 'mqa_htmlpoi');

    /*Sets InfoWindow rollover and contents as described above*/ 
    poi.setRolloverContent('Sports Authority Field at Mile High');
    poi.setInfoContentHTML('Home of the Denver Broncos');

    /*Adds the POI to the map*/ 
    map.addShape(poi);

  });
 

 

 

 

Events

As seen in the samples above, the addListener() event handler is used to listen for an event on the source object and call a custom function when the specified event occurs. Visit the Events page for a complete list of available Event Listeners.