This week Yahoo announced its new Internet Location Platform API, "a resource for managing all geo-permanent named places on Earth" that "provide[s] the Yahoo! Geographic Developer Community with the vocabulary and grammar to describe the world's geography in an unequivocal, permanent, and language-neutral manner." (For more details see our new API profile.)
The RESTful read-only API associates "almost any named place on the Earth" with a unique identifier (called a "Where on Earth ID" or WOEID). Using Berkeley, California as an example you can see how the API uses WOEIDs to tell you about the relationship among locations. First, to look up the WOEID for Berkeley, CA:
returns an XML response tells you, among other things, the WOEID for Berkeley, CA (2362930), the centroid of Berkeley (37.869499, -122.270531), and a bounding box for the city. For a given WOEID, you can get the same data. In our example,
resolves the WOEID of 2362930 back to Berkeley, CA.
The Yahoo! Internet Location Platform describes the relationships among locations in a variety of hierarchies. First of all, there is the concept of a locations' parent. Any given WOEID has at most one parent. You can get the parent Berkeley, CA with
which returns a detailed record for Alameda County, the county in which Berkeley is located. You can then ask the API for the entire parent-oriented hierarchy (a WOEID's parent, parent's parent, etc.) with
You can use the API to ask for the children of a WOEID. The URL
returns the locations whose parent is Berkeley, CA. You'll see a variety of place types in the list, including "suburbs" (e.g., South Berkeley) and zip codes (e.g., 94703). Note the use of the matrix parameter count to increase the number of children returned to up to 100.
Not surprisingly, you can ask for the siblings of a WOEID, all the other locations that share the same parent. Among the siblings of Berkeley, CA listed in http://where.yahooapis.com/v1/place/2362930/siblings;count=100 are such places as Albany, Oakland, and Union City, which are other cities located in Alameda County.
What makes the Yahoo! Internet Location Platform especially interesting is how it supports "unofficial" or "informal" relationships beyond the strict one-parent-at-most hierarchy in belongtos and neighbors methods. The URL
returns "neighbors" to Berkeley, CA including Albany (which has the same parent as Berkeley) but also El Cerrito (which has a different parent, namely, Contra Costa County). It's puzzling, however, why Oakland is not considered a neighbor to Berkeley. I suppose the caveat that "that neighbors are not necessarily geographically contiguous" can be extended to "geographically continguous locations are not necessarily neighbors".
Or by using the belongtos verb you can learn about various informal aggregations. The URL
Finally, there's support for "location names in multiple languages including English, French, German, Italian, Spanish and Dutch as well as local double-byte character set data in Japan, Hong Kong, Korea and Taiwan." For example, look at record for the USA in English, French, and Chinese.
However, will WOEIDs be widely adopted outside of the context of using Yahoo!'s services? The breadth of coverage should be attractive to many developers:
The Yahoo! Internet Location Platform contains about six million places. Coverage varies from country-to-country but globally includes several hundred thousand unique administrative areas with half a million variant names; several thousand historical administrative areas; over two million unique settlements and suburbs, and two-and-a-half million unique postcode points covering about 150 countries, plus a significant number of points of interest, Colloquial Regions, Area Codes, Time Zones, and Islands.
However, there are important questions of ownership/restrictions on this data the possibility of lock-in. It'd be interesting, for instance, to compare the functionality and depth of the Yahoo! Internet Location Platform with the data and services currently in the GeoNames API (see its ProgrammableWeb profile and the list of 38 mashups using the API.) On a technical note, the current API doesn't seem to support reverse geocoding (to return a place name for a given latitude and longitude), functionality found in the Flickr API and GeoNames API).