API Reference

Summary of Resources and Collections

The following resources and collections are provided:

/places: Returns a collection of places.
/place/{woeid}: Returns a place resource.
/place/{woeid}/parent: Returns a place resource for the parent of a place.
/place/{woeid}/ancestors: Returns a collection of places in the parent hierarchy for a place.
/place/{woeid}/belongtos: Returns a collection of places that contain a place.
/place/{woeid}/neighbors: Returns a collection of places that are neighbors of a place.
/place/{woeid}/siblings: Returns a collection of places that are siblings of a place.
/place/{woeid}/children: Returns a collection of places that are children of a place.
/place/{woeid}/descendants: Returns a collection of places in the child hierarchy (the child, the child of child, etc.).
/place/{woeid}/common/{woeid}: Returns a place resource that is the common ancestor to both places.
/continents: Returns a collection of places that are continents.
/oceans: Returns a collection of places that are oceans.
/seas: Returns a collection of places that are seas.
/seas/{place}: Returns a collection of places that are seas and are part of or adjacent to the specified continent or ocean.
/countries: Returns a collection of places that are countries.
/countries/{place}: Returns a collection of places that are countries and are part of or adjacent to the specified continent or ocean.
/states/{country}: Returns a collection of places that are top-level administrative areas (states) within a country.
/admin1s/{country}: An alternative endpoint for /states/{country}.
/counties/{state}: Returns a collection of places that are second-level administrative areas (counties) within a top-level administrative area (state).
/admin2s/{admin1s}: An alternative endpoint for /counties/{state}.
/districts/{county}: Returns a collection of places that are third-level administrative areas (districts) within a second-level administrative area (county).
/admin3s/{admin2}: An alternative endpoint for /districts/{county}.
/concordance/{namespace}/{id}: Returns information that maps dentifiers (codes) from other providers to WOEIDs.
/placetypes: Returns the complete collection of place types supported in GeoPlanet.
/placetypes/{country}: Returns information about all the known placetypes. The placetype name returned will be country-specific, and may vary upon the language requested.
/placetype/{type}: Returns a place type resource.
/placetype/{type}/{country}: Returns information about a single placetype known by its code. The placetype name returned will be country-specific, and may vary depending upon the language requested.

/places

Returns a collection of places that match a specified place name, and optionally, a specified place type. The resources in the collection are long representations of each place (unless short representations are explicitly requested).

Supported Filters

.q
.type
$and
.woeid

Example 8. Retrieving the Most Likely Place for a Given Place Name

Request URI:

http://where.yahooapis.com/v1/places.q(SFO)?appid=[yourappidhere]

Response Data:

<?xml version="1.0" encoding="UTF-8"?>
<places xmlns="http://where.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="1" yahoo:total="1">
  <place yahoo:uri="http://where.yahooapis.com/v1/place/12521721" xml:lang="en-us">
    <woeid>12521721</woeid>
    <placeTypeName code="14">Airport</placeTypeName>
    <name>San Francisco International Airport</name>
    <country type="Country" code="US">United States</country>
    <admin1 type="State" code="US-CA">California</admin1>
    <admin2 type="County" code="">San Mateo</admin2>
    <admin3></admin3>
    <locality1>Millbrae</locality1>
    <locality2></locality2>
    <postal type="Zip Code">94128</postal>
    <centroid>
      <latitude>37.614712</latitude>
      <longitude>-122.391808</longitude>
    </centroid>
    <boundingBox>
      <southWest>
        <latitude>37.601822</latitude>
        <longitude>-122.408089</longitude>
      </southWest>
      <northEast>
        <latitude>37.627602</latitude>
        <longitude>-122.375526</longitude>
      </northEast>
    </boundingBox>
  </place>
</places>

Example 9. Retrieving the Five Most Likely Places for a Given Placename

Request URI:

http://where.yahooapis.com/v1/places.q(CA);count=5?appid=[yourappidhere]

Response Data:

<?xml version="1.0" encoding="UTF-8"?>
<places xmlns="http://where.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="4" yahoo:total="4">
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347563" xml:lang="en-us">
    <woeid>2347563</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>California</name>
    <country type="Country" code="US">United States</country>
    <admin1 type="State" code="US-CA">California</admin1>
    <admin2></admin2>
    <admin3></admin3>
    <locality1></locality1>
    <locality2></locality2>
    <postal></postal>
    <centroid>
      <latitude>37.271832</latitude>
      <longitude>-119.270203</longitude>
    </centroid>
    <boundingBox>
      <southWest>
        <latitude>32.534279</latitude>
        <longitude>-124.415024</longitude>
      </southWest>
      <northEast>
        <latitude>42.00938</latitude>
        <longitude>-114.130814</longitude>
      </northEast>
    </boundingBox>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/23424775" xml:lang="en-us">
    <woeid>23424775</woeid>
    <placeTypeName code="12">Country</placeTypeName>
    <name>Canada</name>
    <country type="Country" code="CA">Canada</country>
    <admin1></admin1>
    <admin2></admin2>
    <admin3></admin3>
    <locality1></locality1>
    <locality2></locality2>
    <postal></postal>
    <centroid>
      <latitude>62.35873</latitude>
      <longitude>-96.582092</longitude>
    </centroid>
    <boundingBox>
      <southWest>
        <latitude>41.55537</latitude>
        <longitude>-140.931137</longitude>
      </southWest>
      <northEast>
        <latitude>83.162102</latitude>
        <longitude>-52.23304</longitude>
      </northEast>
    </boundingBox>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/29334827" xml:lang="en-us">
    <woeid>29334827</woeid>
    <placeTypeName code="7">Town</placeTypeName>
    <name>Cà</name>
    <country type="Country" code="IT">Italy</country>
    <admin1 type="Region" code="">Liguria</admin1>
    <admin2 type="Province" code="IT-GE">Genoa</admin2>
    <admin3></admin3>
    <locality1>Cà</locality1>
    <locality2></locality2>
    <postal type="Postal Code">16026</postal>
    <centroid>
      <latitude>44.51226</latitude>
      <longitude>9.04149</longitude>
    </centroid>
    <boundingBox>
      <southWest>
        <latitude>44.503159</latitude>
        <longitude>9.02873</longitude>
      </southWest>
      <northEast>
        <latitude>44.521339</latitude>
        <longitude>9.05423</longitude>
      </northEast>
    </boundingBox>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2345111" xml:lang="en-us">
    <woeid>2345111</woeid>
    <placeTypeName code="8">Province</placeTypeName>
    <name>Ciego de Avila</name>
    <country type="Country" code="CU">Cuba</country>
    <admin1 type="Province" code="">Ciego de Avila</admin1>
    <admin2></admin2>
    <admin3></admin3>
    <locality1></locality1>
    <locality2></locality2>
    <postal></postal>
    <centroid>
      <latitude>21.95981</latitude>
      <longitude>-78.593674</longitude>
    </centroid>
    <boundingBox>
      <southWest>
        <latitude>20.84487</latitude>
        <longitude>-79.45208</longitude>
      </southWest>
      <northEast>
        <latitude>22.75045</latitude>
        <longitude>-78.070793</longitude>
      </northEast>
    </boundingBox>
  </place>
</places>

Example 10. Retrieving All Places for a Given Place Name and Place Type

Request URI:

http://where.yahooapis.com/v1/places$and(.q(Long+Island),.type(22));count=0?appid=[yourappidhere]

Response Data:

<?xml version="1.0" encoding="UTF-8"?>
<places xmlns="http://where.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="1" yahoo:total="1">
  <place yahoo:uri="http://where.yahooapis.com/v1/place/22720940" xml:lang="en-us">
    <woeid>22720940</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>Long Island</name>
    <country type="Country" code="AU">Australia</country>
    <admin1 type="State" code="AU-VIC">Victoria</admin1>
    <admin2/>
    <admin3/>
    <locality1 type="Town">Melbourne</locality1>
    <locality2 type="Suburb">Long Island</locality2>
    <postal type="Postal Code">3197</postal>
    <centroid>
      <latitude>-38.073818</latitude>
      <longitude>145.140045</longitude>
    </centroid>
    <boundingBox>
      <southWest>
        <latitude>-38.078369</latitude>
        <longitude>145.134277</longitude>
      </southWest>
      <northEast>
        <latitude>-38.069271</latitude>
        <longitude>145.145813</longitude>
      </northEast>
    </boundingBox>
  </place>
