Skip to content
A Ruby interface to the Yelp Developer API for searching local business information.
Branch: master
Clone or download
Pull request Compare This branch is 75 commits ahead, 2 commits behind shaper:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status Dependency Status

A Ruby object-oriented interface to the local business content available on Yelp at 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

This documentation is available at

The latest source code is at


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

You must conform to the Yelp Branding Requirements when making use of content retrieved via their API, documented at

For tests to execute successfully you must have the YWSID (for v1) or YELP_CONSUMER_KEY, YELP_CONSUMER_SECRET, YELP_TOKEN and YELP_TOKEN_SECRET(for v2) set in your environment via (shell-dependent, bash example provided):





 gem install yelpster

and in your gemfile:

 gem 'yelpster'


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

You can include the overlying module to cut back on typing or in case of conflicts between classes, use the fully qualified search request class name.

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.

One Time Client Configuration (Recommended)

To configure token/keys, add the following in a pre-loader file (eg: in initializers dir for Rails). Although currently available, support for specifying keys in request object will be deprecated in the future.

For example, you might have a 'yelp.rb' file in your 'config/initializers' directory that looks like the following:

Yelp.configure(:yws_id          => 'YOUR_YWSID',
               :consumer_key    => 'YOUR_CONSUMER_KEY',
               :consumer_secret => 'YOUR_CONSUMER_SECRET',
               :token           => 'YOUR_TOKEN',
               :token_secret    => 'YOUR_TOKEN_SECRET')

Then create a client object (or use Yelp::Base.client) and call search method with the request object.

A few examples:

 # construct a client instance
 client =

 include Yelp::V1::Review::Request
 # perform an address/location-based search for cream puffs nearby
 request =
             :address => '650 Mission St',
             :city => 'San Francisco',
             :state => 'CA',
             :radius => 2,
             :term => 'cream puffs')
 response =

 # perform a location-based category search for either ice cream or donut shops in SF
 request =
             :city => 'San Francisco',
             :state => 'CA',
             :category => ['donuts', 'icecream'])
 response =

 # perform a neighborhood name lookup for a specific geo-location point
 request =
             :latitude => 37.782093,
             :longitude => -122.483230)
 response =

 # -------------------------------------------------------

 include Yelp::V1::Phone::Request
 # perform a business review search based on a business phone number
 request =
             :phone_number => '4155551212')
 response =

 # -------------------------------------------------------

 include Yelp::V2::Business::Request
 # retrieve details of business vi yelp business id
 request =
             :yelp_business_id => "pjb2WMwa0AfK3L-dWimO8w")
 response =

 # -------------------------------------------------------

 include Yelp::V2::Search::Request
 # search for businesses via bounding box geo coords'
 request =
             :term => "cream puffs",
             :sw_latitude => 37.900000,
             :sw_longitude => -122.500000,
             :ne_latitude => 37.788022,
             :ne_longitude => -122.399797,
             :limit => 3)
 response =

 # search for businesses via lat/long geo point'
 request =
             :term => "cream puffs",
             :latitude => 37.788022,
             :longitude => -122.399797)
 response =

 # search for businesses via location (address, neighbourhood, city, state, zip, country, latitude, longitude)'
 request =
             :term => "cream puffs",
             :city => "San Francisco")
 response =

 request =
             :term => "german food",
             :address => "Hayes",
             :latitude => 37.77493,
             :longitude => -122.419415)
 response =

Here is another example, let's say I wanted to make a call to the API in a controller action:

 class FoodsController < ApplicationController
   include Yelp::V2::Search::Request

   def search
     client =

     request =
                 :term => 'thai',
                 :category_filter => 'food,restaurants',
                 :limit => 20,
                 :radius_filter => 8047,
                 :latitude => params[:latitude],
                 :longitude => params[:longitude])
     response =

     # rest of your code

You can check out all the parameters you can pass in the Yelp API Documentation.

For V1 - For V2 -

If you want to convert some addresses to latitude/longitude, or vice versa, for testing or what have you -- try


This library is provided via the GNU LGPL license at


Copyright 2007 - 2009, Walter Korman,

2011 – Yelp V2 Additions by Naveed Siddiqui

You can’t perform that action at this time.