Pushpin LE API Documentation

Pushpin™ LE API Documentation (Version 0.8)

Getting a Map
Adding a Pin to the Map
Adding Controls
Opening an Info Window
Adding Overlays
Handling Clicks
Attaching Events
Opening an Info Window above a Marker
Creating Custom Icons
Getting Multiple Maps on One Page
Address to Point (Geocoding)
Creating a Map in Demo Mode

Class Reference

PMap
PMarker
PPolyline
PIcon
PEvent
PGeocoder
PAddress
PPoint
PSize
PBounds
PLargeMapControl
PSmallMapControl
PSmallZoomControl
PGetVersion

View Documentation for Version 1.3 Version 1.2 Version 1.1 Version 1.0 Version 0.9
If you're unsure which version of the API you're using, use the global function PGetVersion().

Getting Started

Placebase's Pushpin™ LE provides an easy to use JavaScript Application Programming Interface (API) for embedding scrollable maps into your website. The following code example shows how to create a 500x300 pixel scrollable map centered on Los Angeles:


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"  xmlns:v="urn:schemas-microsoft-com:vml" >
  <head>
	<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>

	<title>Pushpin LE JavaScript API Example: Getting Started</title>
	<script src="http://api.pushpin.com/js?key=2CF42A57ABCE28B359E57E991B18AEB8"
			type="text/javascript">
	</script>

	<script type="text/javascript">
	//<![CDATA[

	function onLoad() {
		// Creates a map and centers it on Los Angeles.

		var map = new PMap(document.getElementById("map"));
		map.centerAndZoom(new PPoint(-118.055, 33.952), 3);
	}

	//]]>
	</script>
  </head>

  <body onload="onLoad()">
	<div id="map" style="position: relative;
		width: 500px; height: 300px; border: 1px solid #979797"></div>
  </body>
</html>

Here is a link to a page where you can view this example in action (start.html).

The URL in the example above, http://api.pushpin.com/js?key=2CF42A57ABCE28B359E57E991B18AEB8, is the location of the pushpin code. In order for that URL to work, you will need a valid key value. Upon subscribing to Pushpin LE you will receive a key. This key will only work for web pages served from your site.

More Examples

Getting a Map

As shown in the Getting Started example above, getting a map consists primarily of two lines of JavaScript code, one to construct the PMap object, and another to center and zoom the map at a particular geographic coordinate (-118.055, 33.952) at zoom level 3:

var map = new PMap(document.getElementById("map"));
map.centerAndZoom(new PPoint(-118.055, 33.952), 3);

View example (start.html)

Adding a Pin to the Map

The PMarker object is used to add a Pushpin to a point on the map.

View example (addpin.html).

The example above uses the same method as the Getting A Map example to center and zoom the map to a geographic coordinate (-118.099, 33.95), but also adds a point to the map. The PMarker constructor takes a PPoint object. Once created, the marker is added to the map using the map.addOverlay() method. The following two lines of code from this example creates a marker at a given point, and overlays that marker on the map:

var marker1 = new PMarker(point1);
map.addOverlay(marker1);

Adding Controls to the Map

The map object offers methods that overlay a variety of controls on the map. The following example shows how to add simple zoom in / zoom out and pan controls to the map. Use 'View Source' in your browser when viewing this example to see how it is coded using the Pushpin LE API.

View example (smallmapcontrol.html).

The example above shows how to add a small map control (PSmallMapControl) to the map. The control allows users to zoom and pan. The following line of code adds the control to the map:

map.addControl(new PSmallMapControl());

Other types of controls can also be added to the map, such as PLargeMapControl and PSmallZoomControl.

Opening an Info Window

Information windows that appear as cartoon-like bubbles can be overlain on the map. In their simplest version, these windows contain text. Click on the pin in the following example to open an Information Window.

View example (infowindow.html).

The above example shows how to add a simple info window to the map. The following line opens the window.

map.openInfoWindow(map.getCenterLatLng(),
                   document.createTextNode("Hello, world!"));

Adding Overlays to the Map

Many overlays can be added to the same map. The following example loops through and adds 10 random pins and 4 lines to the map.

View example (overlay.html).

Handling clicks

Points can be added to the map via clicks using event listening. The following example shows how to support adding markers to the map at whatever point a user clicks.

View example (click.html).

The addListener function waits for a user click, at which point a new PMarker is added to the map.

PEvent.addListener(map, 'click', function(overlay, point) {
    if (overlay) {
        map.removeOverlay(overlay);
    } else if (point) {
        map.addOverlay(new PMarker(point));
    }
});

Attaching Events

In addition to clicks, other events can also be attached and handled with the event listener. The following example prints out several events as they occur. Click here for a list events that can be attached to PMap.

View example (events.html).

Opening an Info Window above a Marker

Info windows can be added to markers themselves in order to annotate the pins.

View example (infowinmarkup.html).

The addListner function is used to add a listener to a specific PMarker object called marker.

PEvent.addListener(marker, 'click', function() {
	marker.openInfoWindowHtml(html);
});

Creating Custom Icons