</places>

Example 11. Retrieving Places That Have the Given WOEIDs

Request URI:

http://where.yahooapis.com/v1/places.woeid(2488042,2488836,2486340)?appid=[yourappidhere]

Response Data:

<?xml version="1.0" encoding="UTF-8"?>
<places xmlns="http://where.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="3" yahoo:total="3">
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2488042" xml:lang="en-US">
    <woeid>2488042</woeid>
    <placeTypeName code="7">Town</placeTypeName>
    <name>San Jose</name>
    <country type="Country" code="US">United States</country>
    <admin1 type="State" code="US-CA">California</admin1>
    <admin2 type="County" code="">Santa Clara</admin2>
    <admin3/>
    <locality1 type="Town">San Jose</locality1>
    <locality2/>
    <postal/>
    <centroid>
      <latitude>37.338470</latitude>
      <longitude>-121.885788</longitude>
    </centroid>
    <boundingBox>
      <southWest>
        <latitude>37.117840</latitude>
        <longitude>-122.160027</longitude>
      </southWest>
      <northEast>
        <latitude>37.555859</latitude>
        <longitude>-121.535393</longitude>
      </northEast>
    </boundingBox>
    <areaRank>7</areaRank>
    <popRank>12</popRank>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2488836" xml:lang="en-US">
    <woeid>2488836</woeid>
    <placeTypeName code="7">Town</placeTypeName>
    <name>Santa Clara</name>
    <country type="Country" code="US">United States</country>
    <admin1 type="State" code="US-CA">California</admin1>
    <admin2 type="County" code="">Santa Clara</admin2>
    <admin3/>
    <locality1 type="Town">Santa Clara</locality1>
    <locality2/>
    <postal/>
    <centroid>
      <latitude>37.355499</latitude>
      <longitude>-121.954262</longitude>
    </centroid>
    <boundingBox>
      <southWest>
        <latitude>37.322990</latitude>
        <longitude>-122.004829</longitude>
      </southWest>
      <northEast>
        <latitude>37.422119</latitude>
        <longitude>-121.914909</longitude>
      </northEast>
    </boundingBox>
    <areaRank>4</areaRank>
    <popRank>10</popRank>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2486340" xml:lang="en-US">
    <woeid>2486340</woeid>
    <placeTypeName code="7">Town</placeTypeName>
    <name>Sacramento</name>
    <country type="Country" code="US">United States</country>
    <admin1 type="State" code="US-CA">California</admin1>
    <admin2 type="County" code="">Sacramento</admin2>
    <admin3/>
    <locality1 type="Town">Sacramento</locality1>
    <locality2/>
    <postal/>
    <centroid>
      <latitude>38.579060</latitude>
      <longitude>-121.491013</longitude>
    </centroid>
    <boundingBox>
      <southWest>
        <latitude>38.437901</latitude>
        <longitude>-121.584068</longitude>
      </southWest>
      <northEast>
        <latitude>38.685539</latitude>
        <longitude>-121.336868</longitude>
      </northEast>
    </boundingBox>
    <areaRank>5</areaRank>
    <popRank>12</popRank>
  </place>
</places>

/place/{woeid}

Returns a resource containing the long representation of a place (unless a short representation is explicitly requested).

Example 12. Retrieving a Place Using a Given WOEID

Request URI:

http://where.yahooapis.com/v1/place/2507854?appid=[yourappidhere]

Response Data:

Example 13. Retrieving a Place with a Given WOEID, in Short Representation

Request URI:

http://where.yahooapis.com/v1/place/2507854?select=short&appid=[yourappidhere]

Response Data:

Example 14. Retrieving a Place with a Given WOEID, in JSON format

Request URI:

http://where.yahooapis.com/v1/place/12521721?format=json&appid=[yourappidhere]

Response Data:

