Web Service

Base URI

Yahoo! PlaceSpotter is a RESTful Web service, accessible at the following URI:

http://yboss.yahooapis.com/geo/placespotter?[parameters]

Requests to PlaceSpotter are sent as HTTP 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. You will also need to use Yahoo!'s OAuth authentication code to authenticate your API call to Yahoo!

The PlaceSpotter 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 PlaceSpotter 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 Example Description Defaults Optional/Required
inputLanguage inputLanguage=fr-CA

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

en-US Optional
outputType outputType=xml Return results in the specified format. Allowed values: xml, json. See also Response Formats. xml Optional
callback 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". (none) Optional
documentContent documentContent=I+live+in+New+York+City Input document to be processed by the request. (none) Required

Rule: Required if documentURL is not specified. Either documentContent or documentURL must be specified, but not both.

documentTitle documentTitle=News+from+New+York+City Title of input document to be processed. Only processed for plaintext documents. (none) Optional
documentURL documentURL=http://rss.slashdot/Slashdot/slashdot URL of input document to be processed by the request.

(none)

Required

Rule: Required if documentContent is not specified. Either documentContent or documentURL must be specified, but not both.

documentType documentType=text/plain

MIME document type. Allowed vaues: text/plain, text/html, text/xml, text/rss, application/xml, application/rss+xml.

(none) Optional

Rule: Required if documentContent is specified. Optional if documentURLis 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 autoDisambiguate=false If true, return only the most likely named place for each place reference. If false, override the the place disambiguation feature of PlaceSpotter. true Optional
focusWoeId 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. (none) Optional
confidence confidence=8 Return only results that have equal or higher confidence. 8 Optional
characterLimit characterLimit=1000 Process only the first N characters of the input document . (none) Optional

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.
JSON JavaScript Object Notation

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 PlaceSpotter 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.

Table of Contents