/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:

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

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>

Yahoo! GeoPlanet