Key Concepts

Many of the Key Concepts here will be familiar to users of the GeoPlanet API; GeoPlanet is a core Yahoo! web service that can be used to obtain more information about the places returned by Placemaker, such as the relationship of one place to containing or adjacent places.

Places v. Place Names

Yahoo! Placemaker aims to capture all forms of how a place is called, and disambiguate the place-name to its canonical form. The platform identifies and disambiguates every place-name to a specific place concept, referenced by its unique identifier, the Where-on-Earth ID (WOEID). WOEIDs always reference a place, not a place name. For example, "New York", "New York City", "NYC", and "the Big Apple" are all variant names for WOEID 2459115. If Placemaker find these variants in the text, it will understand them to be multiple appellations of the same place.

This approach extends to a multi-lingual environment: "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, diacritical marks, and ligatures are not available to the user. All of these spatial appellations are simply multiple names for the same place, and therefore will be identified and understood as the same identifier (WOEID 676757).

Where On Earth Identifiers

Spatial entities identified by Yahoo! Placemaker are uniquely referenced by a positive 32-bit identifier: the Where On Earth ID (WOEID). WOEIDs are permanent and non-repetitive, and are assigned to all entities shared across Placemaker, GeoPlanet, Fire Eagle, Upcoming, and many other Yahoo! APIs. Read more about WOEIDs in the GeoPlanet Documentation on WOEIDs.

WOEIDs reference a particular geostatic named place, and are not used to refer to businesses or individual addresses. When it encounters a structured address, Placemaker will not perform street-level geocoding but will instead provide the WOEID of the smallest bounding named place known, frequently a postal code or neighborhood.

Coverage

Yahoo! Placemaker uses GeoPlanet data on the backend, consisting of several million named places globally. Coverage varies from country to country, and we're always improving it. Read more about our coverage in the GeoPlanet Documentation on Data; you can also download the GeoPlanet data for use in your own applications.

Place Types

Places are categorized to help identify the specific place you are searching for, such as a county and city of the same name. These Place Types have distinctive codes and names that are returned for each place. The complete list of Place Types may be found in the Yahoo! GeoPlanet Documentation on Place Types.

Language

Yahoo! Placemaker 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 multi-byte character set data in Japanese, Traditional Chinese, and Korean. To specify the language, set the inputLanguage query parameter to a code described by RFC 4646.

Positional Consistency

Places in Placemaker are primarily represented by WOEIDs, but we also return a coarse representation in Longitude/Latitude using the WGS84 datum. See more on how we work with positioning, space, and place in the GeoPlanet Documentation on Positional Consistency. WOEIDs returned by Placemaker can be passed onto the GeoPlanet API for further geographic exploration.

Document Scope

Some documents contain multiple place references within a geographic area, such as a county, state, or country. The geographic area associated with a document is called its Document Scope and is a place itself. Yahoo! Placemaker uses the place references in a document along with rules to determine the Document Scope. There are two flavors of Document Scope: Geographic Scope, and Administrative Scope. Geographic Scope is the place that best describes the document and may be of any place type. Administrative Scope is the place that best describes the document and has an administrative place type. The administrative place types are:

  • Country
  • State
  • County
  • Local Administrative Area
  • Town

For example, if your document contains the places "Bolinas", "San Francisco", and "Sacramento", we will return "California" (WOEID 2347563) as the Administrative Scope, and "Northern California" (WOEID 55857166) as the Geographic Scope. Sometimes the same WOEID will be returned for both.

Place Reference

A portion of text within a document that conveys geographic context is called a place reference. A place reference may be ambiguous, such as "Springfield" (there are 26 Springfields in the US alone), or unambiguous, such as "London, England". Yahoo! Placemaker identifies these place references and returns them in its response document, along with the actual text and list of WOEIDs that match each place reference. This makes it possible to highlight text and create links to content associated with the place reference.

Table of Contents