Developer Network Home - Help

Yahoo! Maps Web Services - AJAX API Reference Manual

Version 3 - Beta Yahoo! Maps AJAX API Reference Manual

 

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

Supporting Utilities

Class Description
YLog Captures debugging messages conveniently to logging widget

Classes

Class Description
YCustomOverlay Enables overlay of custom objects at YGeoPoint or YCoordPoint
YCoordPoint Creates an x,y coordinate object
YEvent Registers API events
YGeoPoint Defines objects with latitude and longitude properties
YMap Defines maps and offers many methods which can change the attributes of the map
YMarker Defines map marker objects
YImage Defines custom image object
YSize Defines size objects used for height/width manipulations
YGeoRSS Defines GeoRSS objects used for XML data overlay

Utilities

YLog

Captures printed debug messages, conveniently formats output.

Usage: YLog.print(this.object)

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

Class Details

YCustomOverlay(YGeoPoint,HTMLobject?)

YCustomOverlay provides for overlay of custom objects

Constructor: YCustomOverlay(YGeoPoint|YCoordPoint, HTML object)

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.

Constructor: YCoordPoint(x, y)

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.

YEvent()

Event registration is done through this class.

Constructor: YEvent(object,event,callback,privateObject?)

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

YMarker specific

  • openExpanded
  • closeExpanded
  • openSmartWindow
  • closeSmartWindow

YGeoRSS specific

  • onStartGeoRSS
  • onEndGeoRSS

YMap/YMarker by address specific

  • onStartGeoCode
  • onEndGeoCode

YGeoPoint(lat, lon)

Defines an object with latitude and longitude properties.

Constructor: YGeoPoint(lat, lon)

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

Properties

Property Description
Lat latitude property
Lon Longitude property

YMap( mapContainer, mapType, mapSize )

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

Constructor: YMap( mapContainer, mapType, mapSize )

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
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()

Sets current map type

Parameters:

  • Array of YGeoPoints If provided best zoom level containing array of YGeoPoints is returned

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

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.

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
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 - a string. [orange, blue, violet, brown, green, black, grey, maroon, ocre, purple]
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.

YImage(srcImg?,sizeImg?,offsetSmartWindow?)

The YImage class instantiates image objects.

Constructor: YImage()

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

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.

Constructor: YSize(width, height)

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

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.

Constructor: YGeoRSS(URL)

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);

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.

Copyright © 2010 Yahoo! Inc. All rights reserved.

Privacy Policy - Terms of Service - Copyright Policy - Job Openings