{
"places":{
  "place":[
    {
      "woeid":12521721,
      "placeTypeName":"Airport",
      "placeTypeName attrs":{
        "code":14 },
      "name":"San Francisco International Airport",
      "country":"United States",
      "country attrs":{
        "type":"Country",
        "code":"US" },
      "admin1":"California",
      "admin1 attrs":{
        "type":"State",
        "code":"US-CA" },
      "admin2":"San Mateo",
      "admin2 attrs":{
        "type":"County",
        "code":"" },
      "admin3":"",
      "locality1":"Millbrae",
      "locality1 attrs":{
        "type":"Town" },
      "locality2":"",
      "postal":"94128",
      "postal attrs":{
        "type":"Zip Code" },
      "centroid":{
        "latitude":37.614712,
        "longitude":-122.391808 },
      "boundingBox":{
        "southWest":{
          "latitude":37.601822,
          "longitude":-122.408089 },
        "northEast":{
        "latitude":37.627602,
        "longitude":-122.375526 } },
      "uri":"http:\/\/where.yahooapis.com\/v1\/place\/12521721",
      "lang":"en-us" } ],
  "start":0,
  "count":1,
  "total":1 } }

/place/{woeid}/parent

Returns a resource for the parent of a place. A place has only one parent. The resource is the short representation of the parent (unless a long representation is requested).

Example 15. Retrieving the Parent Place of a Given WOEID, as a Long Representation

Request URI:

http://where.yahooapis.com/v1/place/638242/parent?select=long&appid=[yourappidhere]

Response Data:

/place/{woeid}/ancestors

Returns a collection of places in the parent hierarchy (the parent, the parent of parent, etc.). The resources in the collection are short representations of each place (unless a long representation is specifically requested).

Supported Filters

None

Example 16. Retrieving the Ancestors for a Given WOEID

Request URI:

http://where.yahooapis.com/v1/place/12587712/ancestors?appid=[yourappidhere]

Response Data:

/place/{woeid}/belongtos

Returns a collection of places that have a place as a child or descendant (child of a child, etc.). The resources in the collection are short representations of each place (unless a long representation is specifically requested).

Supported Filters

.type

Example 17. Retrieving the Belongto Places of a Given WOEID

Request URI:

http://where.yahooapis.com/v1/place/23424900/belongtos?appid=[yourappidhere]

Response Data:

<?xml version="1.0" encoding="UTF-8"?>
<places xmlns="http://where.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="4" yahoo:total="4">
  <place yahoo:uri="http://where.yahooapis.com/v1/place/24865707" xml:lang="en-us">
    <woeid>24865707</woeid>
    <placeTypeName code="19">Supername</placeTypeName>
    <name>Central America</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/24865716" xml:lang="en-us">
    <woeid>24865716</woeid>
    <placeTypeName code="19">Supername</placeTypeName>
    <name>Latin America</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/24865672" xml:lang="en-us">
    <woeid>24865672</woeid>
    <placeTypeName code="29">Continent</placeTypeName>
    <name>North America</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/1" xml:lang="en-us">
    <woeid>1</woeid>
    <placeTypeName code="19">Supername</placeTypeName>
    <name>World</name>
  </place>
</places>

/place/{woeid}/neighbors

Returns a collection of places that neighbor of a place. The resources in the collection are short representations of each place (unless a long representation is requested). Note that neighbors are not necessarily geographically contiguous.

Supported Filters

.degree

Example 18. Retrieving Neighboring Places of a Given WOEID

Request URI:

http://where.yahooapis.com/v1/place/2347563/neighbors?appid=[yourappidhere]

Response Data:

Example 19. Retrieving Neighbors of the Neighbors of a Place With a Given WOEID

Request URI:

http://where.yahooapis.com/v1/place/2347563/neighbors.degree(2)?appid=[yourappidhere]

Response Data:

<?xml version="1.0" encoding="UTF-8"?>
<places xmlns="http://where.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="8" yahoo:total="8">
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347587" xml:lang="en-US">
    <woeid>2347587</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Nevada</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347596" xml:lang="en-US">
    <woeid>2347596</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Oregon</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347561" xml:lang="en-US">
    <woeid>2347561</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Arizona</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347603" xml:lang="en-US">
    <woeid>2347603</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Utah</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347571" xml:lang="en-US">
    <woeid>2347571</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Idaho</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347606" xml:lang="en-US">
    <woeid>2347606</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Washington</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347590" xml:lang="en-US">
    <woeid>2347590</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>New Mexico</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347564" xml:lang="en-US">
    <woeid>2347564</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Colorado</name>
  </place>
</places>

/place/{woeid}/siblings

