In simple terms, the Service allows you to look up the unique identifier - called the Where on Earth ID, or WOEID - for almost any named place on the Earth; it also allows you to resolve a WOEID you have received from a third party - such as Fire Eagle™ or Upcoming - to the place it represents.
The API is accessed via HTTP GET; the following examples can be cut-and-paste into a web browser to view the results:
Find the WOEID of a significant landmark: where.yahooapis.com/v1/places.q(‘sydney%20opera%20house’)
Resolve a WOEID to a place: where.yahooapis.com/v1/place/2507854
Find the WOEID of a specific place: where.yahooapis.com/v1/places.q(‘northfield%20mn%20usa’)
Obtain a range of WOEIDs that match a given place, ordered by the most likely: where.yahooapis.com/v1/places.q(‘springfield’);start=0;count=5
Find the parent of a given WOEID (and return a detailed record): where.yahooapis.com/v1/place/638242/parent?select=long
Return the Placename for a given WOEID in a specific language (where it exists): where.yahooapis.com/v1/places.q(‘usa’)?lang=fr
To obtain the representation of a place in JSON format: where.yahooapis.com/v1/place/2487956?format=json
To obtain a list of geographies that neighbor a specific WOEID: where.yahooapis.com/v1/place/12795711/neighbors