Maps AJAX API Reference Manual - Version 3.8

This reference manual defines the classes and methods available with the Yahoo! Maps AJAX API. Need more help? Check out our Getting Started Guide.

Yahoo! Maps Cheatsheets

Download the complete set of cheatsheets and code examples in the Yahoo Maps API Reference Bundle

Classes

Class Description
YMap Defines map object and exports methods which can change the properties of the map
YMapTypeControl Defines map control types and their orientation and/or HTML markup.
YEvent Registers API events
YPolyline Defines polyline overlay class
YCustomOverlay Enables overlay of custom objects at YGeoPoint or YCoordPoint
YCoordPoint Creates an x,y coordinate object
YGeoPoint Defines objects with latitude and longitude properties
YMarker Defines map marker object
YImage Defines custom image object
YGeoRSS Defines GeoRSS objects used for XML data overlay
YSize Defines size objects used for height/width manipulations
YMapDistance Defines map distance objects
YAnnotation Defines map description object

Supporting Classes

Class Description
YLog Captures debugging messages conveniently to logging widget
YUtility Exports supporting convenience methods

Class Details

YMap( mapContainer, mapType, mapSize )

YMap class exports a number of methods to draw, pan and interact with Yahoo! maps, including overlay of markers.

Parameter Description
mapContainer The DOM id of the div element which will hold the map
mapType Current data types supported by map: YAHOO_MAP_SAT, YAHOO_MAP_REG, YAHOO_MAP_HYB
mapSize A YSize object controls maps container dimensions

Methods

Method Description
setMapType(mapType)

Sets current map type

Parameters:

  • Constant As returned from getMapTypes(), such as YAHOO_MAP_REG, YAHOO_MAP_SAT, YAHOO_MAP_HYB

Return value: void

getCurrentMapType()

Return value: current mapType constant

getMapTypes()

Return value: array of mapTypes [YAHOO_MAP_REG, YAHOO_MAP_SAT, YAHOO_MAP_HYB]

addTypeControl()

Adds an overlay with three controls by default

Parameters:

  • mapType array optionally accepts array of map types

Return value: void

addMarker(YGeoPoint, id)

Adds a marker to the map at the specified location.

Parameters:

  • YGeoPoint a map latitude/longitude object
  • id - Optional - DOM element attribute for the marker.

Return value: void

addOverlay(Overlay)

Adds an overlay object to the map, supports adding object of YGeoPoint (markers, smart window for example) and YCoordPoint (controls for example) types

Parameters:

  • Overlay object YCustomOverlay, YMarker object

Return value: void

addPanControl Adds a pan control widget to the map
addZoomLong Adds a zoom slider control widget to the map
addZoomShort Adds a +/- zoom button control widget to the map
convertLatLonXY(YGeoPoint)

Converts a lat/lon pair to an x/y coordinate point

Parameters:

  • YGeoPoint a lat/lon location to convert

Return value: YCoordPoint

convertXYLatLon(YCoordPoint)

Converts an x/y coordinate point to a lat/lon pair.

Parameters:

  • YCoordPoint - a coordinate point to convert

Return value: YGeoPoint

disableDragMap Disable draggable maps
drawZoomAndCenter(
LocationType,
ZoomLevel
)

The main draw method.

Parameters:

  • LocationType - YGeoPoint or valid address string, such as: "701 First Ave., Sunnyvale, CA" or "94089"
  • ZoomLevel - a desired zoom integer within 1-16 range .

Return value: void

enableDragMap Enables draggable maps
getBoundsLatLon

Returns the top left and bottom right lat/lon points of the map

Return value: an object with the properties LatMax, LonMax, LatMin, LonMin.

getCenterLatLon

Returns the lat/lon pair corresponding to the center of the map.

Return value: YGeoPoint object

getContainerSize Returns port size object {width, height}
getEventsList Returns the current list of supported events stored in the EventsList object (see YEvent class)
getInnerRadius Returns an integer -- the number of pixels that comprise the shortest distance from the center of the map to the edge.
getMarkerIDs Returns an array which has the ids of all markers currently in the map
getMarkerObject(MarkerID)

Returns marker object identified by MarkerID

Parameters:

  • MarkerID String identifying given marker

Return value: YMarker type object

getOuterRadius Returns an integer -- the number of pixels that comprise the longest distance from the center of the map to the edge.
getUnitsPerPixel(ZoomLevel)

Returns the granularity of distance represented by each pixel on the map at the specified zoom level