Returns a collection of places that are siblings of a place. Siblings share the same parent and place type as the given place. The resources in the collection are short representations of each place (unless a long representation is requested).

Note

Only the first ten results are returned for this request. Adding a count parameter can increase or decrease the number of results returned.

Supported Filters

None

Example 20. Retrieving Sibling Places of a Given WOEID

Request URI:

http://where.yahooapis.com/v1/place/2347563/siblings?appid=[yourappidhere]

Response Data:

<?xml version="1.0" encoding="UTF-8"?>
<places xmlns="http://where.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="10" yahoo:total="51">
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347559" xml:lang="en-us">
    <woeid>2347559</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Alabama</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347560" xml:lang="en-us">
    <woeid>2347560</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Alaska</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347561" xml:lang="en-us">
    <woeid>2347561</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Arizona</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347562" xml:lang="en-us">
    <woeid>2347562</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Arkansas</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347563" xml:lang="en-us">
    <woeid>2347563</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>California</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347564" xml:lang="en-us">
    <woeid>2347564</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Colorado</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347565" xml:lang="en-us">
    <woeid>2347565</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Connecticut</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347566" xml:lang="en-us">
    <woeid>2347566</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Delaware</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347567" xml:lang="en-us">
    <woeid>2347567</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>District of Columbia</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347568" xml:lang="en-us">
    <woeid>2347568</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Florida</name>
  </place>
</places>

/place/{woeid}/children

Returns a collection of places that are children of a place. The resources in the collection are short representations of each place (unless a long representation is requested).

Note

Only the first ten results are returned for this request. Adding a count parameter can increase or decrease the number of results returned.

Supported Filters

.type
.degree

Example 21. Retrieving Children of Places of a Given WOEID

Request URI:

http://where.yahooapis.com/v1/place/23424977/children?appid=[yourappidhere]

Response Data:

<?xml version="1.0" encoding="UTF-8"?>
<places xmlns="http://where.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="10" yahoo:total="288">
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347559" xml:lang="en-us">
  <woeid>2347559</woeid>
  <placeTypeName code="8">State</placeTypeName>
  <name>Alabama</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347560" xml:lang="en-us">
    <woeid>2347560</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Alaska</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347561" xml:lang="en-us">
    <woeid>2347561</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Arizona</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347562" xml:lang="en-us">
    <woeid>2347562</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Arkansas</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347563" xml:lang="en-us">
    <woeid>2347563</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>California</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347564" xml:lang="en-us">
    <woeid>2347564</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Colorado</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347565" xml:lang="en-us">
    <woeid>2347565</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Connecticut</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347566" xml:lang="en-us">
    <woeid>2347566</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Delaware</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347567" xml:lang="en-us">
    <woeid>2347567</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>District of Columbia</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2347568" xml:lang="en-us">
    <woeid>2347568</woeid>
    <placeTypeName code="8">State</placeTypeName>
    <name>Florida</name>
  </place>
</places>

Example 22. Retrieving Children of the Children of a Place With a Given WOEID

Request URI:

http://where.yahooapis.com/v1/place/2488042/children.degree(2)?appid=[yourappidhere]

Response Data:

<?xml version="1.0" encoding="UTF-8"?>
<places xmlns="http://where.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="10" yahoo:total="862">
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2371353" xml:lang="en-US">
    <woeid>2371353</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>Buena Vista</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2371853" xml:lang="en-US">
    <woeid>2371853</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>Burbank</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2373540" xml:lang="en-US">
    <woeid>2373540</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>Cambrian Park</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2383055" xml:lang="en-US">
    <woeid>2383055</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>College Park</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2397051" xml:lang="en-US">
    <woeid>2397051</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>Edenvale</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2470686" xml:lang="en-US">
    <woeid>2470686</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>Perry</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2478537" xml:lang="en-US">
    <woeid>2478537</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>Rancho Rinconada</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2496130" xml:lang="en-US">
    <woeid>2496130</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>South Coyote</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2521129" xml:lang="en-US">
    <woeid>2521129</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>Willow Glen</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/12797555" xml:lang="en-US">
    <woeid>12797555</woeid>
    <placeTypeName code="11">Zip Code</placeTypeName>
    <name>95101</name>
  </place>
</places>

/place/{woeid}/descendants

