Placemaker Web Service

Base URI

Yahoo! Placemaker is a REST Web service, accessible at the following URI:

http://wherein.yahooapis.com[parameters]

Requests to Placemaker are sent as HTTP POST messages, using a URI (Uniform Resource Identifier) to indicate what resource is desired, HTTP headers to provide context for the request, and a message body composed of parameters and the document to be processed.

The Placemaker Web service supports only the HTTP PUT method. Other HTTP methods are not supported.

Resources

A resource identifies an object (commonly referred to as "nouns" in REST terminology). The Placemaker Web service has one type of resource: document. The resource name is appended to the base URI, as shown by the Examples.

Query Parameters

The Web service supports several parameters (name/value pairs) called "query parameters" that allow users to specify a particular language or format for the response. Query parameters are encoded using one of two encodings: application/x-www-form-urlencoded, or multipart/form-data. Note that qery parameter names are case sensitive.

The following query parameters are supported by the Web service:

Parameter Default Example Description
inputLanguage en-US inputLanguage=fr-CA

Use specified language (RFC 4646) for place name recognition.

outputType xml outputType=rss Return results in the specified format. Allowed values: xml, rss, json. See also Response Formats.
callback (none) callback=myfunc Return JSON response as a JavaScript function call (JSONP). The value of callback is the name of the JavaScript function. The outputType must be set to "json".
documentContent (none) documentContent=I+live+in+New+York+City Input document to be processed by the request. Required if documentURL is not specified. Either documentContent or documentURL must be specified, but not both.
documentTitle (none) documentTitle=News+from+New+York+City Title of input document to be processed. Only processed for plaintext documents.
documentURL

(none)

 documentURL=http://rss.slashdot/Slashdot/slashdot URL of input document to be processed by the request. Required if documentContent is not specified.
documentType (none) documentType=text/plain

MIME document type. Allowed vaues: text/plain, text/html, text/xml, text/rss, application/xml, application/rss+xml. Required if documentContent is specified. Optional if documentURL is specified. If documentType is omitted, then the document itself determines the type. If the content of the input document does not match the content type indicated by documentType, misleading results may be returned.

autoDisambiguate true autoDisambiguate=false If true, return only the most likely named place for each place reference. If false, override the the place disambiguation feature of Placemaker.
focusWoeId (none) focusWoeId=2459115 WOEID of named place to be used as a search focus. Identifies a place that will be used to bias the disamgibuation feature.
confidence 8 confidence=8 Return only results that have equal or higher confidence.
characterLimit (none) characterLimit=1000 Process only the first N characters of the input document .
appid (required) appid=3859387 Grants authorization to use the web service. Identifies the application performing a request. Required for all requests.

Response Errors

The Web service can return the following errors:

Error Code Cause Solution
400 Bad Request The appid parameter was invalid or not specified. Register your application with Yahoo! to get an appid and provide the appid parameter for each request.
404 Not Found The URI has no match in the display map. Make sure that you have spelled the resource correctly and are using the supported parameters.
413 Request Entity Too Large There is currently a 50,000 byte limit for documents processed by Placemaker. Documents above this length are rejected. Specify a smaller document.
415 Unsupported Media Type Document specified does not have a supported document type. Specify a valid media type. For a list of valid types, see the documentType query parameter.
999 Unable to process request at this time Your application is probably sending too many requests, too quickly. This can happen if you are batching requests. While this type of problem is usually temporary, if you continue to experience this error, we recommend that you try to wait (sleep) between requests to avoid this situation.

Response Formats

To specify the response format, set the outputType query parameter. The default response format is XML. The Web service supports the following response formats:

Format Description
XML eXtensible Markup Language (XML) is an open standard specification for serializing structured data.
RSS Really Simple Syndication (RSS) is a family of formats used to publish frequently updated textual content; RSS documents are serialized using XML.
JSON JavaScript Object Notation
JSONP JSON wrapped in a JavaScript callback function. To indicate JSONP, set the outputType query parameter to "json" and the callback query parameter to the name of the callback function.

XML Response Elements

The XML response is returned by default, or if the outputType parameter is set to "xml". The response document uses the XML specification to encode data and the document structure is defined by a Relax NG schema, which can be used to validate the response document.

The root element is called contentlocation. This element contains the following subelements:

Element Example Description
processingTime 0.0123 Time in seconds to process the document.
version build 090409 Version of the software used to process the document.
documentLength 10234 Length in bytes of the document.
document (container) Container for content location information. There may be more than one document element if the input document is an RSS document. Each item in an RSS document will be described by a separate document element in the response. If the input document (or RSS item) does not contain any place references, the corresponding document element will be empty (contain no child elements).

The document element contains the following subelements:

Element Description
administrativeScope Container for the smallest administrative place that best describes the document. Note that if there is no administrative place that best describes the document, the WOEID for that place will be 0.
geographicScope Container for the smallest place that best describes the document.
localScopes Container for list of localScope subelements.
extents Container for the the map extents covering the places mentioned in the document.
placeDetails Container for one named place mentioned in the document. If the input document (or RSS item) does not contain any place references, the corresponding document element will be empty (contain no child elements).
referenceList Container for place references.

The localScopes element contains the following subelement:

Element Description
localScope Container for the smallest named place associated with the document. There may be more than one localScope element.

The extents element contains the following subelements:

