placemaker

= 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}[http://developer.yahoo.com/geo/placemaker/].

= 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}[http://gems.github.com]), 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, [e-mail]

Copyright (c) 2011 {Stack Builders Inc.}[http://stackbuilders.com]