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:

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.

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, justin@stackbuilders.com

Copyright © 2011 Stack Builders Inc.