You can use your own custom icons on the maps using Pushpin LE. Setting the icon.image attribute and (optionally) the icon.shadow attribute to a URL pointing to the image to use will enable overlay of custom images on the map.

View example (icon.html).

Getting Multiple Maps on One Page

Multiple maps can be configured to appear on the same page as in the following example:

View example (multimap.html).

Each map is declared as a separate variable (in this case map and map2), and each can be controlled distinctly by its handle.

var map2 = new PMap(document.getElementById("map2"));
map2.centerAndZoom(new PPoint(-118.055, 33.952), 3);

Converting an Address to a Point (Geocoding)

The process of taking address information and converting it to a location in space is called Geocoding. Pushpin LE supports geocoding of addresses in order to get points from addresses. As shown in the example below, the onLoad function must call a separate function that can create the map page with the results. Geocoding is an inherently messy process and often addresses will not resolve to specific coordinates. Therefore the example below uses error handling for cases where the address cannot be geocoded successfully.

View example (geocode.html).

Creating a Map in Demo Mode

Demo Mode creates a map that pans and zooms itself, showing off some of the features of Pushpin LE.

View example (demo.html).

The startDemo function kicks off the attract mode mapping at the point specified.

map.startDemo(new PPoint(-118.234095, 34.044271), 3);

Class Reference

(Partial- under development). The following tables list the classes and methods currently available through the Pushpin LE API.

`Class: PMap`
Method	Description	Example
`new PMap(container)`	The constructor. Creates a new map object within the HTML container, normally a `div` element.	start.html
`enableDragging()`	Enables dynamic dragging of the map (enabled by default).
`disableDragging()`	Disables dynamic dragging of the map.
`draggingEnabled()`	Returns true if dragging is enabled, false if dragging is disabled.
`enableInfoWindow()`	Enables display of the info window on the map (enabled by default).
`disableInfoWindow()`	Disables display of the info window on the map.
`infoWindowEnabled()`	Returns true is info window is enabled, false if info window is disabled.
`addControl(control)`	Adds a control to the map, such as a `PSmallMapControl`.	smallmapcontrol.html
`removeControl()`	Removes the current control on the map.
`getCenterLatLng()`	Returns a `PPoint` object that represents the center point of the current map view in latitude/longitude.	infowindow.html
`getBoundsLatLng()`	Returns a `PBounds` object that represents the bounding box of the current map view in latitude/longitude.	overlay.html
`getSpanLatLng()`	Returns a `PSize` object that represents the width and height of the current map view in latitude/longitude.
`getZoomLevel()`	Returns the zoom level of the current map.
`centerAtLatLng(PPoint)`	Centers the map at the given `PPoint` object.
`recenterOrPanToLatLng(PPoint)`	Centers the map at the given `PPoint` object. If the point is within the current map view, the map will pan smoothly to the point.
`zoomTo(zoomLevel)`	Zooms to the given zoom level. If the zoom level is not valid, the request is ignored.
`centerAndZoom(PPoint, zoomlevel)`	Centers and zooms the map at the given `PPoint` object and zoom level.	start.html
`addOverlay(overlay)`	Adds the given `PMarker` overlay to the map.	overlay.html
`removeOverlay(overlay)`	Removes the given overlay (`PMarker`) from the map.	click.html
`openInfoWindow(PPoint, htmlElem)`	Displays an info window at the given `PPoint` with the given HTML DOM element.	infowindow.html
`openInfoWindowHtml(PPoint, htmlString)`	Displays an info window at the given `PPoint` with the given HTML string.
`closeInfoWindow()`	Closes the info window if it is displayed on the map.
`startDemo(PPoint, zoomLevel, interval)`	Starts the map in demo mode, centering on the given `PPoint` and zoom level. If an interval is specified (in milliseconds), this sets the time between actions in the demo, otherwise a default of 2000ms is used.	demo.html
`stopDemo()`	Stops the demo mode in the map.	demo.html

Event	Argument	Description	Example
`click`	`overlay, point`	This event gets triggered when a mouse click happens on the map. The overlay argument will contain a value if the user clicked on a marker. The point argument will contain the latitutde and longtiude of the click if no overlay was clicked	click.html
`movestart`		This event gets triggered when the map view starts changing. This could happen from a pan, drag or a method that changes the map view.	events.html
`move`		This event gets triggered as the map view changes.
`moveend`		This event gets triggered when the map view has finished changing.	events.html
`zoomend`	`oldLevel, newLevel`	This event gets triggered when the zoom level of the map has changed.	events.html
`mousemove`		This event gets triggered when the mouse is moved inside the map.
`dragstart`		This event gets triggered when the map starts getting dragged.	events.html
`drag`		This event gets triggered as the map gets dragged.
`dragstop`		This event gets triggered when the map stops being dragged.	events.html

`Class: PMarker`
Method	Description	Example
`new PMarker(point, icon?)`	The constructor. Creates a new `PMarker` object at the given `point`. A `PIcon` can be specified, otherwise the default Pushpin icon will be used.	addpin.html
`openInfoWindow(htmlElem)`	Displays an info window above the marker with the given HTML DOM element.
`openInfoWindow(htmlString)`	Displays an info window above the marker with the given HTML string.	infowinmarkup.html