Element Example Description
center <latitude>40.7145</latitude> <longitude>-74.0071</longitude> Coordinates of center (WGS84). Can be used to mark the location of the place on a map.
southWest <latitude>35.9902</latitude> <longitude>-115.4</longitude> Coordinates of southwest corner of bounding box (WGS84). The southWest and northEast elements can be used to draw a box around the place on a map.
northEast <latitude>40.9176</latitude> <longitude>-73.7004</longitude> Coordinates of northeast corner of bounding box (WGS84).

The placeDetails element contains the following subelements:

Element Example Description
matchType 0 Type of match. Indicates whether the place was determined using text (such as a place name) or using coordinates only (0=text or text and coordinates, 1=coordinates only).
weight 3 Relative weight of the place within the document (range 1-100). Indicates the importance of the place to the document. The value is the sum of the weights of all the place references for the place. Place reference weights vary depending on where the place reference occurs within the document. Place weights are also used to determine the administrative and geographic scope for the document.
confidence 10 Confidence that the document mentions the place (range 1-10). Indicates the confidence that the document refers to the place and not some other place. It is the highest confidence associated with any of the place references for the place. It is possible to have a low-weight, high confidence place, such as San Francisco California, as well as a high-weight, low confidence place, such as Golden Gate Park.
placeId 1 Identifier for the place within the response.
placeReferenceIds 2 List of place reference identifiers referring to the place.
place (container) Container for place information.

In Placemaker 1.2 (or later), the same WOEID may be used in multiple placeDetails elements. The placeId element should be used to distinguish between such places. The placeReferenceIds element may be used to determine the text that matched the place.

The place, adminstrativeScope, and geographicScope elements contain the following subelements:

Element Example Description
woeId 2436704 Permanent identifier for the place.
type Town Place type name for the place.
name Las Vegas, NV, US Fully qualified name for the place.
centroid <latitude>36.1718</latitude> <longitude>-115.14</longitude> Centroid for the place.

The localScope element contains the following subelement:

Element Description
ancestors Container for a list of places that contain another place.

The ancestors element contains the following subelement:

Element Description
ancestor Container for a place that contains another place.

The ancestor element contains the following subelements:

Element Example Description
woeId 2436704 Permanent identifier for the place.
type Town Place type name for the place.
name Las Vegas, NV, US Name for the place (city, state, country or equivalent).

The referenceList element contains one or more of the following subelement:

Element Description
reference Container for one place reference found in the document. Each reference element describes a portion of the document that was matched to a place (or places).

The reference element contains the following subelements:

Element Example Description
woeIds 2436704 List of WOEIDs matching the place reference. Multiple WOEIDs will be separated by a space character. Each WOEID in a reference element will match the WOEID in one of the placeDetails elements.
placeReferenceId 1 Identifier for the place reference within the response.
placeIds 1 List of place identifiers the place reference refers to.
text las vegas, nv Actual text of place reference.
isPlaintextMarker 1 Flag indicating if the place reference is plain text (1=plaintext).
type plaintext Type of text marker for place reference (plaintext, xpath, xpathwithcounts). If the type element is xpathwithcounts, the start and end elements are set to the starting byte index and ending byte index of the text within that element.
start 26 Index of the first character in the place reference (if type is plaintext or xpathwithcounts) or -1 (if type is xpath).
end 39 Index of the first character after the place reference (if type is plaintext or xpathwithcounts) or -1 (if type is xpath).
xpath   Xpath of the place reference (if type is xpath or xpathwithcounts) or empty (if type is plaintext).

For plaintext documents, the isPlaintextMarker element is set to 1, the type element is set to "plaintext", and the start and end elements are set to the starting byte index and ending byte index of the text within the document. For structured documents (HTML, XML), the isPlaintextMarker element is set to 0, the type element is set to "xpath" or "xpathwithcounts", and the xpath element is set to the xpath of the element containing the text.

RSS Response Elements

The RSS response is returned if the outputType parameter is set to "rss". The response document uses the XML specification to encode data and the document structure is defined by the RSS schema, which can be used to validate the response document.

The root element is called rss. This element contains the following subelement:

Element Description
channel Container for channel information.

The channel element contains the following subelements:

Element Example Description
title Yahoo! Placemaker Title for the channel.
link http://wherein.yahooapis.com Link to the channel. Contains a link to the Placemaker web service.
description Yahoo! Placemaker extracted places Description of the channel.
ttl 5 Time to live for the channel.
pubDate Thu, 10 Mar 2009 10:57:22 Time that the channel was retrieved.
copyright Copyright (c) 2009 Yahoo! Inc. All rights reserved. Copyright notice
item (container) Container for items. There may be more than one item element if the input document is RSS and has multiple items.

The item element has the following subelements:

Element Example Description
title Sunnyvale, CA, US woeId=2502265 lat=37.37159 lon=-122.03824 Title for the item. Contains the adminstrativeScope place name, WOEID, and centroid coordinates.
link   Link to the item.
description Sunnyvale, CA, US woeID=2502265 lat=37.37159 lon=-122.03824 Description of the item. Contains the geographicScope place name, WOEID, and centroid coordinates.
cl:contentlocation (see example at the end of this section) Container for content location information.

The cl:contentlocation element has the following subelements:

Element Description
place Container for place information. There may be more than one place element if several places are recognized in the input document.

The place element has the following subelements:

Element Example Description
woeId 2502265 WOEID for the place
name Sunnyale, CA, US Fully qualified name of the place.
latitude 37.3716 Latitude of the centroid for the place.
longitude -122.038 Longitude of the centroid for the place.

Example contentlocation element:

Table of Contents