yelp4r 1.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Tom Cocca
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,41 @@
+yelp4r
+======
+
+Yelp4r is a Ruby wrapper for the Yelp API.  It utilizes the amazing HTTParty gem by John Nunemaker.
+If you need to build an API wrapper that gem is an enourmous help, refer to the following:
+
+http://railstips.org/2008/7/29/it-s-an-httparty-and-everyone-is-invited
+
+
+Yelp API Docs
+=========
+
+http://www.yelp.com/developers/documentation
+
+You will need to register for a Yelp API Key.
+
+
+USAGE
+==========
+
+See http://github.com/tcocca/yelp4r/tree/master/examples
+
+
+INSTALLATION
+==========
+
+sudo gem install yelp4r -s http://gemcutter.org
+
+
+QUESTION/CONCERNS/COMMENTS
+==========
+
+Send me an email through github or at tom dot cocca at gmail dot com
+Feel free to fork and submit changes
+There is a test suite built on rspec. 
+
+
+COPYRIGHT
+=========
+
+Copyright (c) 2008 Tom Cocca. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,60 @@
+require 'rake'
+require 'rake/rdoctask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "yelp4r"
+    s.summary = %Q{Yelp API wrapper in Ruby}
+    s.email = "tom.cocca@gmail.com"
+    s.homepage = "http://github.com/tcocca/yelp4r"
+    s.description = "Simple Ruby wrapper for the Yelp API built on HTTParty with parsers for available Neighborhoods and Categories"
+    s.files = [
+      "README",
+      "LICENSE",
+      "Rakefile",
+      "VERSION.yml",
+      "lib/yelp4r.rb",
+      "lib/rubyify_keys.rb",
+      "lib/yelp4r/categories.rb",
+      "lib/yelp4r/client.rb",
+      "lib/yelp4r/neighborhood_search.rb",
+      "lib/yelp4r/neighborhoods.rb",
+      "lib/yelp4r/phone_search.rb",
+      "lib/yelp4r/response.rb",
+      "lib/yelp4r/review_search.rb",
+      "spec/rcov.opts",
+      "spec/spec.opts",
+      "spec/spec_helper.rb",
+      "spec/fixtures/categories.html",
+      "spec/fixtures/neighborhoods.html",
+      "spec/yelp4r/categories_spec.rb",
+      "spec/yelp4r/client_spec.rb",
+      "spec/yelp4r/neighborhood_search_spec.rb",
+      "spec/yelp4r/neighborhoods_spec.rb",
+      "spec/yelp4r/phone_search_spec.rb",
+      "spec/yelp4r/review_search_spec.rb",
+      "examples/yelp.rb"
+    ]
+    s.authors = ["Tom Cocca"]
+    s.add_dependency 'httparty'
+    s.add_dependency 'nokogiri'
+    s.add_dependency 'mash'
+    s.add_development_dependency "rspec"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'yelp4r'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+task :default => :spec

data/VERSION.yml

@@ -0,0 +1,5 @@
+--- 
+:patch: 0
+:major: 1
+:minor: 1
+:build: 

data/examples/yelp.rb

