Key Concepts

Where On Earth Identifiers

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.

WOEID Management

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:

  1. 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.

  2. 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.

Coverage

Yahoo! GeoPlanet provides information for about six million named places globally. Coverage varies from country to country, but 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 millions of unique postal codes covering about 150 countries, plus a significant number of Points of Interest, Colloquial Regions, Airports, Area Codes, Time Zones, and Islands.

Note

Some Natural Features and Inland Water Geographies are included, but these feature classes are not fully supported in this release.

Hierarchy

Yahoo! GeoPlanet uses a hierarchical model for places that provides both vertical consistency and horizontal consistency of place geography. The model ensures that places in each layer in the hierarchy overlay the correct and corresponding places in other layers, and that geographical relationships are preserved. The hierarchy allows developers to query the geographic context of every named place represented by a WOEID.

Every place belongs to a number of containing, superior (larger) geographic entities, and in turn may contain a number of inferior (smaller) geographic entities. The smallest fully containing official geographical entity for a place is called its parent. The list of containing official geographic entities for a place is called its ancestors. The fully contained geographic entities for a place are called its children.

The hierarchy recognizes a distinction between "official" administrative places, such as country, state, county, and city, and "informal" places, such as colloquial places and historical administrative places. These informal places are included in a separate collection called belongtos.

A place can have both official and informal children. Consider three examples:

"Paul Revere House"

A Point of Interest (POI) place type whose "parent" is North End (neighbourhood), its "ancestors" are North End, Boston (town), Suffolk (county), Massachusetts (state), US (country) and of course, the Earth (you are here).

Additionally it "belongsto" 02114 (zipcode), 617 + 857 (area codes), Boston-Cambridge-Quincy (Metro Statistical Area), New England (colloquial), America/New York (Timezone), and North America (continent)

"The Bay Area"

A colloquial place type whose "parent" is California (state), its "ancestors" are California (state), US (country), and Earth, while its "children" include Alameda, Contra Costa, Marin, Napa, San Francisco, San Mateo, Santa Clara, Solano, Sonoma (counties)

Descdendents include all of the GeoPlanet entities (Towns, Neighborhoods, Points of Interest, Airports) that have these 9 counties as ancestors.

"94089"

A postal code place type, is found in three countries: United States, Germany, Mexico. The US place has "parent" Sunnyvale (town), and "ancestors" Sunnyvale (town), Santa Clara (county), California (state), US (country), and the Earth.

Additionally it "belongsto" 408 (area code), San Jose-Sunnyvale-Santa Clara (MSA), San Francisco Bay Area (colloquial), Silicon Valley (colloquials), America/Los Angeles (Timezone), and North America (continent).

Relationships

Places have relationships with other places; Yahoo! GeoPlanet allows users to identify places that have specific relationships to others, such as the parent, children, and neighbors. For example, a list of states (or first-level administrative areas) in a particular country can be obtained by requesting the children of that country; in a similar manner, the surrounding postal codes of a particular postal code can be obtained via a call for its neighbors. The following relationships are provided by GeoPlanet:

Parent

A direct superior to a given place. For example, California (WOEID 2347563) is a child of the United States (WOEID 23424977), and conversely the United States is the parent of California. In this version of GeoPlanet, places have only one parent.

Children

The direct inferiors to a given place. Children can be of different place types, so the children of California (WOEID 2347563) include its 58 counties, as well as its colloquial entities (High Sierra, Wine Country, Central Valley, etc.), and Zones (MSA Redding, MSA Salinas, etc.).

Neighbors

Places adjacent to a given place. For example, California (WOEID 2347563) is adjacent to Nevada (WOEID 2347587), Oregon (WOEID 2347596), Arizona (WOEID 2347561), and Baja California in Mexico (WOEID 2346265); these are all neighbors of California.

Note

Neighboring places are near each other, but might not share a border.

Siblings

Places that share the same parent and have the same place type. For example, California has 50 siblings: the other 49 states, plus the District of Columbia.

Belongtos

Places that include a given place as one of their children, or their children's children, etc. The given place "belongs to" these places. For example, California (WOEID 2347563) is a child of the place named "Pacific States" (WOEID 23689940); Pacific States therefore is therefore a "belongto" of California (we realize that we are taking some liberties with the English language here).

Ancestors

Places in the chain of parents for a given place. For example, San Jose (WOEID 2488042) is a child of Santa Clara County (WOEID 12587712), which in turn is a child of California (WOEID 2347563), which is in turn a child of the United States (WOEID 23424977). Santa Clara County, California, and the United States are all ancestors of San Jose.

Place Types

Places are categorized to help identify the place. These Place Types have unique codes that may be used to filter results for some resources. They also have localized names, so they can be displayed along with the localized place name. The following table lists the supported place types.

Place Type Name Place Type Code Description
Continent 29 One of the major land masses on the earth. GeoPlanet is built on a seven-continent model: Asia (24865671), Africa (24865670), North America (24865672), South America (24865673), Antarctica (28289421), Europe (24865675), and Pacific (Australia, New Zealand, and the other islands in the Pacific Ocean -- 24865674).
Country 12 One of the countries and dependent territories defined by the ISO 3166-1 standard.
Admin 8 One of the primary administrative areas within a country. Place type names associated with this place type include: State, Province, Prefecture, Country, Region, Federal District.
Admin2 9 One of the secondary administrative areas within a country. Place type names associated with this place type include: County, Province, Parish, Department, District.
Admin3 10 One of the tertiary administrative areas within a country. Place type names associated with this place type include: Commune, Municipality, District, Ward.
Town 7 One of the major populated places within a country. This category includes incorporated cities and towns, major unincorporated towns and villages.
Suburb 22 One of the subdivisions within a town. This category includes suburbs, neighborhoods, wards.
Postal Code 11 One of the postal code areas within a country. This category includes both full postal codes (such as those in UK and CA) and partial postal codes. Examples include: SW1A 0AA (UK), 90210 (US), 179-0074 (JP).
Supername 19 A place that refers to a region consisting of multiple countries or an historical country that has been dissolved into current countries. Examples include Scandinavia, Latin America, USSR, Yugoslavia, Western Europe, and Central America.
Colloquial 24 Examples are New England, French Riviera, 関西地方(Kansai Region), South East England, Pacific States, and Chubu Region.
Time Zone 31 A place that refers to an area defined by the Olson standard. Examples include America/Los Angeles, Asia/Tokyo, Europe/Madrid.

Language

Yahoo! GeoPlanet is UTF-8 compliant and supports location names for usage variations and in multiple languages, including English, French, German, Italian, Spanish as well as local double-byte character set data in Japanese, Traditional Chinese, and Korean.

Yahoo! GeoPlanet aims to capture all forms of how a place is called. For example, "München" in Germany is "Munich" to the English speaking world and "Monaco di Bavaria" to the Italians, but may also be keyed as "Muenchen" and "Munchen" if special characters, diacritic marks, and ligatures are not available to the user. All of these spatial appellations are simply multiple names for the same place, and therefore reside within GeoPlanet mapped to the same WOEID (676757).

The following table lists the supported languages for Yahoo! GeoPlanet.

Code(s) Description
en-US US English
en-GB, en UK English
en-CA CA English
en-AU AU English
en-ZA ZA English
fr-FR, fr FR French
fr-CA CA French
it-IT, it Italian
es-ES, es Spanish
es-US US Spanish
es-MX MX Spanish
de-DE, de DE German
de-AT AT German
zh-TW TW Chinese (traditional)
zh-hant-TW TW Chinese (traditional)
zh-HK HK Chinese (traditional)
zh-hant-HK HK Chinese (traditional)
zh-MO MO Chinese (traditional)
zh-hant-MO MO Chinese (traditional)
zh-CN CN Chinese (simplified)
zh-hans-CN CN Chinese (simplified)
zh-SG SG Chinese (simplified)
zh-hans-SG SG Chinese (simplified)
ja-JP, ja JP Japanese
ko-KR KR Korean
vi-VN VN Vietnamese
el-GR GR Greek
ru-RU RU Russian

Codes for Continents and Oceans

The following codes may be used for continents and oceans in the /seas and /countries collections:

Code Description
AF Africa
AN Antarctica
AS Asia
AU Australia
EU Europe
NA North America
SA South America
AR Arctic Ocean
AT Atlantic Ocean
IN Indian Ocean
PA Pacific Ocean
SO Southern Ocean

Positional Consistency

Places in GeoPlanet are coarsely represented in Longitude/Latitude coordinates using the WGS84 datum. We have chosen to represent all places within a single positional context to ensure that content is organized in a consistent way globally. GeoPlanet also recognizes that a place has a center and an area of influence and represents these respectively by its centroid and its bounding box. Thus every place within each theme has a geometric description. Different areas within different themes overlap to enable the most granular location for an address to be found.

We provide coordinates where available; some entities in GeoPlanet may not have coordinates, but these can usually be derived from the parent and child geometries.

GeoPlanet is not a feature server. The coordinates it provides are illustrative, not normative; we do not aim to be the authority on the exact bounds of any particular place (and leave this debate to others). Our concern is instead to provide a common naming convention, and to ensure that places are correctly represented in relation to each other in a global, consistent framework. In practice this means that we are not in a position to claim that a particular neighborhood stops at one block and starts at the next, only that the concept of that neighborhood be identified consistently. Our primary concerns are relative -- not absolute -- geography, and the semantics of place.

Short and Long Representations

GeoPlanet provides two different representations of the place and placeType resources: the short representation, and the long representation.

The short representation contains only the most essential information about the resource. For place resources, the short representation contains three elements: woeid, placeTypeName, and name. For place type resources, the short representation contains only the placeType element.

The long representation incudes additonal elements. For place resources, the long representation additionally contains these elements: country, admin1, admin2, admin3, locality1, locality2, postal, centroid, boundingBox, areaRank, and popRank. For place type resources, the long representation additionally contains the description element.

The default representation will depend on the resource or collection that is requested.

Example 1. Short Representation of Place Resource


Example 2. Long Representation of Place Resource


Example 3. Short Representation of PlaceType Resource


Example 4. Long Representation of PlaceType Resource


Table of Contents