Yahoo! Placemaker™ Beta

Yahoo! Placemaker is a freely available geoparsing Web service. It helps developers make their applications location-aware by identifying places in unstructured and atomic content – feeds, web pages, news, status updates – and returning geographic metadata for geographic indexing and markup.

Placemaker provides geo-enrichment for the hugely significant proportion of Web content that is geographically relevant but not geographically discoverable. Provided with free-form text, the service identifies places mentioned in text, disambiguates those places, and returns unique identifiers (WOEIDs) for each, as well as information about how many times the place was found in the text, and where in the text it was found. The WOEIDs returned by the service can be passed to Yahoo!'s GeoPlanet™ API for further geographic enrichment and discovery.

Placemaker is not a geocoder and does not perform street-level address recognition; it is however a geo-extraction and indexing tool designed to help determine the 'whereness' of a document or atomic unit of text. It provides the geographic developer community with the means to mark-up and index their content geographically in a globally-aware, locally-relevant, and language-neutral manner, and assists with geographic discovery and aggregation across the Internet.

How Do I Get Started?

1. Get an application ID
2. Read the online documentation
3. POST content to the service and start contributing to the location-aware Web.

Using the API or Web Service

Overview

In simple terms, the Service allows you to determine what places are referenced in a unit of text: you POST content to the service, we return the WOEIDs and the names of the places found therein.

The API is accessed via HTTP POST only.

Application IDs

Yahoo! Placemaker requires a valid application ID to view the results.

Examples

The POST request:

http://wherein.yahooapis.com/v1/document

documentContent=Sunnyvale+CA
documentType=text/plain
appid=my_appid

produces the following return result:

<?xml version="1.0" encoding="utf-8"?>
<contentlocation
  xmlns:yahoo="http://www.yahooapis.com/v1/base.rng"
  xmlns:xml="http://www.w3.org/XML/1998/namespace"
  xmlns="http://wherein.yahooapis.com/v1/schema"
  xml:lang="en">
  <processingTime>0.001432</processingTime>
  <version> build 090409</version>
  <documentLength>12</documentLength>
  <document>
    <administrativeScope>
      <woeId>2502265</woeId>
      <type>Town</type>
      <name><![CDATA[Sunnyvale, CA, US]]></name>
      <centroid>
        <latitude>37.3716</latitude>
        <longitude>-122.038</longitude>
      </centroid>
    </administrativeScope>
    <geographicScope>
      <woeId>2502265</woeId>
      <type>Town</type>
      <name><![CDATA[Sunnyvale, CA, US]]></name>
      <centroid>
        <latitude>37.3716</latitude>
        <longitude>-122.038</longitude>
      </centroid>
    </geographicScope>
    <extents>
      <center>
        <latitude>37.3716</latitude>
        <longitude>-122.038</longitude>
      </center>
      <southWest>
        <latitude>37.3316</latitude>
        <longitude>-122.081</longitude>
      </southWest>
      <northEast>
        <latitude>37.4518</latitude>
        <longitude>-121.979</longitude>
      </northEast>
    </extents>
    <placeDetails>
      <place>
        <woeId>2502265</woeId>
        <type>Town</type>
        <name><![CDATA[Sunnyvale, CA, US]]></name>
        <centroid>
          <latitude>37.3716</latitude>
          <longitude>-122.038</longitude>
        </centroid>
      </place>
      <matchType>0</matchType>
      <weight>1</weight>
      <confidence>10</confidence>
    </placeDetails>
    <referenceList>
      <reference>
        <woeIds>2502265</woeIds>
        <start>0</start>
        <end>12</end>
        <isPlaintextMarker>1</isPlaintextMarker>
        <text><![CDATA[Sunnyvale CA]]></text>
        <type>plaintext</type>
        <xpath><![CDATA[]]></xpath>
      </reference>
    </referenceList>
  </document>
</contentlocation>

Rate Limits

There are no formal rate limits but, if using the service aggressively, it may be prudent to wait (sleep) between requests.

Terms of Use

Use of this service is subject to the Yahoo! APIs Terms of Use.