@@ -0,0 +1,166 @@
+require File.dirname(__FILE__) + '/../lib/yelp4r'
+
+# Read the Yelp API Documentation
+# http://www.yelp.com/developers/documentation
+
+# Initialize a new Yelp Client
+client = Yelp4r::Client.new('your_ywsid_key')
+
+
+# Initialize a new Phone Search object
+phone_search = Yelp4r::PhoneSearch.new(client)
+
+# Phone search only does one thing, looks up a business by a phone number
+results = phone_search.search_by_phone_number('1234567890')
+
+# A response object is returned
+# The response is either a Mash Object or an array of Mash objects, these are hashes that have been converted into OpenStruct-esque objects
+# Also all keys have been rubyified, eg:  results.body['camelCase] is now results.body.camel_case
+# The following response methods are available to all Yelp searches in the 3 search classes
+#   PhoneSearch, ReveiwSearch, NeighborhoodSearch
+if results.success?
+  puts results.data          # Pure data of the repsonse
+  puts results.body          # Entire body of the response
+else
+  puts results.reponse_code  # Yelp repsonse code 
+  puts results.error_message # The text of the error message
+end
+
+
+# Initialize a Neighborhood Search Object
+neigh_search = Yelp4r::NeighborhoodSearch.new(client)
+
+# Search by a geocode point
+# Pass a Lat and Long respectively
+results = neigh_search.search_by_geocode(37.788022, -122.399797)
+
+# Search by a location (with optional country code)
+results = neigh_search.search_by_location('Boston, MA')
+# or
+results = neigh_search.search_by_location('Boston, MA', 'US')
+
+# Again the response methods above apply here as well
+
+
+# Initialize a Review Search Object
+review_search = Yelp4r::ReviewSearch.new(client)
+
+# Each search method for the review_search object takes the following optional parameters
+# :category => this is a Yelp category term (see the categories list below)
+# :term => this is a search term
+# :num_biz_requested => a number 1 through 20 (default is 10)
+
+# Search by a bouding box
+# Pass a top left lat/long and bottom right lat/long
+results = review_search.search_by_bounding_box(38, -122.6, 37.788022, -122.399797)
+results = review_search.search_by_bounding_box(38, -122.6, 37.788022, -122.399797, :term => "bars", :num_biz_requested => 15)
+
+# Search by geocode and radius
+# This method accepts and optional param of 
+# :radius => max of 25
+results = review_search.search_by_geocode_and_radius(37.788022, -122.399797)
+results = review_search.search_by_geocode_and_radius(37.788022, -122.399797, :radius => .5)
+results = review_search.search_by_geocode_and_radius(37.788022, -122.399797, :category => "bars", :radius => 1)
+
+# Search by location
+# This method accepts and optional params of:
+# :radius => max of 25
+# :cc => country code
+results = review_search.search_by_location('Boston, MA')
+results = review_search.search_by_location('Boston, MA', :num_biz_requested => 10)
+results = review_search.search_by_location('Boston, MA', :radius => 5)
+results = review_search.search_by_location('Boston, MA', :term => "doctors")
+
+# Again the response methods above apply here as well
+
+
+# Yelp4r provides a couple of html parsed lists powered by Hpricot
+# This first is the list of neighborhoods
+# see the page here: http://www.yelp.com/developers/documentation/neighborhood_list
+
+# Create a new Neighborhoods object
+neighborhoods = Yelp4r::Neighborhoods.new
+
+# Get the list
+# This list is designed to keep the parent and its children in a hash with the parent being the key and the children in an array
+# which is generated by a recursive function 
+# see the spec_helper method yelp4r_test_neighs_list for an example.
+
+puts neighborhoods.list
+
+# There is also a method to return a list of <option> tags to be used in a select tag in HTML
+# The method takes an optional string for selected or an array if used with a multiple select
+# The value of the options return the full string of the location
+
+puts neighborhoods.options_from_list
+# or
+puts neighborhoods.options_from_list('Deep Cove, Vancouver, BC, Canada')
+# or
+puts neighborhoods.options_from_list(['Vancouver, BC, Canada', 'Deep Cove, Vancouver, BC, Canada'])
+
+# To use this in a form see the following example:
+
+=begin
+  #controller
+  
+  def index
+    @neighs = Yelp4r::Neighborhoods.new
+  end
+
+  #view - index.html.erb
+  
+  <% form_tag "/yelp" do %>
+    <%= select_tag :neighs, @neighs.options_from_list(params[:neighs] || []) %>
+   <br />
+   <%= select_tag :mult_neighs, @neighs.options_from_list(params[:mult_neighs] || []), :multiple => true, :size => 10 %>
+   <br />
+   <%= submit_tag "submit" %>
+  <% end %>
+
+=end
+
+
+# The second parser is the list of categories.
+# See the page here: http://www.yelp.com/developers/documentation/category_list
+
+# Create a Categories object
+categories = Yelp4r::Categories.new
+
+# Get the list
+# As above the list keeps parents and children
+# However this list is different as there is a "display" value and the "input" or "parameter" value
+# In the hash the key is the "input" value, there is a :display value and if the element has children their is a :children value that is an array
+# see the spec_helper method yelp4r_test_cats_list
+
+puts categories.list
+
+# As with Neighborhoods there is also a method to return a list of <option> tags to be used in a select tag in HTML for Categories
+# The method takes an optional string for selected or an array if used with a multiple select
+# This works exactly the same as Neighborhoods
+
+puts categories.options_from_list
+# or
+puts categories.options_from_list("beaches")
+# or
+puts categories.options_from_list(["diving", "dancestudio", "golf"])
+
+# To use this in a form see the following example: (basically the same exact thing as neighborhoods)
+
+=begin
+  #controller
+  
+  def index
+    @cats = Yelp4r::Categories.new
+  end
+
+  #view - index.html.erb
+  
+  <% form_tag "/yelp" do %>
+    <%= select_tag :cats, @cats.options_from_list(params[:cats] || []) %>
+   <br />
+   <%= select_tag :mult_cats, @cats.options_from_list(params[:mult_cats] || []), :multiple => true, :size => 10 %>
+   <br />
+   <%= submit_tag "submit" %>
+  <% end %>
+
+=end

data/lib/rubyify_keys.rb

@@ -0,0 +1,29 @@
+class Hash
+ 
+  # Converts all of the keys to strings, optionally formatting key name
+  def rubyify_keys!
+    keys.each{|k|
+      v = delete(k)
+      new_key = k.to_s.to_underscore!
+      self[new_key] = v
+      v.rubyify_keys! if v.is_a?(Hash)
+      v.each{|p| p.rubyify_keys! if p.is_a?(Hash)} if v.is_a?(Array)
+    }
+    self
+  end
+ 
+end
+
+class String
+  
+  # converts a camel_cased string to a underscore string, 
+  # Same way ActiveSupport does string.underscore
+  def to_underscore!
+    self.to_s.gsub(/::/, '/').
+      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      tr("-", "_").
+      downcase
+  end
+  
+end

data/lib/yelp4r/categories.rb

@@ -0,0 +1,76 @@
+module Yelp4r
+  class Categories
+    
+    attr_accessor :parse_url
+    
+    def initialize
+      @parse_url = "http://www.yelp.com/developers/documentation/category_list"
+    end
+    
+    def list
+      require 'nokogiri'
+      require 'open-uri'
+      doc = Nokogiri::HTML(open(@parse_url))
+      html = doc.at("ul.attr-list")
+      neighborhoods = process_list(html)
+      return neighborhoods
+    end
+    
+    def options_from_list(selected = [])
+      selected_opts = selected.collect {|s| s.strip}
+      process_options(list, selected_opts)
+    end
+    
+    private
+    
+    def process_list(item)
+      item.children.find_all{|t| t.name == "li"}.map do |child|
+        unless child.inner_text.nil?
+          if child.next_sibling
+            next_list = child.next_sibling.name == "ul" ? child.next_sibling : child.next_sibling.next_sibling
+          end
+          if next_list && !next_list.children.find_all{|c| c.name == "li"}.empty?
+            str_vals = decode_string(child.inner_text)
+            {str_vals[2] => {:display => str_vals[1], :children => process_list(next_list)}}
+          elsif child.name == "li"
+            str_vals = decode_string(child.inner_text)
+            {str_vals[2] => {:display => str_vals[1]}}
+          end
+        end
+      end
+    end
+    
+    def decode_string(str)
+      /(.*)\s\(([^\)]*)/.match(str)
+    end
+    
+    def process_options(item, selected, depth = 0, options = [])
+      if item.is_a?(Hash)
+        depth += 1
+        item.each do |key, val|
+          opt_selected = selected.include?(key) ? ' selected="selected"' : ''
+          options << %(<option value="#{key}"#{opt_selected}>#{option_prefix(depth)}#{val[:display]}</option>)
+          process_options(val[:children], selected, depth, options) if val[:children]
+        end
+        depth -= 1
+      elsif item.is_a?(Array)
+        item.each do |i|
+          process_options(i, selected, depth, options)     
+        end
+      end
+      return options
+    end
+    
+    def option_prefix(depth)
+      s = ""
+      if depth > 1
+        (depth - 1).times do 
+          s += "&nbsp;-"
+        end
+        s += "&nbsp;"
+      end
+      return s
+    end
+    
+  end
+end

data/lib/yelp4r/client.rb

@@ -0,0 +1,13 @@
+module Yelp4r
+  class Client
+    
+    include HTTParty
+    base_uri 'api.yelp.com'
+    format :json
+    
+    def initialize(ywsid)
+      self.class.default_params :ywsid => ywsid
+    end
+    
+  end
+end

data/lib/yelp4r/neighborhood_search.rb

@@ -0,0 +1,28 @@
+module Yelp4r
+  class NeighborhoodSearch
+    
+    attr_accessor :client
+    
+    def initialize(client)
+      @client = client
+    end
+    
+    def search_by_geocode(lat, long)
+      options = {:lat => lat, :long => long}
+      process(options)
+    end
+    
+    def search_by_location(location, cc = "")
+      options = {:location => location}
+      options.merge!({:cc => cc}) unless cc.blank?
+      process(options)
+    end
+    
+    private
+    
+    def process(options)
+      Response.new(@client.class.get('/neighborhood_search', :query => options))
+    end
+    
+  end
+end

data/lib/yelp4r/neighborhoods.rb

@@ -0,0 +1,85 @@
+module Yelp4r
+  class Neighborhoods
+    
+    attr_accessor :parse_url
+    
+    def initialize
+      @parse_url = "http://www.yelp.com/developers/documentation/neighborhood_list"
+    end
+    
+    def list
+      require 'nokogiri'
+      require 'open-uri'
+      doc = Nokogiri::HTML(open(@parse_url))
+      html = doc.at("ul.attr-list")
+      neighborhoods = process_list(html)
+      return neighborhoods
+    end
+    
+    def options_from_list(selected = [])
+      selected_opts = selected.collect {|s| s.strip}
+      process_options(list, selected_opts)
+    end
+    
+    private
+    
+    def process_list(item)
+      item.children.find_all{|t| t.name == "li"}.map do |child|
+        unless child.inner_text.nil?
+          if child.next_sibling
+            next_list = child.next_sibling.name == "ul" ? child.next_sibling : child.next_sibling.next_sibling
+          end
+          if next_list && !next_list.children.find_all{|c| c.name == "li"}.empty?
+            {child.inner_text => process_list(next_list)}
+          elsif child.name == "li"
+            child.inner_text
+          end
+        end
+      end
+    end
+    
+    def process_options(item, selected, depth = 0, options = [], parent = "")
+      if item.is_a?(Hash)
+        depth += 1
+        item.each do |key, val|
+          unless parent.blank?
+            opt = "#{key}, #{parent}"
+          else
+            opt = key
+          end
+          opt_selected = selected.include?(opt) ? ' selected="selected"' : ''
+          options << %(<option value="#{opt}"#{opt_selected}>#{option_prefix(depth)}#{key}</option>)
+          process_options(val, selected, depth, options, opt)
+        end
+        depth -= 1
+      elsif item.is_a?(Array)
+        item.each do |i|
+          process_options(i, selected, depth, options, parent)     
+        end
+      else
+        depth += 1
+        unless parent.blank?
+          opt = "#{item}, #{parent}"
+        else
+          opt = item
+        end
+        opt_selected = selected.include?(opt) ? ' selected="selected"' : ''
+        options << %(<option value="#{opt}"#{opt_selected}>#{option_prefix(depth)}#{item}</option>)
+        depth -= 1
+      end
+      return options
+    end
+    
+    def option_prefix(depth)
+      s = ""
+      if depth > 1
+        (depth - 1).times do 
+          s += "&nbsp;-"
+        end
+        s += "&nbsp;"
+      end
+      return s
+    end
+    
+  end
+end

data/lib/yelp4r/phone_search.rb

@@ -0,0 +1,21 @@
+ module Yelp4r
+  class PhoneSearch
+    
+    attr_accessor :client
+    
+    def initialize(client)
+      @client = client
+    end
+    
+    def search_by_phone_number(phone)
+      process({:phone => phone})
+    end
+    
+    private
+    
+    def process(options)
+      Response.new(@client.class.get('/phone_search', :query => options))
+    end
+  
+  end
+end

data/lib/yelp4r/response.rb

@@ -0,0 +1,50 @@
+module Yelp4r
+  class Response
+    
+    attr_accessor :body
+    
+    def initialize(response)
+      @body = mash_response(response)
+    end
+    
+    def response_code
+      @body.message.code
+    end
+    
+    def success?
+      response_code == 0
+    end
+    
+    def error_message
+      @body.message.text unless success?
+    end
+    
+    def data
+      if !@body.businesses.blank?
+        @body.businesses
+      elsif !@body.neighborhoods.blank?
+        @body.neighborhoods
+      end
+    end
+    
+    private
+    
+    def mash_response(response)
+      if response.is_a?(Array)
+        @body = []
+        response.each do |b|
+          if b.is_a?(Hash)
+            @body << Mash.new(b.rubyify_keys!)
+          else
+            @body << b
+          end
+        end
+      elsif response.is_a?(Hash)
+        @body = Mash.new(response.rubyify_keys!)
+      else
+        @body = response
+      end
+    end
+    
+  end
+end

data/lib/yelp4r/review_search.rb

@@ -0,0 +1,33 @@
+ module Yelp4r
+  class ReviewSearch
+    
+    attr_accessor :client
+    
+    def initialize(client)
+      @client = client
+    end
+    
+    def search_by_bounding_box(tl_lat, tl_long, br_lat, br_long, optional = {})
+      options = {:tl_lat => tl_lat, :tl_long => tl_long, :br_lat => br_lat, :br_long => br_long}
+      process(options, optional)
+    end
+    
+    def search_by_geocode_and_radius(lat, long, optional = {})
+      options = {:lat => lat, :long => long}
+      process(options, optional)
+    end
+    
+    def search_by_location(location, optional = {})
+      options = {:location => location}
+      process(options, optional)
+    end
+    
+    private
+    
+    def process(options, optional)
+      options.merge!(optional) unless optional.blank?
+      Response.new(@client.class.get('/business_review_search', :query => options))
+    end
+  
+  end
+end

data/lib/yelp4r.rb

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'httparty'
+require 'mash'
+require 'rubyify_keys'
+
+require 'yelp4r/client'
+require 'yelp4r/phone_search'
+require 'yelp4r/neighborhood_search'
+require 'yelp4r/review_search'
+require 'yelp4r/response'
+require 'yelp4r/neighborhoods'
+require 'yelp4r/categories'

data/spec/fixtures/categories.html

@@ -0,0 +1,40 @@
+<html>
+  <body>
+    <div>
+        <div>
+        <ul class="attr-list">
+          <li>Active Life (active)</li>
+      		<ul>
+    		    <li>Amusement Parks (amusementparks)</li>
+          	<li>Fitness & Instruction (fitness)</li>
+      		  <ul>
+        			<li>Dance Studios (dancestudio)</li>
+        		  <li>Gyms (gyms)</li>
+        		  <li>Martial Arts (martialarts)</li>
+        		</ul>
+          </ul>
+          <li>Automotive (auto)</li>
+          <ul>
+			      <li>Auto Detailing (auto_detailing)</li>
+            <li>Auto Glass Services (autoglass)</li>
+          </ul>
+          <li>Shopping (shopping)</li>
+          <ul>
+            <li>Home & Garden (homeandgarden)</li>
+        		<ul>
+        			<li>Appliances (appliances)</li>
+        		  <li>Furniture Stores (furniture)</li>
+            </ul>
+            <li>Sporting Goods (sportgoods)</li>
+        		<ul>
+        			<li>Bikes (bikes)</li>
+        		  <li>Outdoor Gear (outdoorgear)</li>
+        		  <li>Sports Wear (sportswear)</li>
+        		</ul>
+        		<li>Thrift Stores (thrift_stores)</li>
+          </ul>
+        </ul>
+      </div>
+    </div>
+  </body>
+</html>