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).
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.
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.
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.
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.
The following errors can be returned:
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.
Non empty q filter required for this resource
Be sure to provide the q filter in requests for the /places collection.
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.
Requested representation not available for this resource
Be sure that you have included an Accept header or format parameter with a supported value.
Example 8. Retrieving the Most Likely Place for a Given Place Name
The request:
http://where.yahooapis.com/v1/places.q(SFO)?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="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:
http://where.yahooapis.com/v1/places.q(CA)?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/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:
http://where.yahooapis.com/v1/places$and(.q(Long+Island),.type(Suburb));count=0?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="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>