Parameters:

  • ZoomLevel - a desired zoom integer within 1-16 range (default is current zoom level)

Return value: An object with the following properties: miles, kilometers

getZoomLevel(input?)

Returns current zoom level when no input is specified

Parameters:

  • input Optional input parameter can be any of
    • if input is array of YGeoPoint objects best fit zoom is returned
    • if input is a YMapDistance object radius is assumed and best fit returned

Return value: default 1-16 current zoom level, best zoom level if array of YGeoPoints

getBestZoomAndCenter(input)

Returns object with zoomLevel and YGeoPoint properties

Parameters:

  • input array of YGeoPoint objects

Return value: object with zoomLevel and YGeoPoint properties

getZoomValidLevels Return array of valid zoom integers
isDragMapEnabled Returns boolean value determining whether map is draggable
panToLatLon(YGeoPoint)

Pans map to the given lat/lon

Parameters:

  • YGeoPoint - a map latitude/longitude object

Return value: void

panToXY(YCoordPoint)

Pans map to the given x/y coordinates

Parameters:

  • YCoordPoint - a map coordinate object

Return value: void

removeMarker(id)

Removes marker specified by id

Parameters:

  • id - the id of the YMarker object

Return value: void

removeMarkersAll Removes all markers from the map
removeOverlay(overlayObject)

Removes the specified overlayObject object from the map

Parameters:

  • overlayObject - overlay object

Return value: void

removePanControl Removes the pan control widget from the map
removeZoomControl Removes the zoom control widget from the map
resizeTo(YSize)

Given YSize object, resize map to new dimensions

Parameters:

  • YSize - a map width/height object

Return value: void

setZoomLevel(zlevel) Set new zoom level and redraw map at that zoom level
setZoomRange(minZoomLevel,maxZoomLevel)

Constrain zoom selection range

Parameters:

  • minZoomLevel - valid zoom integer
  • maxZoomLevel - valid zoom integer

Return value: void

showSmartWindow(
YGeoPoint,
InfoValue
)

Opens a SmartWindow at the location defined by YGeoPoint. The SmartWindow will display InfoValue. The InfoValue parameter can be an existing DOM object with nodeValue text.

Parameters:

  • YGeoPoint - a YGeoPoint location
  • InfoValue - string. A new text, HTML or object with nodeValue set.
setAnnotation(annotation)

Set defined map annotation object

Parameters:

  • annotation - Description object of type YMapAnnotation

Return value: void

getAnnotation()

Return annotation object set on given map instance

Return value: annotation object of type YMapAnnotation

exportFormat(type)

Export map in supported format defined by type

Parameters:

  • type - valid export type "GEORSS"

Return value: GeoRSS XML string

addZoomScale() Add zoom scale to map container (default)
removeZoomScale() Remove zoom scale from map container
disablePanOnDoubleClick() Disable default double click action
disableKeyControls() Disable default keyboard/mouse wheel zoom and pan controls shortcuts
processGeoRSS(URL)

Process GeoRSS document supplied over HTTP, used with onEndGeoRSS callback

Parameters:

  • URL - link to valid GeoRSS document

Return value: void

searchLocal(YGeoPoint,query,radius,nresults?)

Search local listings, used with onEndLocalSearch event callback

Parameters:

  • YGeoPoint - Location of interest center point
  • query - query string, for example "pizza", "yahoo"
  • radius - radius in miles from center point
  • nresults - number of results to return, max: 20

Return value: void

searchTraffic(YGeoPoint,radius)

Search local traffic incidents, used with onEndTrafficSearch event callback

Parameters:

  • YGeoPoint - Location of interest center point
  • radius - radius in miles from center point

Return value: void

getGeoBox(points)

Given array of YGeoPoint objects return min and max

Parameters:

  • points - array of YGeoPoint objects

Return value: object {min:YGeoPoint_MIN,max:YGeoPoint_MAX}

getPolylineIDs()

Get list of all generated polyline ids

Return value: array of ids

getPolylineObject(id)

return a reference to polyline segment for given id

Parameters:

  • id - id of polyline segment

Return value: object

geoCodeAddress (address)

Geocode address, used with onEndGeoCode event callback

Parameters:

  • address - valid address string

Return value: void

YMapTypeControl(YCoordPoint)

Parameter Description
CoordPoint A point of type YCoordPoint. Allows for custom positioning of the map type control.

Methods

