I created an UltraSmall™ ruby library for interfacing with Yahoo Local Search v2 a couple weeks ago and have finally put it up on RubyForge.org for the world to use. Here’s a quick tutorial (check out the Documentation):

Download and Install

You can check out it from my svn server:

svn co svn://www.last100meters.com/var/repos/local

Or download it from The RubyForge Page.

After downloading you can check out the Spec Tests written in [Rspec]. Run them from a terminal and make sure they pass:

spec spec

You should see this:

    Finished in 0.201256 seconds

    26 specifications, 0 failures

If you receive failures than something is working and you should contact me.

Rails Install

Put the local.rb file in the lib directory.

Delete the line:

require File.dirname(__FILE__) + '/lib/extensions'

The extensions file has a bunch of Ruby extensions that are already in Rails, so you don’t need them.

Thats it, you may need to require it with:

require 'local'

Other Install

Just:

require 'local'

Use

First set your Application ID from yahoo (link).

Local.app_id = ‘yourappidgoeshere’

Perform a search:

Local.search('pizza', :zip => 32304)

Limit the search scope to 20 miles radius:

Local.search('pizza', {:zip => 32304, :radius => 20.0})

Change number of results returned to 10

Local.search('pizza', {:zip => 32304, :results => 10})

Local.search returns an Array of Result objects. Each Result has these attributes:

* title - Name of the Result
* address - Street address of the result
* city - city in which the result is located
* state - Hmm…possibly the state where the result is located
* phone - push these numbers sequentually into phone device to talk directly with result
* latitude - lat of location
* longitude - see above but replace ‘lat’ with ‘long’ (thats what she said)
* rating - a Rating object
* distance - The distance as calculated by one of the following methods:
* When you enter a street address along with your search term, this is the distance from that particular street address to each result.
* When you enter your search term along with a city or a city and state, this is the distance from the city center to the business you‘re looking for.
* url - the URL to the detailed page for a business
* clickurl - The URL for linking to the detailed page for a business. See URL linking for more information.
* mapurl - The URL of a map for the address.
* businessurl - The URL of the business website, if known
* businessclickurl - The URL for linking to the businesses website if known. See URL linking for more information.

If your playing around with Local in irb or the console and you want to see all the attributes do this:

result.singleton_methods

Conclusion

This is my first Ruby Library that I have written. Using [Rspec] for testing really helped me refactor and build a good interface. Check Rspec out if you haven’t already.

Also, I am posting this from TextMate. I think I will be happy when TextMate becomes the new OS.