yelpster 1.1.1

data/README.rdoc

@@ -0,0 +1,199 @@
+This is an expansion of the yelp api ruby gem written by Walter Korman. The gem has been extended to support version 2 of the yelp api. V2 supports business details retrieval via yelp id as well as searches for businesses using geo-point, bounding box or address/location. It also uses OAuth for authorization of requests.
+
+NOTE: Use of this code will break legacy code. You need to update all existing references to Yelp::Request::.. with Yelp::V1::Request::... Check out sample usage section for more information.
+
+The source for the original gem can be found here: http://github.com/shaper/yelp
+Following is the updated extract of the readme file. 
+
+--------------------------------------------------------------------------------
+
+== yelp
+
+A Ruby object-oriented interface to the local business content available
+on Yelp at http://www.yelp.com.  Functionality is provided to perform
+all searches available via the developer API including:
+
+* search for business reviews by geo-bounding-box, geo-point, or address/location.
+* search for a business review by business phone number.
+* search for a neighborhood by geo-point or address/location.
+* search for business details by geo-bounding-box, geo-point, or address/location.
+* retrieval of business details by specifying yelp id of business
+
+More detailed information on the underlying Yelp API, error response codes, and so forth is available at http://www.yelp.com/developers/getting_started.
+
+The RubyForge project is hosted at http://rubyforge.org/projects/yelpster.  This documentation is available at http://yelpster.rubyforge.org.
+
+The latest source code is at http://github.com/nvd/yelpster.
+
+== About
+
+Everybody loves Yelp! For those seeking burritos in the Mission District of
+San Francisco, it's easy to feel awash in a sea of taquerias with little to go
+on for decision-making other than whether the rice has peas in it (generally a
+negatory data point) or how long the line happens to be around lunchtime.
+
+Worry no longer! Yelp is here.
+
+Why should you use this library rather than writing directly to their API, or rolling your own?  A few reasons that come to mind:
+
+* we've done a variety of mini-legwork from which you, Yelp and our fellow netizens will benefit, such as making sure we inform the Yelp server that we support gzipped data over the wire to save on bandwidth.
+* we have rudimentary tests, whereas your implementation doesn't (since you haven't even written it yet).
+* we return responses (by default, configurable) as JSON data converted into a Ruby hash and appropriate data types where applicable.
+* (subjective but we know we're right) -- we think our API is a nicer layer for Ruby developers to work with than the bare-bones REST API that Yelp provides.
+
+== Requirements
+
+You must have a Yelp Web Service ID (YWSID) if you're using v1 of the api or Consumer Key, Consumer Secret, Token and a Token Secret for version 2. These are available at http://www.yelp.com/developers/getting_started/api_access.
+
+You must conform to the Yelp Branding Requirements when making use of content
+retrieved via their API, documented at http://www.yelp.com/developers/getting_started/api_branding.
+
+For tests to execute successfully you must have the YWSID (for v1) or CONSUMER_KEY, CONSUMER_SECRET, TOKEN and TOKEN_SECRET(for v2) set in your environment via (shell-dependent, bash example provided):
+
+ % export YWSID='YOUR_ID_HERE'
+
+or
+
+ % export CONSUMER_KEY='YOUR_CONSUMER_KEY_HERE'
+ % export CONSUMER_SECRET='YOUR_CONSUMER_SECRET_HERE'
+ % export TOKEN='YOUR_TOKEN_HERE'
+ % export TOKEN_SECRET='YOUR_TOKEN_SECRET_HERE'
+
+== Installing
+
+NOTE: At the moment, this source (and support for yelp api v2) has not been incorporated into the original gem. You can install the original gem following the instructions below
+
+Install +rubygems+ if you don't already have it.  See http://rubyforge.org/projects/rubygems/.
+
+Then install the +yelp+ gem by executing:
+
+ % gem install yelp
+
+== Usage
+
+Instantiate a Yelp::Client and use its +search+ method to make requests of
+the Yelp server.
+
+The available search request types are:
+
+* Yelp::V1::Review::Request::BoundingBox
+* Yelp::V1::Review::Request::GeoPoint
+* Yelp::V1::Review::Request::Location
+* Yelp::V1::Phone::Request::Number
+* Yelp::V1::Neighborhood::Request::GeoPoint
+* Yelp::V1::Neighborhood::Request::Location
+* Yelp::V2::Business::Request::Id
+* Yelp::V2::Search::Request::BoundingBox
+* Yelp::V2::Search::Request::GeoPoint
+* Yelp::V2::Search::Request::Location
+
+By default, response content is formatted as a Ruby hash converted from Yelp's
+source JSON response content. Alternate response formats (including the
+original pure JSON) can be specified on request record construction via the
+Yelp::[V1/V2]::Request +response_format+ parameter, available in all request record
+types.
+
+A few examples:
+
+ # construct a client instance
+ client = Yelp::Client.new
+
+ # perform an address/location-based search for cream puffs nearby
+ request = Yelp::V1::Review::Request::Location.new(
+             :address => '650 Mission St',
+             :city => 'San Francisco',
+             :state => 'CA',
+             :radius => 2,
+             :term => 'cream puffs',
+             :yws_id => 'YOUR_YWSID_HERE')
+ response = client.search(request)
+
+ # perform a location-based category search for either ice cream or donut shops in SF
+ request = Yelp::V1::Review::Request::Location.new(
+             :city => 'San Francisco',
+             :state => 'CA',
+             :category => [ 'donuts', 'icecream' ],
+             :yws_id => 'YOUR_YWSID_HERE')
+ response = client.search(request)
+
+ # perform a neighborhood name lookup for a specific geo-location point
+ request = Yelp::V1::Neighborhood::Request::GeoPoint.new(
+             :latitude => 37.782093,
+             :longitude => -122.483230,
+             :yws_id => 'YOUR_YWSID_HERE')
+ response = client.search(request)
+
+ # perform a business review search based on a business phone number
+ request = Yelp::V1::Phone::Request::Number.new(
+             :phone_number => '4155551212',
+             :yws_id => 'YOUR_YWSID_HERE')
+ response = client.search(request)
+
+ # retrieve details of business vi yelp business id
+ request = Yelp::V2::Business::Request::Id.new(
+			:yelp_business_id => "pjb2WMwa0AfK3L-dWimO8w",
+			:consumer_key => ‘YOUR_CONSUMER_KEY’,
+			:consumer_secret => ‘YOUR_CONSUMER_SECRET’,
+			:token => ‘YOUR_TOKEN’,
+			:token_secret => ‘YOUR_TOKEN_SECRET’)
+ response = client.search(request)
+
+ # search for businesses via bounding box geo coords'
+ request = Yelp::V2::Search::Request::BoundingBox.new(
+			:term => "cream puffs",
+			:sw_latitude => 37.900000,
+			:sw_longitude => -122.500000,
+			:ne_latitude => 37.788022,
+			:ne_longitude => -122.399797,
+			:limit => 3,
+			:consumer_key => ‘YOUR_CONSUMER_KEY’,
+			:consumer_secret => ‘YOUR_CONSUMER_SECRET’,
+			:token => ‘YOUR_TOKEN’,
+			:token_secret => ‘YOUR_TOKEN_SECRET’)
+ response = client.search(request)
+
+ # search for businesses via lat/long geo point'
+ request = Yelp::V2::Search::Request::GeoPoint.new(
+			:term => "cream puffs",
+			:latitude => 37.788022,
+			:longitude => -122.399797,
+			:consumer_key => ‘YOUR_CONSUMER_KEY’,
+			:consumer_secret => ‘YOUR_CONSUMER_SECRET’,
+			:token => ‘YOUR_TOKEN’,
+			:token_secret => ‘YOUR_TOKEN_SECRET’)
+ response = client.search(request)
+
+ # search for businesses via location (address, neighbourhood, city, state, zip, country, latitude, longitude)'
+ request = Yelp::V2::Search::Request::Location.new(
+			:term => "cream puffs",
+			:city => "San Francisco",
+			:consumer_key => ‘YOUR_CONSUMER_KEY’,
+			:consumer_secret => ‘YOUR_CONSUMER_SECRET’,
+			:token => ‘YOUR_TOKEN’,
+			:token_secret => ‘YOUR_TOKEN_SECRET’)
+ response = client.search(request)
+
+ request = Yelp::V2::Search::Request::Location.new(
+			:term => "german food",
+			:address => "Hayes",
+			:latitude => 37.77493,
+			:longitude => -122.419415,
+			:consumer_key => ‘YOUR_CONSUMER_KEY’,
+			:consumer_secret => ‘YOUR_CONSUMER_SECRET’,
+			:token => ‘YOUR_TOKEN’,
+			:token_secret => ‘YOUR_TOKEN_SECRET’)
+ response = client.search(request)
+
+If you want to convert some addresses to latitude/longitude, or vice
+versa, for testing or what have you -- try http://stevemorse.org/jcal/latlon.php.
+
+== License
+
+This library is provided via the GNU LGPL license at http://www.gnu.org/licenses/lgpl.html.
+
+== Authors
+
+Copyright 2007 - 2009, Walter Korman <shaper@fatgoose.com>, http://lemurware.blogspot.com
+
+2011 – Yelp V2 Additions by Naveed Siddiqui <naveed@10eighteen.com>
+

data/Rakefile

@@ -0,0 +1,19 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+$:.unshift(File.dirname(__FILE__) + "/lib")
+require 'yelpster'
+
+Echoe.new('yelpster', Yelp::VERSION) do |p|
+  p.author = 'Naveed Siddiqui'
+  p.email = 'naveed@10eighteen.com'
+  p.url = 'https://github.com/nvd/yelpster'
+  p.summary = 'An object-oriented interface to the Yelp Developer API.'
+  p.description = <<EDOC
+Extension of Korman's Ruby wrapper to interface with Yelp's REST API described in detail at:
+
+http://www.yelp.com/developers/getting_started
+EDOC
+  p.ignore_pattern = ["tmp/*", "script/*"]
+  p.runtime_dependencies = [ 'json >=1.1.1', 'oauth >=0.4.5' ]
+end

data/TODO.txt

@@ -0,0 +1,6 @@
+* look into rails partials inability to properly enumerate the response
+  business records with the :collection param.
+* think about how to gracefully report errors
+* should we use "require 'json/add/rails'" for json for rails happiness?
+* use SAX-based XML parsing rather than DOM
+* consider supporting keep-alive for high volume requests

data/lib/yelpster/client.rb

@@ -0,0 +1,105 @@
+require 'cgi'
+require 'logger'
+require 'rubygems'
+require 'json'
+require 'yaml'
+
+class Yelp
+  # Provides access to the Yelp search facilities as documented at:
+  #
+  # http://www.yelp.com/developers/documentation
+  #
+  # Example usage:
+  #
+  #    client = Yelp::Client.new
+  #    request = Yelp::V1::Review::Request::Location.new(
+  #                 :address => '650 Mission St',
+  #                 :city => 'San Francisco',
+  #                 :state => 'CA',
+  #                 :radius => 2,
+  #                 :term => 'cream puffs',
+  #                 :yws_id => 'YOUR_YWSID_HERE')
+  #    response = client.search(request)
+  #
+  # By default, response content is formatted as a Ruby hash converted from
+  # Yelp's source JSON response content.  Alternate response formats can be
+  # specified on request record construction via the Yelp::Request
+  # +response_format+ parameter, available in all request record types.
+  #
+  class Client
+    # allows specifying the user agent string to submit with search requests
+    attr_accessor :agent
+    
+    # whether debug mode is enabled for logging purposes, defaulting to false
+    attr_accessor :debug
+    
+    # the Logger compatible object with which log messages are outputted,
+    # defaulting to output to STDOUT
+    attr_accessor :logger
+
+    # the default user agent submitted with search requests
+    DEFAULT_AGENT = 'yelp for Ruby (http://www.rubyforge.org/projects/yelp/)'
+
+    # Constructs a new client that uses the supplied YWSID for submitting
+    # search requests.
+    #
+    def initialize
+      @agent = DEFAULT_AGENT
+      @debug = false
+      @logger = nil
+    end
+    
+    # Submits the supplied search request to Yelp and returns the response in
+    # the format specified by the request.
+    #
+    def search (request)
+      # build the full set of hash params with which the url is constructed
+      params = request.to_yelp_params
+
+      # construct the url with which we obtain results
+      url = build_url(request.base_url, params)
+      debug_msg "submitting search [url=#{url}, request=#{request.to_yaml}]."
+
+      # submit the http request for the results
+	    # http_request_params not used in v2 as OAuth (implemented in v2) only takes response params
+	    http_params = { 'User-Agent' => @agent }
+	    http_params['Accept-Encoding'] = 'gzip,deflate' if request.compress_response?
+	    content = request.pull_results(url, http_params)
+
+      # read the response content
+      debug_msg((request.response_format.serialized?) ? "received response [content_length=#{content.length}]." : "received response [content_length=#{content.length}, content=#{content}].")
+
+      # format the output as specified in the request
+      format_content(request.response_format, content)
+    end
+
+    protected
+
+      def format_content (response_format, content)
+        (response_format == Yelp::ResponseFormat::JSON_TO_RUBY) ? JSON.parse(content) : content
+      end
+
+      def debug_msg (message)
+        return if !@debug
+        @logger = Logger.new(STDOUT) if (!@logger)
+        @logger.debug message
+      end
+
+      def build_url (base_url, params)
+        url = base_url.clone
+		    unless params.nil?
+			    url << '?'
+			    param_count = 0
+			    params.each do |key, value|
+			      next if value.nil?
+			      url << '&' if (param_count > 0)
+			      key_str = (params[key].kind_of?(Array)) ? 
+				    params[key].map { |k| CGI.escape(k.to_s) }.join("+") : CGI.escape(params[key].to_s)
+			      url << "#{CGI.escape(key.to_s)}=#{key_str}"
+			      param_count += 1
+			    end
+		    end
+        url
+      end
+  end
+end

data/lib/yelpster/record.rb

@@ -0,0 +1,16 @@
+class Yelp
+  # General-purpose record that allows passing a hash with parameters
+  # to populate object attributes defined via methods like
+  # +attr_reader+ or +attr_accessor+.
+  #
+  class Record
+    def initialize (params)
+      if !params.nil?
+        params.each do |key, value| 
+          name = key.to_s
+          instance_variable_set("@#{name}", value) if respond_to?(name)
+        end
+      end
+    end
+  end
+end

data/lib/yelpster/response_format.rb

@@ -0,0 +1,36 @@
+require 'yelpster/record'
+
+class Yelp
+  # Describes the available response formats when querying the Yelp web
+  # service for results.
+  #
+  class ResponseFormat < Record
+    # the name of the response format
+    attr_reader :name
+    
+    # whether this response format returns serialized data (and, so, data that
+    # we probably don't want to print to a log file and suchlike)
+    attr_reader :serialized
+
+    # the format specifier to retrieve results as straight JSON content
+    JSON = Yelp::ResponseFormat.new(:name => 'json')
+  
+    # the format specifier to retrieve results as Ruby objects converted
+    # from the returned JSON content via the +json+ rubygem.
+    JSON_TO_RUBY = Yelp::ResponseFormat.new(:name => 'json_to_ruby')
+  
+    # the format specifier to retrieve results as a serialized Python
+    # response.  We're not quite sure why you'd want to use this if
+    # you're calling it from Ruby code, but we like to see completeness
+    # in an API.
+    PICKLE = Yelp::ResponseFormat.new(:name => 'pickle', :serialized => true)
+  
+    # the format specifier to retrieve results as a serialized PHP
+    # response.  We're not quite sure why you'd want to use this if
+    # you're calling it from Ruby code, but we like to see completeness
+    # in an API.
+    PHP = Yelp::ResponseFormat.new(:name => 'php', :serialized => true)
+
+    alias :serialized? :serialized
+  end
+end

data/lib/yelpster/v1/neighborhood/request/base.rb

@@ -0,0 +1,15 @@
+require 'yelpster/v1/request'
+
+class Yelp
+  module V1
+	  module Neighborhood
+		  module Request
+		    class Base < Yelp::V1::Request
+			    def base_url
+			      'http://api.yelp.com/neighborhood_search'
+			    end
+		    end
+      end
+    end
+  end
+end

data/lib/yelpster/v1/neighborhood/request/geo_point.rb

@@ -0,0 +1,25 @@
+require 'yelpster/v1/neighborhood/request/base'
+
+class Yelp
+  module V1
+	  module Neighborhood
+		  module Request
+		    # Describes a request to search for the name of a neighborhood at a
+		    # specific geo-point location.
+		    #
+		    class GeoPoint < Yelp::V1::Neighborhood::Request::Base
+			    # latitude of geo-point for which a neighborhood name is desired
+			    attr_reader :latitude
+
+			    # longitude of geo-point for which a neighborhood name is desired
+			    attr_reader :longitude
+
+			    def to_yelp_params
+			      super.merge(:lat => latitude,
+						            :long => longitude)
+			    end
+		    end
+      end
+    end
+  end
+end

data/lib/yelpster/v1/neighborhood/request/location.rb

@@ -0,0 +1,55 @@
+require 'yelpster/v1/neighborhood/request/base'
+
+class Yelp
+  module V1
+	  module Neighborhood
+   		module Request
+  		  # Describes a request to search for a neighborhood name for a specific
+  		  # address/location.  You do not need to specify all of the address
+  		  # attributes -- some subset of the core +address+, +city+,
+  		  # +state+ and +zipcode+ will suffice.
+  		  #
+  		  class Location < Yelp::V1::Neighborhood::Request::Base
+  			# the street address of the location sought
+  			attr_reader :address
+
+  			# the city of the location sought
+  			attr_reader :city
+
+  			# the state of the location sought
+  			attr_reader :state
+
+  			# the zipcode of the location sought
+  			attr_reader :zipcode
+
+  			def initialize (params)
+  			  # we explicitly initialize the location fields since we reference
+  			  # them later when building a full location string and we want
+  			  # to know they were initialized properly (and avoid warnings)
+  			  super({
+  				:address => nil,
+  				:city => nil,
+  				:state => nil,
+  				:zipcode => nil
+  				}.merge(params))
+  			end
+
+  			def to_yelp_params
+  			  super.merge(:location => build_location_string)
+  			end
+			
+  			protected
+
+  			  # Returns the Yelp-compatible concatenated string with the various
+  			  # possible bits of an address-oriented location.
+  			  #
+  			  def build_location_string
+  				# per the Yelp documentation, the location string is to be built
+  				# as some combination of "address, city, state, or zip".
+  				[ @address, @city, @state, @zipcode ].compact.join(" ")
+  			  end
+        end
+      end
+    end
+  end
+end

data/lib/yelpster/v1/phone/request/number.rb

@@ -0,0 +1,26 @@
+require 'yelpster/v1/request'
+
+class Yelp
+  module V1
+	  module Phone
+  		module Request
+  		  # Describes a request to search for a business review for the business
+  		  # associated with a specific phone number.
+  		  #
+  		  class Number < Yelp::V1::Request
+    			# the phone number of the business to search for, formatted as
+    			# '1112223333'.  Make sure you don't have any hyphens or parentheses.
+    			attr_reader :phone_number
+
+    			def base_url
+    			  'http://api.yelp.com/phone_search'
+    			end
+
+    			def to_yelp_params
+    			  super.merge(:phone => phone_number)
+    			end
+  		  end
+      end
+    end
+  end
+end

data/lib/yelpster/v1/request.rb

@@ -0,0 +1,55 @@
+require 'yelpster/record'
+require 'open-uri'
+require 'zlib'
+
+class Yelp
+  module V1
+	  class Request < Yelp::Record
+		# specifies whether the response content should be transmitted
+		# over the wire compressed, defaulting to true.
+		attr_reader :compress_response
+
+		# one of the Yelp::ResponseFormat format specifiers detailing the
+		# desired format of the search results, defaulting to
+		# Yelp::ResponseFormat::JSON_TO_RUBY.
+		attr_reader :response_format
+
+		# the Yelp Web Services ID to be passed with the request for
+		# authentication purposes.  See http://www.yelp.com/developers/getting_started/api_access
+		# to get your own.
+		attr_reader :yws_id
+
+		alias :compress_response? :compress_response
+
+		def initialize (params)
+		  default_params = {
+			:compress_response => true,
+			:response_format => Yelp::ResponseFormat::JSON_TO_RUBY
+			}
+		  super(default_params.merge(params))
+		end
+
+		def to_yelp_params
+		  params = {
+			:ywsid => yws_id
+		  }
+
+		  # if they specified anything other than a json variant, we
+		  # need to tell yelp what we're looking for
+		  case @response_format
+		  when Yelp::ResponseFormat::PICKLE 
+			  params[:output] = 'pickle'
+		  when Yelp::ResponseFormat::PHP 
+			  params[:output] = 'php'
+		  end
+
+		  params
+		end
+
+		def pull_results (url, http_params)
+		  source = open(url, http_params)
+		  content = (compress_response?) ? Zlib::GzipReader.new(source).read : source.read
+		end
+	  end
+   end
+end

data/lib/yelpster/v1/review/request/base.rb

@@ -0,0 +1,33 @@
+require 'yelpster/v1/request'
+
+class Yelp
+  module V1
+	  module Review
+  		module Request
+  		  class Base < Yelp::V1::Request
+    			# specifies the number of businesses to return in the result set.
+    			# default is 10.  minimum value is 1 and maximum value is 20.
+    			attr_reader :business_count
+
+    			# string representing the name of business or search term being
+    			# requested.
+    			attr_reader :term
+
+    			# optionally narrow the results by one or more categories.
+    			# may be a single string value, or an Array of multiple values.
+    			attr_reader :category
+
+    			def base_url
+    			  'http://api.yelp.com/business_review_search'
+    			end
+
+    			def to_yelp_params
+    			  super.merge(:term => term,
+    						  :num_biz_requested => business_count,
+    						  :category => category)
+    			end
+  		  end
+      end
+    end
+  end
+end

data/lib/yelpster/v1/review/request/bounding_box.rb

@@ -0,0 +1,39 @@
+require 'yelpster/v1/review/request/base'
+
+class Yelp
+  module V1
+	  module Review
+  		module Request
+  		  # Describes a request to search for business reviews for businesses
+  		  # within a geo-point-specific bounding box and radius around
+  		  # that box.
+  		  #
+  		  class BoundingBox < Yelp::V1::Review::Request::Base
+    			# bottom right latitude of bounding box
+    			attr_reader :bottom_right_latitude
+			
+    			# bottom right longitude of bounding box
+    			attr_reader :bottom_right_longitude
+			
+    			# radius to use while searching around specified geo-point.
+    			# default value is 1, maximum value is 25.
+    			attr_reader :radius
+			
+    			# top left latitude of bounding box
+    			attr_reader :top_left_latitude
+			
+    			# top left longitude of bounding box
+    			attr_reader :top_left_longitude
+
+    			def to_yelp_params
+    			  super.merge(:tl_lat => top_left_latitude,
+    						  :tl_long => top_left_longitude,
+    						  :br_lat => bottom_right_latitude,
+    						  :br_long => bottom_right_longitude,
+    						  :radius => radius)
+    			end
+    		end
+      end
+    end
+  end
+end

data/lib/yelpster/v1/review/request/geo_point.rb

@@ -0,0 +1,30 @@
+require 'yelpster/v1/review/request/base'
+
+class Yelp
+  module V1
+	  module Review
+  		module Request
+  		  # Describes a request to search for business reviews for businesses near
+  		  # a specific geo-point and radius around that point.
+  		  #
+  		  class GeoPoint < Yelp::V1::Review::Request::Base
+    			# latitude of geo-point to search near
+    			attr_reader :latitude
+
+    			# longitude of geo-point to search near
+    			attr_reader :longitude
+
+    			# radius to use while searching around specified geo-point.
+    			# default value is 1, maximum value is 25.
+    			attr_reader :radius
+
+    			def to_yelp_params
+    			  super.merge(:lat => latitude,
+    						  :long => longitude,
+    						  :radius => radius)
+    			end
+    		end
+      end
+    end
+  end
+end