Method Description
setControl(mapType, markup?, mapSize?) Add a Type Control (REG,SAT,HYB) to the available control types. Can be used to specify specific images for each control with a link location and YSize attribute.
setVertical() Sets the orientation of the Map Types to vertical.
setHorizontal() Sets the orientation of the Map Types to horizontal.

YEvent

Event registration is done through this class.

Methods

Method Description
Capture(
object,
event ,
callback
)

Capture an event on a map or marker.

Parameters:

  • object - a YMap or YMarker object .
  • event - an event to capture (see EventsList below)
  • callback - function to call when event is captured
  • privateObject - optional private context object

Return value: void

The event parameter should be a property of the EventsList object (e.g. EventsList.MouseUp):

  • endMapDraw
  • changeZoom
  • startPan
  • onPan
  • endPan
  • endAutoPan
  • startAutoPan
  • MouseClick
  • MouseDown
  • MouseDoubleClick
  • MouseOut
  • MouseOver
  • MouseUp
  • KeyUp
  • KeyDown

YMarker specific

  • openExpanded
  • closeExpanded
  • openSmartWindow
  • closeSmartWindow

YGeoRSS specific

  • onEndGeoRSS

YMap specific

  • onEndGeoCode
  • polylineAdded
  • polylineRemoved
  • endMapDraw
  • onEndLocalSearch
  • onEndTrafficSearch

YPolyline(points, color?, width?, alpha?)

YPolyline enables creation of line segments on the map

Parameter Description
points Array of YGeoPoint objects describing line segments, requires two or more points
color Optional line segment color
width Optional width in pixels
alpha Optional transparency level of the line segment

YCustomOverlay(YGeoPoint,HTMLobject?)

YCustomOverlay enables overlay of custom objects

Parameter Description
YGeoPoint or YCoordPoint Position object of type YGeoPoint (location position) or YCoordPoint (container coordinate position)
HTMLobject Customized map overlay HTML object

YCoordPoint(x, y)

YCoordPoint creates an object with x, y coordinate properties. The coordinates are in pixels with coordinate (0,0) as the upper left hand corner of the map.

Parameter Description
x An integer representing the pixel position from the top, left corner of the map on the x axis.
y An integer representing the pixel position from the top, left corner of the map on the y axis.

Properties

Property Description
x The pixel position from the top, left corner of the map on the x axis.
y The pixel position from the top, left corner of the map on the y axis.

Methods

Method Description
distance(point)

Return distance between coordinate points

Parameters:

  • point YCoordPoint type object

Return value: float

translate(xcoord,ycoord)

Translate from default origin (left,top) to any other origin

Parameters:

  • xcoord valid x coordinate name (left, right)
  • ycoord valid y coordinate name (top, bottom)

Return value: void

equal(point)

Check two coordinate points

Parameters:

  • point YCoordPoint type object

Return value: boolean

YGeoPoint(lat, lon)

Defines an object with latitude and longitude properties.

Parameter Description
lat A float representing geographic latitude
lon A float representing geographic longitude

Properties

Property Description
Lat latitude property
Lon Longitude property

Methods

Method Description
distance(point)

Return distance between coordinate points

Parameters:

  • point YGeoPoint type object

Return value: distance object with properties: kilometers, miles, nautical, pixels

middle(point)

Return middle point between two coordinate points

Parameters:

  • point YGeoPoint type object

Return value: YGeoPoint

equal(point)

Check two coordinate points

Parameters:

  • point YGeoPoint type object

Return value: boolean

YMarker(YGeoPoint, YImage?, ID?)

The YMarker class instantiates map marker objects.

Constructor: YMarker( YGeoPoint )

Parameter Description
YGeoPoint An object that holds a latitude/longitude pair
YImage Optional - An object that holds custom marker definitions
ID Optional - A string which identifies the marker as a DOM object (its CSS id attribute). The string should be comprised of digits (0-9) and/or lowercase letters (a-z). An ID will be automatically generated if this parameter is not provided. It's recommended to let API handle ID assignment.

Methods

Method Description
addAutoExpand(InfoValue)

Add AutoExpand window, use alone or with SmartWindow, automatically opens on mouseover and closes on mouseout events

Parameters:

  • InfoValue - HTML/Text string. used to display full or teaser content, can be used with SmartWindow
changeImage(YImage)

Changes the marker image with the supplied YImage.

openAutoExpand()

open AutoExpand window if defined

closeAutoExpand()

close AutoExpand window if defined

hide()

hides marker from the map

unhide()

unhides marker on the map

ishidden()

Check if current marker is hidden

Return value: boolean

setSmartWindowColor

set color of the SmartWindow border

Parameters:

  • color string. valid colors: [orange, blue, lightblue, brown, green, lightgreen, grey, black, maroon, ocre, purple]
setYGeoPoint

set/re-set YGeoPoint of marker object

Parameters:

  • YGeoPoint a map latitude/longitude object
addLabel

Adds a label to the marker.

Parameters:

  • label - a string. A new text or HTML label for the marker
reLabel

change label on the marker

Parameters:

  • label - a string. A new text or HTML label for the marker
closeSmartWindow Close the SmartWindow for the marker
openSmartWindow(
InfoValue)

Opens a smart window for the marker. The SmartWindow will display InfoValue. The InfoValue parameter can be an existing DOM object with nodeValue text.

Parameters:

  • InfoValue - string. A new text, HTML or object with nodeValue set.
updateSmartWindow(
InfoValue)

Update InfoValue of SmartWindow.

Parameters:

  • InfoValue - string. A new text, HTML or object with nodeValue set.
disableAutoContain Do not contain SmartWindow within container if opened
enableAutoContain Contain SmartWindow within map container if opened (default)
getCoordPoint Return object YCoordPoint relative to left,top origin

YImage(srcImg?,sizeImg?,offsetSmartWindow?,offset)

The YImage class instantiates image objects. Used with custom images for YMarker or YCustomOverlay

Properties Description
srcImg Image URL location
sizeImg YSize(width,height) object describing size of the image
offsetSmartWindow Position of SmartWindow is present relative to left,top coordinates of the marker image
offset Position of image relative to left, bottom origin coordinates (used to arbitrarily position image over YGeoPoint)

Properties

Property Description
Width The integer pixel width of the map
Height The integer pixel height of the map

YGeoRSS(URL)

A YGeoRSS object enables you to overlay your own data given valid GeoRSS XML file. The XML file must be a publically accessible.

Parameter Description
URL URL of valid GeoRSS file. Domain of this file should equal that including Maps API. More information on supported GeoRSS type

Event support

Property Description
onStartGeoRSS Register a callback before automatic overlay starts. For example: YEvent.Capture(map,EventsList.onStartGeoRSS, myCallback);
onEndGeoRSS Register a callback after GeoRSS overlay has completed. For example: YEvent.Capture(map,EventsList.onEndGeoRSS, myCallback);

YSize(width, height)

A size object with width and height properties. This object is used as a parameter for calls such as the YMap constructor and the YMap resizeTo method.

Parameter Description
width The integer pixel width of the map
height The integer pixel height of the map

YMapDistance(distance, units?)

Class defines distance object. Very useful for internationalization of maps with various different units of distance (km , mi).

Parameter Description
distance The distance length
units Distance units, "miles" (default) or "kilometers"

YAnnotation(title, description, link)

Class used with GeoRSS export to set map description

Parameter Description
title Title of the map
description Description of the map
link URL where map is hosted

Utilities

YLog

Captures printed debug messages, conveniently formats output.

Parameter Description
print(MESSAGE) Prints given message to capturing widget
initPos(YCoordPoint) Optionally initializes position of the logger
initSize(YSize) Optionally initializes width and height of the logger

YUtility

The YUtility class exports number of supporting and convenience methods. These methods are a very useful way to modify the dom or resize containers dynamically.

Methods

Method Description
containerResize(parentId,childId)

Parameters:

  • parentId - HTML element id of anchor object
  • childId - HTML element id of child object

Constructor:

  • YUtility.containerResize(parentId,childId);
createNode(type,id)

Convenience method encapsulates document.createNode with internally used property

Parameters:

  • type - valid HTML element type ("div", "img")
  • id - HTML element id
appendNode(parent,child)

Convenience method encapsulates document.appendChild with internally used property

Parameters:

  • parent - Parent HTML element object
  • child - Child HTML element object

Rate Limit

The Yahoo! Maps AJAX API is limited to 50,000 queries per IP per day and to non-commercial use. See information on rate limiting.

Sensor-Based Location Limit

You may use location data derived from GPS or other location sensing devices in connection with the Yahoo! Maps APIs, provided that such location data is not based on real-time (i.e., less than 6 hours) GPS or any other real-time location sensing device, the GPS or location sensing device that derives the location data cannot automatically (i.e. without human intervention) provide the end user's location, and any such location data must be uploaded by an end-user (and not you) to the Yahoo! Maps APIs.

Ready to get started?