Description

Yahoo! Placemaker is a freely available geoparsing Web service. It helps developers make their applications location-aware by identifying places in unstructured and atomic content - feeds, web pages, news, status updates - and returning geographic metadata for geographic indexing and markup.

This library is a Ruby interface for accessing the Yahoo PlaceMaker API.

Installation

Assuming that you’ve set up your ruby environment to pull gems from GitHub (see the GitHub instructions if you haven’t yet done this), install placemaker with the following command:

sudo gem install jsl-placemaker

Usage

The following is an example of using the Placemaker gem to read places in a standard feed. You’ll have to get a Yahoo App ID first if you haven’t already done so.

require 'placemaker'
p = Placemaker::Client.new(:appid => YOUR_APP_ID, :document_url => 'http://feeds.nytimes.com/nyt/rss/HomePage', :document_type => 'text/xml')
p.fetch!

This will make a call to the Placemaker service and populate the Placemaker::Client object with data about the places in the content that you sent to Yahoo. The information that you’ll be interested in may be divided into “documents” and “meta-data.”

You can also use placemaker with a document that you upload. Use document_content in the configuration options instead of document_url, and make sure to set the appropriate value for document_type. Acceptable mime types are text/plain, text/html, text/xml, text/rss, application/xml, and application/rss+xml. The following is an example of using jsl-placemaker to encode content that you upload:

p = Placemaker::Client.new(:appid => YOUR_APP_ID, :document_content => 'railsconf was in las vegas this year', :document_type => 'text/plain')
p.fetch!

Afterwards, you have access to the same Placemaker::Client methods as if you had pointed placemaker to a document_url.

Documents

Once you’ve run the fetch! method on the Placemaker::Client, you may invoke the method documents which will return a set of Placemaker::Document objects corresponding to each of the entries in the feed given to the placemaker service. For example, if you gave a document_url pointing to a feed containing 15 entries, there will be 15 documents in the resulting client object.

The following are methods that you may invoke on each of the Placemaker::Document objects to find out more about the place information that Yahoo was able to glean from the input document:

place_details - Returns a Placemaker::Location object that is a container for one named place mentioned in the document
administrative_scope - Returns a Placemaker::Location object that is a container for the smallest administrative place that best describes the document
geographic_scope - Returns a Placemaker::Location object that is a container for the smallest place that best describes the document
extents - Returns a Placemaker::Extents object that is a container for the the map extents covering the places mentioned in the document

Below is a summary of the methods that these objects respond to. You may wish to browse the Placemaker rdoc files for these classes to see for more details.

Placemaker::Location

Placemaker::Location objects contain a woe_id, name, location_type and centroid.

woe_id - permanent identifier for the place
name - fully qualified name for the place
location_type - type name for the place
centroid - centroid for the place, responds to lat and lng

Placemaker::Extents

Placemaker::Extents are bounding boxes for an area of interest. They respond to methods for center, south_west and north_east. In all of these cases, they return a Placemaker::Coordinates object responding to lat and lng.

Meta-data

The request to the Yahoo place coding service returns information about the request. You may invoke the methods processing_time, version, and document_length to find out more about the request.

Author

Justin S. Leitgeb, [email protected]