GeoPlanet is a free (although with daily usage limits) geographical information database offered by Yahoo!. This post explores the information available in this database, and how to query it.
GeoPlanet is an excellent online resource to retrieve geographical information, that complements other sources such as Google Maps, GADM and OpenStreetmaps. Its database hold information about more than six million places all over the world, and it is hierarchically structured. Each entity in the database is a child of another entity of higher level. The database can be queried using an API based on HTTP GET requests. Although the service is offered at no charge, the requests must include an “application ID” obtained previously. On the other hand, Yahoo! imposes a limit of 2000 requests/day. In GeoPlanet, ach entity in the database is uniquely identified by its “WOEID” (Where On Earth ID).
Obtaining an application ID
The application ID is requested by filling and submitting the form at the registration page https://developer.apps.yahoo.com/wsregapp/, including a brief description of the intended usage: As part of the response, we are given the application ID as a 68 character identifier, that has to be included in the API calls.
Obtaining the WOEID and other geographical information of a given place
The request to get the WOEID for a given place name is made as in the following example for the sydney opera house:
The response from GeoPlanet is a XML document:
<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/28717584" xml:lang="en-GB"> <woeid>28717584</woeid> <placeTypeName code="20">Point of Interest</placeTypeName> <name>Sydney Opera House</name> <country type="Country" code="AU" woeid="23424748">Australia</country> <admin1 type="State" code="AU-NSW" woeid="2344700">New South Wales</admin1> <admin2/> <admin3/> <locality1 type="Town" woeid="1105779">Sydney</locality1> <locality2 type="Suburb" woeid="28676667">Sydney Central</locality2> <postal type="Postal Code" woeid="12706662">2000</postal> <centroid> <latitude>-33.857639</latitude> <longitude>151.214706</longitude> </centroid> <boundingBox> <southWest> <latitude>-33.859119</latitude> <longitude>151.213577</longitude> </southWest> <northEast> <latitude>-33.856159</latitude> <longitude>151.215836</longitude> </northEast> </boundingBox> <areaRank>0</areaRank> <popRank>0</popRank> </place> </places>
Note: For any request made to the GeoPlanet API, if the parameter “format=json” is added to the request, we can get the response in JSON format instead of XML:
Retrieve several possible results for a given place name
Sometimes, a place name may designate several different places. For instance, there are many towns and villages named Madrid or Toledo in different countries in America, besides the well known cities with those names in Spain. In the request made to GeoPlanet, we can specify a number of results:
The XML document returned includes several <place>…</place> elements:
<places xmlns="http://where.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="5" yahoo:total="15"> <place yahoo:uri="http://where.yahooapis.com/v1/place/766273" xml:lang="en-GB"> <woeid>766273</woeid> <placeTypeName code="7">Town</placeTypeName> <name>Madrid</name> <country type="Country" code="ES" woeid="23424950">Spain</country> <admin1 type="Autonomous Community" code="ES-M" woeid="12578024">Madrid</admin1> <admin2 type="Province" code="" woeid="12602090">Madrid</admin2> <admin3 type="Municipality" code="" woeid="12688024">Madrid</admin3> <locality1 type="Town" woeid="766273">Madrid</locality1> ... </place> <place yahoo:uri="http://where.yahooapis.com/v1/place/361938" xml:lang="en-GB"> ... </place> ... </places>
In this example, we can notice:
- The attributes “start” and “count” in the <places> element hold the values of the parameters in the request. The value of the “total” attribute is the total number of results in the database for the query performed. In the example, the database holds 15 entities with the name “madrid”, of which five have been returned in the response.
- The hierarchy is contained in the tags <admin[1,2,3]> and<locality[1,2]>. The WOEID of each of the entities in those tags is included in the response.
Retrieve the geographical information for a WOEID
The retrieved WOEIDs can be used to perform additional queries, using urls as in the example below:
We can also ask for the “parent” of an entity identified by its WOEID:
Note: The default response for this query returns only the “woeid”,”placeTypeName” and “name”. To retrieve all the available information for a given WOEID, we can add the parameter “select=long”, as in the example above.
Retrieve the name of the place identified by its WOEID in a different language (if it exists in the database)
For instance to retrieve the french name of the USA:
Retrieve a list of neighbors:
Retrieve the hierarchically related places
Entities with some kind of hierarchical relation to a given place identified by its WOEID can be retrieved with an url:
where RELATION can be one of: