API Reference

Summary of Resources and Collections

The following resources and collections are provided:

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


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:


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:


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:


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


/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

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


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


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


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


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:


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


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

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

Response Data:


Example 25. Retrieving a Place That is Common Ancestor of Three Places

Request URI:

http://where.yahooapis.com/v1/place/2488042/common/2488836/2486340?appid=[yourappidhere]

Response Data:


/continents

Returns a collection of places that are continents.

Supported Filters

None

Example 26. Retrieving All Continents

Request URI:

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

Response Data:


/oceans

Returns a collection of places that are oceans.

Supported Filters

None

Example 27. Retrieving All Oceans

Request URI:

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

Response Data:


/seas

Returns a collection of places that are seas.

Supported Filters

None

Example 28. Retrieving All Seas

Request URI:

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

Response Data:


/seas/{place}

Returns a collection of places that are seas and are part of or adjacent to the specified continent or ocean.

Supported Filters

None

Example 29. Retrieving the Seas Adjacent to or Part of the Pacific Ocean

Request URI:

http://where.yahooapis.com/v1/seas/Pacific+Ocean?appid=[yourappidhere]

Response Data:


/countries

Returns a collection of places that are countries.

Supported Filters

None

Example 30. Retrieving All Countries

Request URI:

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

Response Data:


/countries/{place}

Returns a collection of places that are countries and are part of or adjacent to the specified continent or ocean.

Supported Filters

None

Example 31. Retrieving the Countries Within North America (NA)

Request URI:

http://where.yahooapis.com/v1/countries/NA?appid=[yourappidhere]

Response Data:


/states/{country}

Returns a collection of places that are top-level administrative areas (states) within a country.

Supported Filters

None

Example 32. Retrieving the States Within the United States (US)

Request URI:

http://where.yahooapis.com/v1/states/US?appid=[yourappidhere]

Response Data:


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

Supported Filters

None

Example 33. Retrieving the Counties Within California (CA)

Request URI:

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

Response Data:


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

Supported Filters

None

Example 34. Retrieving the Districts of Greater London

Request URI:

http://where.yahooapis.com/v1/districts/Greater+London?appid=[yourappidhere]

Response Data:


/admin3s/{admin2}

An alternative endpoint for /districts/{county}.

/concordance/{namespace}/{id}

Returns information that maps identifiers (codes) from other providers to WOEIDs. The following table lists the supported identifier providers.

Namespace Organization Place Types Country Description Reference
capost Canada Post Postal codes CA Postal codes defined by Canada Post http://www.canadapost.ca
ccltd IANA Countries all Country code top level domains assigned by IANA (Internet Assigned Numbers Authority) http://www.iana.org/domains/root/db
faa FAA Airports US Airport codes defined by FAA (Federal Aeronautics Agency) http://www.faa.gov
fips FIPS Countries, States, Counties, Towns all (countries); US (states, towns) Codes defined in FIPS 10-4 (countries), FIPS 5-2 ( US states), FIPS 6-4 (US counties), FIPS 55-3 (US places) http://earth-info.nga.mil/gns/html/digraphs.htm
geonames geonames.org Towns all Geonames identifiers http://www.geonames.org
iata IATA Airports all Airport codes defined by IATA (International Air Transport Association) http://www.iata.org
icao ICAO Airports all Airport codes defined by ICAO (International Civil Aviation Organization) http://www.icao.int
insee INSEE Towns FR Codes defined by INSEE for towns in France http://insee.fr/en
iso ISO Countries, States, Counties all Codes defined in ISO 3166-1 Alpha-2 (countries) and ISO 3166-2 (states, counties) http://www.iso.org
jgdc JGDC Admin, Towns, POIs JP Geographic codes for Japan places defined by Japan Geographic Data Center http://www.kokudo.or.jp
locode United Nations Towns all Codes defined in UN/Locode http://www.unece.org/cefact/locode
osm OpenStreetMap Airports, Towns all Place IDs from OpenStreetMap http://www.openstreetmap.org
usps USPS Postal codes US Zip codes defined by US Postal Service http://www.usps.com
wiki Wikipedia Airports, Towns US Page IDs for places in the US from en.wikipedia.org http://en.wikipedia.org

Example 35. Retrieving the WOEID and FIPs Code for a Given ISO Code

Request URI:

http://where.yahooapis.com/v1/concordance/iso/US-CA;appid=[yourappidhere]

Response Data:


/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
  • .type

Example 36. Retrieving a Collection of Place Types

Request URI:

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

Response Data:


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:


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:


Table of Contents