A Ruby interface to the Yelp Developer API for searching local business information.
Pull request Compare This branch is 70 commits behind nvd:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


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: github.com/shaper/yelp Following is the updated extract of the readme file.


A Ruby object-oriented interface to the local business content available on Yelp at 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 www.yelp.com/developers/getting_started.

The RubyForge project is hosted at rubyforge.org/projects/yelpster. This documentation is available at yelpster.rubyforge.org.

The latest source code is at github.com/nvd/yelpster.


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.


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 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 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):





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 rubyforge.org/projects/rubygems/.

Then install the yelp gem by executing:

% gem install yelp


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::::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 stevemorse.org/jcal/latlon.php.


This library is provided via the GNU LGPL license at www.gnu.org/licenses/lgpl.html.


Copyright 2007 - 2009, Walter Korman <shaper@fatgoose.com>, lemurware.blogspot.com

2011 – Yelp V2 Additions by Naveed Siddiqui <naveed@10eighteen.com>