This zip file contains data produced by the Yahoo! Geo Technologies group.

The zip file consists of:

* a set of 4 data files (.tsv)
* a license file (licence.txt)
* this file (readme.txt)

This is a stand-alone, platform independent data provision with no prerequisites.

Following is the layout of each data file:

filename: geoplanet_places_x.tsv

This file contains basic information about each named place known by GeoPlanet.

- 6 fields
* WOE_ID - primary "place" key
* ISO - ISO 3166-1 country/territory code
* Name - preferred local language or english place name
* Language - ISO 639-2(b) language code (see Supplemental Information)
* PlaceType - code indicating place class (see Supplemental Information)
* Parent_ID - WOEID of direct parent feature

Each place has a unique permanent identifier called its WOEID. The WOEID for a place will never change, but a place may be retired due to duplication or merging with another place. The parent place is the smallest administrative place (Country, State, County, LocalAdmin, Town, Suburb) that contains the place.

filename: geoplanet_aliases_x.tsv

This file contains alternative names for places.

- 4 fields
* WOE_ID - primary "place" key
* Name - alternative place name
* Name_Type - mnemonic describing name
* Language - ISO 639-2(b) language code

The Name_Type field is a single letter code that describes the alias as follows:
* P is a preferred English name
* Q is a preferred name (in other languages)
* V is a well-known (but unofficial) variant for the place (e.g. "New York City" for New York)
* S is either a synonym or a colloquial name for the place (e.g. "Big Apple" for New York), or a version of the name which is stripped of accent characters.
* A is an abbreviation or code for the place (e.g. "NYC" for New York)

Note that preferred means that for the language listed the "P" or "Q" should be used in preference to the "Normal" record in the geoplanet_places_x.tsv file.


filename: geoplanet_adjacencies_x.tsv

This file contains information about neighboring places.

- 4 fields
* Place_WOE_ID - WOEID of one place
* Place_ISO - ISO 3166-1 country/territory code
* Neighbour_WOE_ID - WOEID of neighorhing place
* Neighbour_ISO - ISO 3166-1 country/territory code

Each neighbor relationship occurs only once in this file. The country codes are provided to allow users to filter data for specific countries.


filename: geoplanet_changes_x.tsv

This file contains information about retired WOEIDs and their replacement WOEIDs.

- 3 fields
* Woe_id - WOEID that was retired
* Rep_id - WOEID to be used as a replacement
* Data_Version - Version in which the WOEID was retired

WOIEDs are never reused. WOEIDs that must be retired due to duplication or merging are added to this file, allowing users to determine the WOEID that replaces the retired WOEID.

Supplemental information:

Supported Languages:

* ARA - Arabic (Latin transcription)
* CHI - Chinese
* CZE - Czech
* DAN - Danish
* DUT - Dutch
* ENG - English
* FIN - Finnish
* FRE - French
* GER - German
* HUN - Hungarian
* ITA - Italian
* JPN - Japanese
* KOR - Korean
* NOR - Norwegian
* POL - Polish
* POR - Portuguese
* RUM - Romanian
* SPA - Spanish
* SWE - Swedish
* UNK - Unknown

Supported Placetypes:

* Airport - Commercial airport
* Colloquial - Unofficlal place name
* Continent - Africa, Antarctica, Asia, Australia, Europe, North America, South America
* Country - Place assigned an ISO 3166-1 code
* County - Second-level administrative area (Admin2)
* Drainage - River, Lake, etc
* Estate - Subdivision, housing development, mobile home park
* HistoricalCounty - Historical county
* HistoricalState - Historical state
* HistoricalTown - Historical town
* Island - Island
* LandFeature - National, state, or city park
* LocalAdmin - Third-level administrative area (Admin3)
* Miscellaneous - Unclassified place
* Ocean - Atlantic Ocean, Arctic Ocean, Indian Ocean, Pacific Ocean, Southern Ocean
* POI - Point of interest
* Sea - Sea, Bay, Channel
* Sport - Sports team
* State - First-level administrative area (Admin1)
* Suburb - City quarter, neighborhood, district
* Supername - Place covering multiple countries
* Timezone - Place described by an Olsen Timezone code
* Town - Incorporated or unincorporated populated place
* Zip - Full or partial postal code
* Zone - Metropolitan Statistical Area (MSA), Telephone Area Code

We are pleased to announce the release of GeoPlanet v1.3. This update includes several new features to help developers discover information about commonly used places, such as countries and administrative areas (states, counties), and link places with other places.

The new resources and collections in GeoPlanet v1.3 include:

/v1/place/{woeid}/descendants - return a list of places in the child hierarchy below a specified place
/v1/place/{woeid}/common/{woeid} - return the smallest place that is the ancestor of two or more places
/v1/continents - returns a list of places that are continents
/v1/oceans - return a list of places that are oceans
/v1/seas - return a list of places that are seas
/v1/countries - return a list of places that are countries or dependent areas
/v1/admin1s/{country} - return a list of places that are top-level administrative areas of a specified country
/v1/admin2s/{admin1} - return a list of second-level administrative areas of a specific top-level administrative area
/v1/admin3s/{admin2} - return a list of third-level administrative areas of a specific second-level administrative area
/v1/concordance/{namespace}/{id} - return information about identifiers used to refer to a place

Information about the Concordance resource will be covered in a separate topic. A list of the new features is provided at http://developer.yahoo.com/geo/geoplanet/g...tml#release_1_3. You can learn about all the resources and collections provided by GeoPlanet at http://developer.yahoo.com/geo/geoplanet/g...-reference.html.

We have also updated and streamlined the GeoPlanet documentation. Even if you are familiar with GeoPlanet, it may be worth rereading the documentation to learn about new ways to use GeoPlanet.

If you have questions regarding the new features, please post them to to the General Discussion Forum.

Eddie Babcock
Yahoo! Geo Technologies

Yahoo! Geo is pleased to announce an update to the Yahoo! GeoPlanet web service. Weve listened to your feedback and added several useful features to help you develop interesting applications using GeoPlanet.

First, we added a new query parameter called callback that allows GeoPlanet to return JSON data wrapped in a JavaScript function call (aka JSONP), so you can more easily process the GeoPlanet response within a JavaScript application and avoid cross-site serving issues.

Second, we added support for a new response format called GeoJSON. This is an evolving standard for adding geographic content to JSON.

Third, we added a new filter for the /places collection called $and. This filter allows you to apply two other filters (such as .q and .type) to the same request. This means that you can now limit results to just the place types you are interested in. The syntax for filters may seem strange, but it offers a lot of functionality.

Fourth, we added a /placetype resource that allows you to get information about a place type. This is handy if you want to find the name and/or description (see the next item) for a single place type.

Last, we added support for a long representation for the /placetype resource (and /placetypes collection) that includes a one line description of the place type. This is handy if you want a better understanding of a place type.

More detailed information about these new features is available in the GeoPlanet documentation, and examples are available on our GeoPlanet General Discussion Forum.

We also fixed several bugs reported by our developer community. We continue to view GeoPlanet as an evolving product, so let us know how we can make it better! Post a message to one of our GeoPlanet developer forums and tell us what you think.

Eddie Babcock
Principal Engineer, Yahoo! Geo Technologies

Welcome to the Product Announcements board for Yahoo! GeoPlanet. This is the place to learn about updated releases and new features added to GeoPlanet.

GeoPlanet is a versioned web service, which means that you must specify which version of the web service you are using in every request. Backward-compatible changes, such as new resources, supported formats, or elements will not change the version number. Backward-incompatible changes, such as resource name changes or deleted required elements will change the version number. We try to minimize the number of versions by making mostly backward-compatible changes, and consolidating backward-incompatible changes in a single release.