yelp 0.1.1

data/Manifest.txt

@@ -0,0 +1,24 @@
+History.txt
+LICENSE.txt
+Manifest.txt
+README.txt
+Rakefile
+TODO.txt
+lib/yelp.rb
+lib/yelp/client.rb
+lib/yelp/record.rb
+lib/yelp/response_format.rb
+lib/yelp/request.rb
+lib/yelp/neighborhood/request/base.rb
+lib/yelp/neighborhood/request/geo_point.rb
+lib/yelp/neighborhood/request/location.rb
+lib/yelp/phone/request/number.rb
+lib/yelp/review/request/base.rb
+lib/yelp/review/request/bounding_box.rb
+lib/yelp/review/request/geo_point.rb
+lib/yelp/review/request/location.rb
+test/test_client.rb
+test/test_neighborhood_search.rb
+test/test_phone_search.rb
+test/test_review_search.rb
+test/yelp_helper.rb

data/README.txt

@@ -0,0 +1,108 @@
+= 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.
+
+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/yelp.  This documentation is available at http://yelp.rubyforge.org.
+
+== 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) 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 set in your
+environment via (shell-dependent, bash example provided):
+
+    % export YWSID='YOUR_ID_HERE'
+
+== Installing
+
+We recommend installing <tt>yelp</tt> via rubygems[http://rubyforge.org/projects/rubygems/] (see also http://www.rubygems.org).
+
+Once you have +rubygems+ installed on your system, you can easily install the <tt>yelp</tt> gem by executing:
+
+% gem install --include-dependencies 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::Review::Request::BoundingBox
+* Yelp::Review::Request::GeoPoint
+* Yelp::Review::Request::Location
+* Yelp::Phone::Request::Number
+* Yelp::Neighborhood::Request::GeoPoint
+* Yelp::Neighborhood::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::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::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 neighborhood name lookup for a specific geo-location point
+    request = Yelp::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::Phone::Request::Number.new(
+                :phone_number => '4155551212',
+                :yws_id => 'YOUR_YWSID_HERE')
+    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, Walter Korman <shaper@wgks.org>, http://lemurware.blogspot.com

data/Rakefile

@@ -0,0 +1,17 @@
+require 'rubygems'
+require 'hoe'
+$:.unshift(File.dirname(__FILE__) + "/lib")
+require 'yelp'
+
+Hoe.new('yelp', Yelp::VERSION) do |p|
+  p.rubyforge_name = 'yelp'
+  p.author = 'Walter Korman'
+  p.email = 'shaper@wgks.org'
+  p.extra_deps = [ 'json', '>= 1.1.1' ]
+  p.summary = 'An object-oriented interface to the Yelp Developer API.'
+  p.description = 'An object-oriented interface to the Yelp Developer API.'
+  p.url = 'http://www.samskivert.com/shaper/yelp'
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.remote_rdoc_dir = '' # Release to root
+  # p.spec_extras = { :rdoc_options => '--main' << 'README' }
+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/yelp.rb

@@ -0,0 +1,16 @@
+require 'yelp/client'
+require 'yelp/record'
+require 'yelp/request'
+require 'yelp/response_format'
+require 'yelp/neighborhood/request/base'
+require 'yelp/neighborhood/request/geo_point'
+require 'yelp/neighborhood/request/location'
+require 'yelp/phone/request/number'
+require 'yelp/review/request/base'
+require 'yelp/review/request/bounding_box'
+require 'yelp/review/request/geo_point'
+require 'yelp/review/request/location'
+
+class Yelp
+  VERSION = '0.1.1'
+end

data/lib/yelp/client.rb

@@ -0,0 +1,103 @@
+require 'cgi'
+require 'logger'
+require 'open-uri'
+require 'rubygems'
+require 'json'
+require 'yaml'
+require 'zlib'
+
+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::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_params = { 'User-Agent' => @agent }
+      http_params['Accept-Encoding'] = 'gzip,deflate' if request.compress_response?
+      source = open(url, http_params)
+
+      # read the response content
+      content = (request.compress_response?) ? Zlib::GzipReader.new(source).read : source.read
+      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
+        url << '?'
+        param_count = 0
+        params.each do |key, value|
+          next if value.nil?
+          url << '&' if (param_count > 0)
+          url << "#{key}=#{CGI.escape(params[key].to_s)}"
+          param_count += 1
+        end
+        url
+      end
+  end
+end

data/lib/yelp/neighborhood/request/base.rb

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

data/lib/yelp/neighborhood/request/geo_point.rb

@@ -0,0 +1,23 @@
+require 'yelp/neighborhood/request/base'
+
+class Yelp
+  module Neighborhood
+    module Request
+      # Describes a request to search for the name of a neighborhood at a
+      # specific geo-point location.
+      #
+      class GeoPoint < Yelp::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

data/lib/yelp/neighborhood/request/location.rb

@@ -0,0 +1,53 @@
+require 'yelp/neighborhood/request/base'
+
+class Yelp
+  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::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

data/lib/yelp/phone/request/number.rb

@@ -0,0 +1,24 @@
+require 'yelp/request'
+
+class Yelp
+  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::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

data/lib/yelp/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/yelp/request.rb

@@ -0,0 +1,44 @@
+require 'yelp/record'
+
+class Yelp
+  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
+  end
+end