Reference

Summary

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.
/placetypes: returns the complete collection of place types supported in GeoPlanet.
/placetype: returns a place type resource.

/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

The following filters are supported for this collection: .q, .type, $and. The .q filter allows a user to match places by name. The .type filter allows users to match places by place type. The $and filter allows users to match places using the intersection of the other filters.

The .q filter supports an optional country code, which is used to adjust the order of the results. The .q filter is required.

The .type filter must be used with the $and filter. It cannot be specified by itself because the .q filter is required.

Supported Matrix Parameters

The following matrix parameters are supported for this collection: start, count. The start parameter allows a user to skip resources. The count parameter allows a user to control the number of resources to be returned. These parameters effectively provide a mechanism for paging through large result sets.

Supported Query Parameters

The following query parameters are supported for this collection: lang, format, callback, select, and appid. The lang parameter allows a user to choose the language used in the response. The format parameter allows a user to choose the content type of the response (XML, JSON, GeoJSON). The callback parameter allows a user to encapsulate a JSON response within a JavaScript function call. The select parameter allows a user to choose the representation of the response (short, long). The appid parameter grants authorization to use the Web service, and is required.

Representations

The short representation contains three elements: woeid, placeTypeName, and name.

The long representation additionally contains these elements: country, admin1, admin2, admin3, locality1, locality2, postal, centroid, and boundingBox.

Possible Errors

The following errors can be returned:

400 Bad Request

A valid appid parameter is required for this resource; please visit http://developer.yahoo.com/wsregapp to get an appid

Be sure to provide the appid parameter for each GeoPlanet request you make.

400 Bad Request

Non empty q filter required for this resource

Be sure to provide the q filter in requests for the /places collection.

404 Not Found

URI has no match in the display map

Be sure that you have spelled the resource correctly and are using one of the supported filters for the /places collection.

406 Not Acceptable

Requested representation not available for this resource

Be sure that you have included an Accept header or format parameter with a supported value.

Examples

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

The request:

produces the following:

<?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 Place for a Given Placename

The request:

produces the following:

<?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

The request:

produces the following:

<?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>

/place/{woeid}

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

Supported Query Parameters

The following query parameters are supported for this collection: lang, format, callback, select, and appid. The lang parameter allows a user to choose the language used in the response. The format parameter allows a user to choose the content type of the response (XML, JSON, GeoJSON). The callback parameter allows a user to encapsulate a JSON response within a JavaScript function call. The select parameter allows a user to choose the representation of the response (short, long). The appid parameter grants authorization to use the Web service, and is required.

Representations

The short representation contains three elements: woeid, placeTypeName, and name.

The long representation additionally contains these elements: country, admin1, admin2, admin3, locality1, locality2, postal, centroid, and boundingBox.

Possible Errors

The following errors can be returned:

400 Bad Request

A valid appid parameter is required for this resource; please visit http://developer.yahoo.com/wsregapp to get an appid

Be sure to provide the appid parameter for each GeoPlanet request you make.

404 Not Found

URI has no match in the display map

Be sure that you have spelled the resource correctly.

404 Resource Does Not Exist

Could not find the resource xxx

Be sure to provide a valid woeid in requests for this resource.

406 Not Acceptable

Requested representation not available for this resource

Be sure that you have included an Accept header or format parameter with a supported value.

Examples

Example 11. Retrieving a resource for the Place Using a Given WOEID

The request:

produces the following:

Example 12. Retrieving a Resource for the Place with a Given WOEID, in Short Representation

The request:

produces the following:

Example 13. Retrieving a Resource for the Place with a Given WOEID, in JSON format

The request:

produces the following:

