Yahoo! Maps Simple API

Displaying your content on Yahoo! Maps

The Yahoo! Maps Simple API enables you to overlay your data on Yahoo! Maps, allowing you to create custom map displays without programming. Simply pass geoRSS tagged XML files to our servers and your data will be displayed on a Yahoo! Map, complete with features like overlays and annotations.

Request URL

http://api.maps.yahoo.com/Maps/V1/annotatedMaps

Request parameters

The Yahoo! Maps Simple API supports GET and POST requests. See information on constructing REST queries

Here is a POST request sample written in JavaScript® and a GET sample query URL. In both cases you need to provide the following parameters:

Parameter Value Description
appid string (required) The application ID. See Application IDs for more information.
xmlsrc string (required) Either an XML string, or a URL to an XML file. If a URL is used, it must be accessible through a standard HTTP connection. Details on the format of this XML are below.

sample image

Response

The Yahoo! Maps Simple API returns HTML containing the generated map inside a Yahoo! page.

XML Input File Format

The XML used by the Yahoo! Maps Simple API is based on geoRSS 2.0. A good reference on the web is at http://brainoff.com/worldkit/doc/rss.php. A geoRSS file contains a channel element that can contain multiple item elements. The specification for these channel and item elements is found in the following tables:

Channel Sub-Elements

Element Value Description
link string (required) A URL to be used to link the user back to the referring page. Presently not displayed
title string (required) The anchor text for the URL specified by the link.
image enclosing tag Specifies an image file for branding above the map. The file may be no larger than 144x100 pixels. It has one required sub-element:
  • url (string): The URL of the image file.
There are also five optional sub-elements:
  • title (string): alt text for the image.
  • description (string): text displayed beneath the image.
  • link (string): a URL to specify where the description should link if clicked on.
  • width (integer): the width of the image in pixels
  • height (integer): the height of the image in pixels
geo:lat floating-point number The latitude for the center point of the map. If geo:lat, geo:long and ymaps:ZoomLevel are all specified, any point outside the map borders will not be shown.
geo:long floating-point number The longitude for the center point of the map.
ymaps:ZoomLevel integer (1-10) The zoom level for the map. Some common zoom levels:
  • 2: street level
  • 4: city level
  • 8: state level
ymaps:IntlCode string Two letter language code. This replaces the default language code in the HTTP header.
ymaps:Groups enclosing tag Allows grouping of some icons to form a legend at the top of the map. It may enclose an arbitrary number of Group entities. It has one attribute:
  • defaultViewNumbered (Boolean). If set to true, the icons on the group legend will be numbered unless overridden by a BaseIcon definition.
group enclosing tag Specifies a group as part of the ymaps:Groups. It has two required sub-elements:
  • title (string): A title for this group, to be shown in the legend.
  • id (string): an id string to allow this group to be referred to in item elements (which may then use the group icon if one is specified).
There are also three optional sub-elements. These tags serve the same purpose as the ones below, and full documentation may be found there:
  • ymaps:BaseIcon (string).
  • ymaps:HoverIcon (string).
  • ymaps:PopupIcon (string).
item enclosing tag Describes an individual item to be placed on the map. Full specification for the item element is in the table below.

Item Sub-Elements

Element Value Description
title string (required) The title of the item, displayed next to the icon on the left-hand side and as the title of the popup information box.
link (required) string A URL to link this item to an external webpage. Links the text specified in title.
description (required) string The free text in the body of the popup information box.
ymaps:Address string The street address of the location. Anything Yahoo! Maps is able to recognize as a valid address can be used here.
ymaps:CityState string The city and state/province of the location.
ymaps:Zip integer or <integer>-<integer> The five-digit ZIP code, or the five-digit code plus four-digit extension of the location.
ymaps:Country string: default us The two-letter country code of the location. ca and us are currently supported.
geo:lat floating-point number The latitude of the location. If geo:lat and geo:long are not specified, ymaps:Address, ymaps:CityState, ymaps:Zip and ymaps:Country are all required.
geo:long floating-point number The longitude of the location.
ymaps:PhoneNumber string The phone number for the location, for display in the popup information box.
ymaps:GroupId string Assigns this item to a group specified in the ymaps:Groups. It will default to using the icon for that group unless overridden by ymaps:BaseIcon.
ymaps:BaseIcon string A URL to a GIF file, which will be used as the icon to represent this item on the map.
ymaps:HoverIcon string A URL to a GIF file, which will be used as the icon when the mouse moves over the BaseIcon on the map. Defaults to the BaseIcon.
ymaps:PopupIcon string A URL to a GIF file, which will be used as the icon when the user clicks on the location on the map for more information. Defaults to the BaseIcon.
ymaps:ExtraLink string The text for an additional link to be put into the popup information box. Has attributes:
  • href: The URL that this link should point to.
An item may contain multiple instances of this tag.
ymaps:ExtraImage enclosing tag Specifies an image file for display in the popup information box. It has two required sub-elements:
  • url (string): The URL of the image file.
  • title (string): alt text for the image.
There is also an optional sub-element:
  • link (string): a URL to specify where the image should link if clicked.
An item may contain multiple instances of this tag.
ymaps:ItemUrl string A URL pointing to html content that should be displayed in an IFRAME inside the popup information box. Only one ItemUrl may be used per item.

Sample XML File

Yahoo! Maps Simple API Samples

HTTP GET Request Url

http://api.maps.yahoo.com/Maps/V1/annotatedMaps?appid=YahooDemo& xmlsrc=https://developer.yahoo.com/maps/sample.xml

HTTP POST Sample

The provided sample consists of two parts. The HTML file and is shown in the textfield below and a JavaScript file that gets included. You can see the script in action or have a look at the JavaScript file. Oliver Harte provided an updated version of the script that works in IE as well and he added some lines of documentation to it.

Embed Yahoo! Maps in web pages

If you want to embed Yahoo! Maps in your web site or application, try our embeddable APIs - Flash and AJAX APIs.

Ready to get started?