Events	Description	Example
`click`	This event gets triggered when a mouse click happens on the map.	infowinmarkup.html

`Class: PPolyline`
Method	Description	Example
`new PPolyline(points, color, weight, opacity)`	The constructor. Creates a new `PPolyline` object from the given points (array of `PPoint` objects). The color (in HTML hex form like "#ff0000"), weight (width in pixels), and opacity (float between 0 and 1) can be specified.	overlay.html

`Class: PIcon`
Method	Description	Example
`new PIcon(icon?)`	The constructor. Creates a new `PIcon` object. If a `PIcon` is specified, its properties are copied. There are some Pushpin icons that can be added by specifying a string instead of a `PIcon`. 'PushpinLogo' uses the same icon as the pin in the Pushpin logo. 'PushpinSmall' uses a smaller icon that looks better in higher zoom levels.	icon.html

Property	Type	Description	Example
`image`	String	Sets the URL of the icon image to be used.	icon.html
`shadow`	String	Sets the URL of the icon's shadow image to be used.	icon.html
`iconSize`	PSize	Sets the size of the icon image in pixels using the `PSize` object with pixels.	icon.html
`shadowSize`	PSize	Sets the size of the icon's shadow image in pixels using the `PSize` object with pixels.	icon.html
`iconAnchor`	PPoint	Sets an offset for the icon, using the `PPoint` object with pixels, to anchor the icon to the marker's point.	icon.html
`shadowAnchor`	PPoint	Sets an offset for the shadow, using the `PPoint` object with pixels, to anchor the shadow to the marker's point.	icon.html
`infoWindowAnchor`	PPoint	Sets an offset for the info window, using the `PPoint` object with pixels, to anchor the info window to the marker's point.	icon.html

`Class: PEvent`
Method	Description	Example
`addListener(source, eventName, function)`	A static method that calls the given function when the given event happens on the source object.	infowinmarkup.html

`Class: PGeocoder`
Method	Description	Example
`new PGeocoder()`	The constructor. Creates an object that can convert address strings into a latitude and longitude coordinates.	geocode.html
`geocode(address, callback)`	Calls the pushpin geocoder to geocode the address and return the result via `callback`. The `address` argument must be a `PAddress` object. The `callback` argument mustbe a `Function` that accepts a `PAddress` as its first argument.

`Class: PAddress`
Method	Description	Example
`new PAddress(addr, x, y, errorMsg, errorCode)`	The constructor. Creates an object that stores an address and its coordinates if it was geocoded. See the `PGeocoder` class.	geocode.html
`wasFound()`	Returns true if the address was geocoded successfully (i.e. the `x` and `y` properties of the object have values); false otherwise.	geocode.html

Property	Type	Description	Example
`addr`	String	Calls the pushpin geocoder to geocode the address and return the result via `callback`. The `address` argument must be a `PAddress` object. The `callback` argument mustbe a `Function` that accepts a `PAddress` as its first argument.	geocode.html
`x`	decimal	the longitudinal coordinate of the address.	geocode.html
`y`	decimal	the latitudinal coordinate of the address.	geocode.html
`errorMsg`	String	User-friendly text describing why an error ocurred in geocoding the address.	geocode.html
`errorCode`	integer	A number indicating the type of error that occurred when geocoding the address.	geocode.html

`Class: PPoint`
Method	Description	Example
`new PPoint(x, y)`	The constructor. Creates a new `PPoint` object with the `x` and `y` geographic longitude latitude coordinates. Can also be in pixels.	start.html

Property	Type	Description	Example
x	integer	Contains either the longitudinal or x-axis value depending on how the object is initialized	start.html
y	integer	Contains either the latitudinal or y-axis value depending on how the object is intialized	start.html

`Class: PSize`
Method	Description	Example
`new PSize(width, height)`	The constructor. Creates a new `PSize` object with the given width and height measurement values. This could be in longitude (width) or latitude (height) or in pixels.	start.html

`Class: PBounds`
Method	Description	Example
`new PBounds(minX, minY, maxX, maxY)`	The constructor. Creates a new `PBounds` object with the given coordinates. This could be in longitude / latitude or in pixels. `minX, minY` represent the top left coordinates of the box and `maxX, maxY` represent the bottom right coordinates.	overlay.html

`Class: PLargeMapControl`
Method	Description	Example
`new PLargeMapControl()`	The constructor. Creates large zoom and pan controls on the map, including the zoom slider.	largecontrol.html

`Class: PSmallMapControl`
Method	Description	Example
`new PSmallMapControl()`	The constructor. Creates small zoom and pan controls on the map.	smallmapcontrol.html

`Class: PSmallZoomControl`
Method	Description	Example
`new PSmallZoomControl()`	The constructor. Creates only a small zoom control..	smallcontrol.html

`Function: PGetVersion`
Method	Return	Description	Example
`PGetVersion()`	`String`	This global function returns the version number of the API.