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.
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:
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:
Return value: void |
| addMarker(YGeoPoint, id) | Adds a marker to the map at the specified location. Parameters:
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:
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:
Return value: YCoordPoint |
| convertXYLatLon(YCoordPoint) | Converts an x/y coordinate point to a lat/lon pair. Parameters:
Return value: YGeoPoint |
| disableDragMap | Disable draggable maps |
| drawZoomAndCenter( LocationType, ZoomLevel ) |
The main draw method. Parameters:
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:
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:
Return value: An object with the following properties: miles, kilometers |
| getZoomLevel(input?) | Returns current zoom level when no input is specified Parameters:
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:
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:
Return value: void |
| panToXY(YCoordPoint) | Pans map to the given x/y coordinates Parameters:
Return value: void |
| removeMarker(id) | Removes marker specified by id Parameters:
Return value: void |
| removeMarkersAll | Removes all markers from the map |
| removeOverlay(overlayObject) | Removes the specified overlayObject object from the map Parameters:
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:
Return value: void |
| setZoomLevel(zlevel) | Set new zoom level and redraw map at that zoom level |
| setZoomRange(minZoomLevel,maxZoomLevel) | Constrain zoom selection range Parameters:
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:
|
| setAnnotation(annotation) | Set defined map annotation object Parameters:
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:
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:
Return value: void |
| searchLocal(YGeoPoint,query,radius,nresults?) | Search local listings, used with onEndLocalSearch event callback Parameters:
Return value: void |
| searchTraffic(YGeoPoint,radius) | Search local traffic incidents, used with onEndTrafficSearch event callback Parameters:
Return value: void |
| getGeoBox(points) | Given array of YGeoPoint objects return min and max Parameters:
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:
Return value: object |
| geoCodeAddress (address) | Geocode address, used with onEndGeoCode event callback Parameters:
Return value: void |
YMapTypeControl(YCoordPoint)
Constructor: YMapTypeControl(CoordPoint)
| 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.
Class: YEvent
Methods
| Method | Description |
|---|---|
| Capture( object, event , callback ) |
Capture an event on a map or marker. Parameters:
Return value: void The event parameter should be a property of the EventsList object (e.g. EventsList.MouseUp):
YMarker specific
YGeoRSS specific
YMap specific
|
YPolyline(points, color?, width?, alpha?)
YPolyline enables creation of line segments on the map
Constructor: YPolyline(points, color?, width?, alpha?)
| 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
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. |
Methods
| Method | Description |
|---|---|
| distance(point) | Return distance between coordinate points Parameters:
Return value: float |
| translate(xcoord,ycoord) | Translate from default origin (left,top) to any other origin Parameters:
Return value: void |
| equal(point) | Check two coordinate points Parameters:
Return value: boolean |
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 |
Methods
| Method | Description |
|---|---|
| distance(point) | Return distance between coordinate points Parameters:
Return value: distance object with properties: kilometers, miles, nautical, pixels |
| middle(point) | Return middle point between two coordinate points Parameters:
Return value: YGeoPoint |
| equal(point) | Check two coordinate points Parameters:
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:
|
| 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:
|
| setYGeoPoint | set/re-set YGeoPoint of marker object Parameters:
|
| addLabel | Adds a label to the marker. Parameters:
|
| reLabel | change label on the marker Parameters:
|
| 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:
|
| updateSmartWindow( InfoValue) |
Update InfoValue of SmartWindow. Parameters:
|
| 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
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 |
| 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.
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); |
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 |
YMapDistance(distance, units?)
Class defines distance object. Very useful for internationalization of maps with various different units of distance (km , mi).
Constructor: YMapDistance(distance, units?)
| 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
Constructor: YAnnotation(title, description, link)
| 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.
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 |
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.
Class: YUtility
Methods
| Method | Description |
|---|---|
| containerResize(parentId,childId) | Parameters:
Constructor:
|
| createNode(type,id) | Convenience method encapsulates document.createNode with internally used property Parameters:
|
| appendNode(parent,child) | Convenience method encapsulates document.appendChild with internally used property Parameters:
|
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.
Recent Blog Articles
August 8, 2008
Y! Music Battle of the APIs in the Key of Ruby
August 8, 2008
August 4, 2008
August 4, 2008
Send Your Suggestions