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
andlng
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.