Returns a collection of places in the child hierarchy (the child, the child of child, etc.). The resources in the collection are short representations of each place (unless a long representation is specifically requested).

Supported Filters

.type

Example 23. Retrieving Descendants for a Given WOEID

Request URI:

http://where.yahooapis.com/v1/place/2507854/descendants?appid=[yourappidhere]

Response Data:

<?xml version="1.0" encoding="UTF-8"?>
<places yahoo:start="0" yahoo:count="10" yahoo:total="208">
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2387118" xml:lang="en-us">
    <woeid>2387118</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>Creston</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2416645" xml:lang="en-us">
    <woeid>2416645</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>Hamilton Square</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2368700" xml:lang="en-us">
    <woeid>2368700</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>Briar Manor</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/2379541" xml:lang="en-us">
    <woeid>2379541</woeid>
    <placeTypeName code="22">Suburb</placeTypeName>
    <name>Chewalla Park</name>
  </place>
  .
  .
  .
  <place yahoo:uri="http://where.yahooapis.com/v1/place/23609073" xml:lang="en-us">
    <woeid>23609073</woeid>
    <placeTypeName code="20">Point of Interest</placeTypeName>
    <name>Trenton Central High School</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/23609075" xml:lang="en-us">
    <woeid>23609075</woeid>
    <placeTypeName code="20">Point of Interest</placeTypeName>
    <name>Hedgepeth-williams Middle School</name>
  </place>
</places>

/place/{woeid}/common/{woeid}

Returns a place resource that is the common ancestor to both places. Up to ten WOEIDs can be specified.

Example 24. Retrieving a Place That is a Common Ancestor of Two Places

Request URI:

Returns a collection of places that are second-level administrative areas (counties) within a top-level administrative area (state).

Supported Filters

None

Example 33. Retrieving the Counties Within California (CA)

Request URI:

http://where.yahooapis.com/v1/counties/CA?appid=[yourappidhere]

Response Data:

<?xml version="1.0" encoding="UTF-8"?>
<places yahoo:start="0" yahoo:count="58" yahoo:total="58">
  <place yahoo:uri="http://where.yahooapis.com/v1/place/12587670" xml:lang="en-us">
    <woeid>12587670</woeid>
    <placeTypeName code="9">County</placeTypeName>
    <name>Alameda</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/12587671" xml:lang="en-us">
    <woeid>12587671</woeid>
    <placeTypeName code="9">County</placeTypeName>
    <name>Alpine</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/12587672" xml:lang="en-us">
    <woeid>12587672</woeid>
    <placeTypeName code="9">County</placeTypeName>
    <name>Amador</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/12587673" xml:lang="en-us">
    <woeid>12587673</woeid>
    <placeTypeName code="9">County</placeTypeName>
    <name>Butte</name>
  </place>
  .
  .
  .
  <place yahoo:uri="http://where.yahooapis.com/v1/place/12587726" xml:lang="en-us">
    <woeid>12587726</woeid>
    <placeTypeName code="9">County</placeTypeName>
    <name>Yolo</name>
  </place>
  <place yahoo:uri="http://where.yahooapis.com/v1/place/12587727" xml:lang="en-us">
    <woeid>12587727</woeid>
    <placeTypeName code="9">County</placeTypeName>
    <name>Yuba</name>
  </place>
</places>

/admin2s/{admin1s}

<?xml version="1.0" encoding="UTF-8"?>
<placeTypes xmlns="http://where.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="35" yahoo:total="35">
  <placeType yahoo:uri="http://where.yahooapis.com/v1/placetype/0" xml:lang="en-us">
    <placeTypeName code="0">Undefined</placeTypeName>
  </placeType>
  <placeType yahoo:uri="http://where.yahooapis.com/v1/placetype/1" xml:lang="en-us">
    <placeTypeName code="1">Building</placeTypeName>
  </placeType>
  <placeType yahoo:uri="http://where.yahooapis.com/v1/placetype/2" xml:lang="en-us">
    <placeTypeName code="2">Street Segment</placeTypeName>
  </placeType>
