Spatial entities provided by Yahoo! GeoPlanet are referenced by a 32-bit identifier: the Where On Earth ID (WOEID). WOEIDs are unique and non-repetitive, and are assigned to all entities within the system. A WOEID, once assigned, is never changed or recycled. If a WOEID is deprecated it is mapped to its successor or parent WOEID, so that requests to the service using a deprecated WOEID are served transparently.
The world's geography is not static; Yahoo! GeoPlanet acknowledges this reality. We employ a significant number of automated and editorial processes that are designed to ensure the currency and accuracy of our geographic resource. Constant administrative, postal, and geographic processes render locations obsolete: cities grow to absorb adjacent towns and villages, postal codes are created, terminated, and modified on a frequent basis in most countries that have them, and new development replaces outdated infrastructure. In Japan, for example, the 'gappei' process constantly re-organises the nation’s official administrative geography by a method of merging, splitting, and redrawing geographical boundaries.
In cases where a place is stripped of its official status, Yahoo! will migrate the place to a historical category so that it can still be recognised, and its relationships to its successor places are updated so they can be discovered. Such places cease to be included in the administrative hierarchy. Their WOEIDs will remained unchanged.
In cases where a place is still current, yet has been redefined in respect of name, geometry or category, the WOEID will remain unchanged, and the attribution is updated to reflect the change.
As we continuously refine Yahoo! GeoPlanet there are times when we need to deprecate existing WOEIDs; there are two primary scenarios in which we will take this infrequent course of action:
Duplicate Places: where improved integration procedures or editorial intervention discovers that the same place is represented twice, usually due to naming, positional or categorisation irregularities.
For example, the place "CIA" was originally represented in GeoPlanet as a suburb category location, but subsequently identified as a match for the extant Airport 'Calgary International Airport'; the original WOEID for the suburb place was thus deprecated and mapped to the new WOEID for the Airport. The GeoPlanet API, however, continues to accommodate transparently and permanently the deprecated, duplicate WOEID. This approach to data management allows us to improve and refine the underlying resource without impacting offline content which has been indexed against it.
Invalid Places: where the detailed editorial evaluation process finds no corroborative information verifying a place's existence, or concludes that the place is out of GeoPlanet's scope.
In the rare instance when this occurs, it is usually due to the integration of historical locations that have no bearing to the 'real world', or situations where places are deemed to be unspecific or unverifiable.
In these situations, the WOEID of the invalid place will be deprecated and mapped to the WOEID of its parent place.