{
"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).

Supported Query Parameters

The following query parameters are supported for this collection: lang, format, callback, select, and appid. The lang parameter allows a user to choose the language used in the response. The format parameter allows a user to choose the content type of the response (XML, JSON, GeoJSON). The callback parameter allows a user to encapsulate a JSON response within a JavaScript function call. The select parameter allows a user to choose the representation of the response (short, long). The appid parameter grants authorization to use the Web service, and is required.

Representations

The short representation contains three elements: woeid, placeTypeName, and name.

The long representation additionally contains these elements: country, admin1, admin2, admin3, locality1, locality2, postal, centroid, and boundingBox.

Possible Errors

The following errors can be returned:

400 Bad Request

A valid appid parameter is required for this resource; please visit http://developer.yahoo.com/wsregapp to get an appid

Be sure to provide the appid parameter for each GeoPlanet request you make.

404 Not Found

URI has no match in the display map

Be sure that you have spelled the resource correctly.

404 Resource Does Not Exist

Could not find the resource xxx

Be sure to provide a valid woeid in requests for the /place resource.

406 Not Acceptable

Requested representation not available for this resource

Be sure that you have included an Accept header or format parameter with a supported value.

Examples

Example 14. Retrieving a Resource for the Parent of a Given WOEID, as a Long Representation

The request:

produces the following:

/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

Supported Matrix Parameters

None

Supported Query Parameters

The following query parameters are supported for this collection: lang, format, callback, select, and appid. The lang parameter allows a user to choose the language used in the response. The format parameter allows a user to choose the content type of the response (XML, JSON, GeoJSON). The callback parameter allows a user to encapsulate a JSON response within a JavaScript function call. The select parameter allows a user to choose the representation of the response (short, long). The appid parameter grants authorization to use the Web service, and is required.

Representations

The short representation contains three elements: woeid, placeTypeName, and name.

The long representation additionally contains these elements: country, admin1, admin2, admin3, locality1, locality2, postal, centroid, and boundingBox.

Possible Errors

The following errors can be returned:

400 Bad Request

A valid appid parameter is required for this resource; please visit http://developer.yahoo.com/wsregapp to get an appid

Be sure to provide the appid parameter for each GeoPlanet request you make.

404 Not Found

URI has no match in the display map

Be sure that you have spelled the resource correctly and are using one of the supported filters for this collection.

404 Resource Does Not Exist

Could not find the resource xxx

Be sure to provide a valid woeid in requests for this collection.

406 Not Acceptable

Requested representation not available for this resource

Be sure that you have included an Accept header or format parameter with a supported value.

Examples

Example 15. Retrieving a Collection of Ancestors for a Given WOEID

The request:

produces the following:

/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

The only supported filter for this collection is .type. This filter allows a user to limit the results to one or more specified place types.

Supported Matrix Parameters

The following matrix parameters are supported for this collection: start, count. The start parameter allows a user to skip resources. The count parameter allows a user to control the number of resources to be returned. These parameters effectively provide a mechanism for paging through large result sets.

Supported Query Parameters

The following query parameters are supported for this collection: lang, format, callback, select, and appid. The lang parameter allows a user to choose the language used in the response. The format parameter allows a user to choose the content type of the response (XML, JSON, GeoJSON). The callback parameter allows a user to encapsulate a JSON response within a JavaScript function call. The select parameter allows a user to choose the representation of the response (short, long). The appid parameter grants authorization to use the Web service, and is required.

Representations

The short representation contains three elements: woeid, placeTypeName, and name.

The long representation additionally contains these elements: country, admin1, admin2, admin3, locality1, locality2, postal, centroid, and boundingBox.

Possible Errors

The following errors can be returned:

400 Bad Request

A valid appid parameter is required for this resource; please visit http://developer.yahoo.com/wsregapp to get an appid

Be sure to provide the appid parameter for each GeoPlanet request you make.

404 Not Found

URI has no match in the display map

Be sure that you have spelled the resource correctly and are using one of the supported filters for this collection.

404 Resource Does Not Exist

Could not find the resource xxx

Be sure to provide a valid woeid in requests for this collection.

406 Not Acceptable

Requested representation not available for this resource

Be sure that you have included an Accept header or format parameter with a supported value.

Example

Example 16. Retrieving a Collection of Belongto places of a Given WOEID

The request:

produces the following:

<?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

None

Supported Matrix Parameters

The following matrix parameters are supported for this collection: start, count. The start parameter allows a user to skip resources. The count parameter allows a user to control the number of resources to be returned. These parameters effectively provide a mechanism for paging through large result sets.

Supported Query Parameters

The following query parameters are supported for this collection: lang, format, callback, select, and appid. The lang parameter allows a user to choose the language used in the response. The format parameter allows a user to choose the content type of the response (XML, JSON, GeoJSON). The callback parameter allows a user to encapsulate a JSON response within a JavaScript function call. The select parameter allows a user to choose the representation of the response (short, long). The appid parameter grants authorization to use the Web service, and is required.

Representations

The short representation contains three elements: woeid, placeTypeName, and name.

The long representation additionally contains these elements: country, admin1, admin2, admin3, locality1, locality2, postal, centroid, and boundingBox.

Possible Errors

The following errors can be returned:

400 Bad Request

A valid appid parameter is required for this resource; please visit http://developer.yahoo.com/wsregapp to get an appid

Be sure to provide the appid parameter for each GeoPlanet request you make.

404 Not Found

URI has no match in the display map

Be sure that you have spelled the resource correctly and are using one of the supported filters for this collection.

404 Resource Does Not Exist

Could not find the resource xxx

Be sure to provide a valid woeid in requests for this collection.

406 Not Acceptable

Requested representation not available for this resource

Be sure that you have included an Accept header or format parameter with a supported value.

Examples

Example 17. Retrieving a Collection of Neighbor Places of a Given WOEID

The request:

produces the following:

/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).

Supported Filters

None

Supported Matrix Parameters

The following matrix parameters are supported for this collection: start, count. The start parameter allows a user to skip resources. The count parameter allows a user to control the number of resources to be returned. These parameters effectively provide a mechanism for paging through large result sets.

Supported Query Parameters

The following query parameters are supported for this collection: lang, format, callback, select, and appid. The lang parameter allows a user to choose the language used in the response. The format parameter allows a user to choose the content type of the response (XML, JSON, GeoJSON). The callback parameter allows a user to encapsulate a JSON response within a JavaScript function call. The select parameter allows a user to choose the representation of the response (short, long). The appid parameter grants authorization to use the Web service, and is required.

Representations

The short representation contains three elements: woeid, placeTypeName, and name.

The long representation additionally contains these elements: country, admin1, admin2, admin3, locality1, locality2, postal, centroid, and boundingBox.

Possible Errors

The following errors can be returned:

400 Bad Request

A valid appid parameter is required for this resource; please visit http://developer.yahoo.com/wsregapp to get an appid

Be sure to provide the appid parameter for each GeoPlanet request you make.

404 Not Found

URI has no match in the display map

Be sure that you have spelled the resource correctly and are using one of the supported filters for this collection.

404 Resource Does Not Exist

Could not find the resource xxx

Be sure to provide a valid woeid in requests for this collection.

406 Not Acceptable

Requested representation not available for this resource

Be sure that you have included an Accept header or format parameter with a supported value.

Examples

Example 18. Retrieving a Collection of Sibling Places of a Given WOEID

The request:

produces the following:

<?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>

Note

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

/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).

Supported Filters

The only supported filter for this collection is .type. This filter allows a user to limit the results to one or more specified place types.

Supported Matrix Parameters

The following matrix parameters are supported for this collection: start, count. The start parameter allows a user to skip resources. The count parameter allows a user to control the number of resources to be returned. These parameters effectively provide a mechanism for paging through large result sets.

Supported Query Parameters

The following query parameters are supported for this collection: lang, format, callback, select, and appid. The lang parameter allows a user to choose the language used in the response. The format parameter allows a user to choose the content type of the response (XML, JSON, GeoJSON). The callback parameter allows a user to encapsulate a JSON response within a JavaScript function call. The select parameter allows a user to choose the representation of the response (short, long). The appid parameter grants authorization to use the Web service, and is required.

Representations

The short representation contains three elements: woeid, placeTypeName, and name.

The long representation additionally contains these elements: country, admin1, admin2, admin3, locality1, locality2, postal, centroid, and boundingBox.

Possible Errors

The following errors can be returned:

400 Bad Request

A valid appid parameter is required for this resource; please visit http://developer.yahoo.com/wsregapp to get an appid

Be sure to provide the appid parameter for each GeoPlanet request you make.

404 Not Found

URI has no match in the display map

Be sure that you have spelled the resource correctly and are using one of the supported filters for this collection.

404 Resource Does Not Exist

Could not find the resource xxx

Be sure to provide a valid woeid in requests for this collection.

406 Not Acceptable

Requested representation not available for this resource

Be sure that you have included an Accept header or format parameter with a supported value.

Examples

Example 19. Retrieving a Collection of Children Places of a Given WOEID

The request:

produces the following:

<?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>

Note

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

/placetypes

Returns the complete collection of place types supported in GeoPlanet. The resources in the collection each describe a single place type. Additional placetypes will be included in future versions of GeoPlanet.

