Project

placemaker

0.01
No release in over 3 years
Low commit activity in last 3 years
placemaker is a Ruby client for the Yahoo Placemaker API. It uses the nokogiri and curb gems to help the user to efficiently query the Placemaker service and parse the XML response.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Runtime

>= 0
 Project Readme

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

Copyright © 2011 Stack Builders Inc.