...
  <placeType yahoo:uri="http://where.yahooapis.com/v1/placetype/35" xml:lang="en-us">
    <placeTypeName code="35">Historical Town</placeTypeName>
  </placeType>
  <placeType yahoo:uri="http://where.yahooapis.com/v1/placetype/36" xml:lang="en-us">
    <placeTypeName code="36">Aggregate</placeTypeName>
  </placeType>
</placeTypes>

Example 37. Retrieving a Collection of Place Types and Their Descriptions

Request URI:

http://where.yahooapis.com/v1/placetypes?select=long&appid=[yourappidhere]

Response Data:

<?xml version="1.0" encoding="UTF-8"?>
<placeTypes xmlns="http://where.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="35" yahoo:total="35">
  <placeType yahoo:uri="http://where.yahooapis.com/v1/placetype/0" xml:lang="en-us">
    <placeTypeName code="0">An undefined place</placeTypeDescription>
  </placeType>
  <placeType yahoo:uri="http://where.yahooapis.com/v1/placetype/1" xml:lang="en-us">
    <placeTypeName code="1">Building</placeTypeName>
    <placeTypeDescription>A building that matches the house number from an address</placeTypeDescription>
  </placeType>
  <placeType yahoo:uri="http://where.yahooapis.com/v1/placetype/2" xml:lang="en-us">
    <placeTypeName code="2">Street Segment</placeTypeName>
    <placeTypeDescription>A street segment that matches the street from an address>/placeTypeDescription>
  </placeType>
...
  <placeType yahoo:uri="http://where.yahooapis.com/v1/placetype/35" xml:lang="en-us">
    <placeTypeName code="35">Historical Town</placeTypeName>
    <placeTypeDescription>A historical populated settlement that is no longer known by its original name</placeTypeDescription>
  </placeType>
  <placeType yahoo:uri="http://where.yahooapis.com/v1/placetype/36" xml:lang="en-us">
    <placeTypeName code="36">Aggregate</placeTypeName>
    <placeTypeDescription>An aggregate place</placeTypeDescription>
  </placeType>
</placeTypes>

Example 38. Retrieving a Partial Collection of Place Types

Request URI:

http://where.yahooapis.com/v1/placetypes.type(0,2)?appid=[yourappidhere]

Response Data:

/placetypes/{country}

Returns information about all the known placetypes. The placetype name returned will be country-specific, and may vary upon the language requested.

Supported Filters

.type

Example 39. Retrieving All Placetypes for Spain

Request URI:

http://where.yahooapis.com/v1/placetypes/ES?appid=[yourappidhere]

Response Data:

/placetype/{type}

Returns a resource that describes a single place type.

Example 40. Retrieving a Short Representation of the Resource for a Place Type

Request URI:

http://where.yahooapis.com/v1/placetype/35?appid=[yourappidhere]

Response Data:

Example 41. Retrieving a Long Representation of the Resource for a Place Type

Request URI:

http://where.yahooapis.com/v1/placetype/35?select=long&appid=[yourappidhere]

Response Data:

/placetype/{type}/{country}

Returns information about a single placetype known by its code. The placetype name returned will be country-specific, and may vary depending upon the language requested.

Example 42. Retrieving the Province Placetype for Spain

Request URI:

http://where.yahooapis.com/v1/placetype/9/ES?appid=[yourappidhere]

Response Data:

API Reference

Summary of Resources and Collections

/places

Supported Filters

/place/{woeid}

/place/{woeid}/parent

/place/{woeid}/ancestors

Supported Filters

/place/{woeid}/belongtos

/place/{woeid}/belongtos

Supported Filters

/place/{woeid}/neighbors

Supported Filters

/place/{woeid}/siblings

Note

Supported Filters

/place/{woeid}/children

Note

Supported Filters

/place/{woeid}/descendants

Supported Filters

/place/{woeid}/common/{woeid}

/continents

Supported Filters

/oceans

Supported Filters

/seas

Supported Filters

/seas/{place}

Supported Filters

/countries

Supported Filters

/countries/{place}

Supported Filters

/states/{country}

Supported Filters

/admin1s/{country}

/counties/{state}

Supported Filters

/admin2s/{admin1s}

/districts/{county}

Supported Filters

/admin3s/{admin2}

/concordance/{namespace}/{id}

/placetypes

Supported Filters

/placetypes/{country}

Supported Filters

/placetype/{type}

/placetype/{type}/{country}

Table of Contents