Supported Filters

The only supported filter for this collection is .type. This filter allows a user to limit the results to one or more specified place types.

Supported Matrix Parameters

The following matrix parameters are supported for this collection: start, count. The start parameter allows a user to skip resources. The count parameter allows a user to control the number of resources to be returned. These parameters effectively provide a mechanism for paging through large result sets.

Supported Query Parameters

The following query parameters are supported for this collection: lang, format, callback, select, and appid. The lang parameter allows a user to choose the language used in the response. The format parameter allows a user to choose the content type of the response (XML, JSON, GeoJSON). The callback parameter allows a user to encapsulate a JSON response within a JavaScript function call. The select parameter allows a user to choose the representation of the response (short, long). The appid parameter grants authorization to use the Web service, and is required.

Representations

The short representation contains the placeTypeName element.

The long representation additionally contains the description element.

Possible Errors

The following errors can be returned:

400 Bad Request

A valid appid parameter is required for this resource; please visit http://developer.yahoo.com/wsregapp to get an appid

Be sure to provide the appid parameter for each GeoPlanet request you make.

404 Not Found

URI has no match in the display map

Be sure that you have spelled the resource correctly and are using one of the supported filters for this collection.

404 Resource Does Not Exist

Could not find the resource xxx

Be sure to provide a valid woeid in requests for this collection.

406 Not Acceptable

Requested representation not available for this resource

Be sure that you have included an Accept header or format parameter with a supported value.

Examples

Example 20. Retrieving a Collection of Place Types

The request:

produces the following:

<?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 21. Retrieving a Collection of Place Types and their descriptions

The request:

produces the following:

<?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 22. Retrieving a Partial Collection of Place Types

The request:

produces the following:

/placetype

Returns a resource that describes a single place type.

Supported Query Parameters

The following query parameters are supported for this resource: lang, format, callback, select, and appid. The lang parameter allows a user to choose the language used in the response. The format parameter allows a user to choose the content type of the response (XML, JSON, GeoJSON). The callback parameter allows a user to encapsulate a JSON response within a JavaScript function call. The select parameter allows a user to choose the representation of the response (short, long). The appid parameter grants authorization to use the Web service, and is required.

Representations

The short representation contains the placeTypeName element.

The long representation additionally contains the description element.

Possible Errors

The following errors can be returned:

400 Bad Request

A valid appid parameter is required for this resource; please visit http://developer.yahoo.com/wsregapp to get an appid

Be sure to provide the appid parameter for each GeoPlanet request you make.

404 Not Found

URI has no match in the display map

Be sure that you have spelled the resource correctly and are using one of the supported filters for this collection.

404 Resource Does Not Exist

Could not find the resource xxx

Be sure to provide a valid woeid in requests for this collection.

406 Not Acceptable

Requested representation not available for this resource

Be sure that you have included an Accept header or format parameter with a supported value.

Examples

Example 23. Retrieving a short representation of the Resource for a Place Type

The request:

produces the following:

Example 24. Retrieving a long representation of the Resource for a Place Type

The request:

produces the following:

Reference

Summary

/places

Supported Filters

Supported Matrix Parameters

Supported Query Parameters

Representations

Possible Errors

Examples

/place/{woeid}

Supported Query Parameters

Representations

Possible Errors

Examples

/place/{woeid}/parent

Supported Query Parameters

Representations

Possible Errors

Examples

/place/{woeid}/ancestors

Supported Filters

Supported Matrix Parameters

Supported Query Parameters

Representations

Possible Errors

Examples

/place/{woeid}/belongtos

Supported Filters

Supported Matrix Parameters

Supported Query Parameters

Representations

Possible Errors

Example

/place/{woeid}/neighbors

Supported Filters

Supported Matrix Parameters

Supported Query Parameters

Representations

Possible Errors

Examples

/place/{woeid}/siblings

Supported Filters

Supported Matrix Parameters

Supported Query Parameters

Representations

Possible Errors

Examples

Note

/place/{woeid}/children

Supported Filters

Supported Matrix Parameters

Supported Query Parameters

Representations

Possible Errors

Examples

Note

/placetypes

Supported Filters

Supported Matrix Parameters

Supported Query Parameters

Representations

Possible Errors

Examples

/placetype

Supported Query Parameters

Representations

Possible Errors

Examples

Table of Contents