You are looking at historical revision 19031 of this page. It may differ significantly from its current revision.

yelp

Introduction

This egg provides an interface to the Yelp API. Yelp is a social database of reviews of restaurants and businesses. It also provides generalized lookup by phone number, geocode, or address across the United States, Canada, and Great Britain. All six Yelp APIs are supported along with a simple query mechanism for traversing the JSON query result. A valid Yelp YWSID is required to use this API. There is no charge for a YWSID, though each YWSID has a daily query limit (1000) and use is subject to Yelp's API Terms of Use.

Examples

 
#;1> (use yelp)
#;2> (set-ywsid! "qvGjCuKXg8adMmACm7haqw")     ;; example YWSID
#;3> (define y (by-phone "4154376800"))
#;4> (display-info y)
Categories: Pizza
Neighborhood: Mission
Pizzeria Delfina
3611 18th Street
San Francisco, CA 94110
(415)437-6800
37.761398 -122.424003
#;5> (decode y)
message:
  text: OK
  code: 0
  version: 1.1.1
businesses: (1)
  country_code: US
  id: bai6umLcCNy9cXql0Js2RQ
  is_closed: #f
  city: San Francisco
  mobile_url: http://mobile.yelp.com/biz/bai6umLcCNy9cXql0Js2RQ
  review_count: 836
  zip: 94110
  state: CA
  ...
#;6> (find y "businesses.phone")
"4154376800"
#;7> (find y "businesses.categories.name")
"Pizza"
#;8> (find y "businesses.neighborhoods.name")
"Mission"

Authors

Derrell Piper

License

 
Copyright (c) 2009 Derrell Piper.
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
conditions are met:

  Redistributions of source code must retain the above copyright notice, this list of conditions and the following
    disclaimer. 
  Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
    disclaimer in the documentation and/or other materials provided with the distribution. 
  Neither the name of the author nor the names of its contributors may be used to endorse or promote
  products derived from this software without specific prior written permission. 

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

Requirements

Requires the json egg.

In addition, the chicken-install tests require the test egg. -test also requires a valid YWSID exist in ../ywsid above the egg's temporary install directory. When fetched with chicken-install -r, simply creating a file named ywsid in the parent directory (i.e., the one in which you did the chicken-install -r) with the following content:

(set-ywsid! "<your-personal-ywsid-goes-here>")

...and then doing a chicken-install -test in the yelp subdirectory, should work.

None of this matters if you don't care about regression tests or if you do not specify -test to chicken-install.

API

Authorization and Introspection

[procedure] (set-ywsid! YWSID)

Sets the Yelp web service ID to the value of YWSID. This must be done before calling any other function in this egg.

[procedure] (valid? OBJECT)

Is the OBJECT a valid Yelp response? There's no need to check valid? if you check for 'yelp-success.

All Yelp responses include this structure:

message:
  text: OK
  code: 0
  version: 1.1.1

valid? checks for both "OK" and 0.

Error Handling

The Yelp API consists of the following functions:

Each of these functions returns two values. The first value is a RESPONSE object if successful or a string representing an error code (either from Yelp or internally generated). The second value is a symbolic return status. These values are defined in this egg:

Other values represent the translation of "message.code" in the Yelp response. 'yelp-success implies valid?.

Yelp Phone API

See Yelp Phone API.

[procedure] (by-phone NUMBER)

Look up a business by its phone number, NUMBER.

The following phone syntax is understood:

This egg currently understands only the North American Numbering Plan syntax (US and Canada). Sorry mates.

Yelp Neighborhood API

See Yelp Neighborhood API.

[procedure] (hood-for-address LOCATION #:CC)

Returns the neighborhood name associated with a street address, LOCATION.

[procedure] (hood-for-geocode LAT LON)

Returns the neighborhood name associated with a geocode location, LAT and LON.

Yelp Review Search API

See Yelp Review Search API

[procedure] (near-address TERM LOCATION #:NUMBER #:CC #:CATEGORY)

Returns a list of NUMBER reviews for businesses containing TERM and located near the address LOCATION. The CATEGORY keyword may be used to limit the search to a particular Yelp category name, e.g., "vietnamese".

Yelp's search algorithm is quite liberal in what it accepts for LOCATION; neighborhood names are valid terms as are common abbreviations for major cities. For example:

#;1> (display-info (near-address "tokyo a go-go" "mission sf"))
Categories: Sushi Bars, Japanese
Neighborhood: Mission
Tokyo Go Go
3174 16th Street
Suite 250I
San Francisco, CA 94103
(415)864-2288
37.764900 -122.424003
#;2> (display-info (near-address "john's pizzeria" "nyc"))
Categories: Pizza
Neighborhood: West Village
John's Pizzeria
278 Bleecker St
New York, NY 10014
(212)243-1680
40.731712 -74.003274
[procedure] (near-geocode TERM LAT LON #:NUMBER #:RADIUS #:CATEGORY)

Returns a list of NUMBER reviews for businesses containing TERM and located in a circle around the geocode location LAT and LON for a radius of RADIUS. The Yelp API fails to specify the units (assume US statute miles). The CATEGORY keyword may be used to limit the search to a particular Yelp category name, e.g., "pizza".

[procedure] (near-geobox TERM TL-LAT TL-LON BR-LAT BR-LON #:NUMBER #:CATEGORY)

Returns a list of NUMBER reviews for businesses containing TERM and located in a box with the top-left geocode of TL-LAT and TL-LON and a bottom-right geocode of BR-LAT and BR-LON. The CATEGORY keyword may be used to limit the search to a particular Yelp category name, e.g., "divebars+lounges".

Display and Query

[procedure] (display-info RESPONSE [PORT])

Display basic information for a Yelp RESPONSE on PORT. For example:

#;1> (display-info (by-phone "415.673.3163"))
Categories: Vietnamese
Neighborhood: Civic Center/Tenderloin
Pho Tan Hoa
431 Jones St
San Francisco, CA 94102
(415)673-3163
37.785377 -122.412916
[procedure] (decode RESPONSE [PORT])

Walks the JSON tree and decodes the response to PORT. Primarily useful during development to determine the pathname of interest.

[procedure] (find RESPONSE PATH)

Walks the JSON tree and searches for the JSON key specified by PATH. They syntax of find uses simple dotted notation to describe the pathname, for example: businesses.phone or message.code.

Implementation Notes

The Yelp routines alway return an outermost JSON structure which the JSON egg maps to a vector. find returns a list, vector, or a simple value (number, string, #t, #f, or null), depending on what's being queried. decode and find accept lists and vectors. For example:

#;1> (define y (by-phone "(415)864-2288"))
#;2> (define c (find y "businesses.categories"))
#;3> (find c "name")
"Sushi Bars"
#;4> (find (list-ref c 0) "name")
"Sushi Bars"
#;5> (for-each (lambda (c) (let ((n (find c "name"))) (print n))) c)
Sushi Bars
Japanese
#;6> (define m (find y "message"))
#;7> (decode m)
text: OK
code: 0
version: 1.1.1
#;8> (find m "text")
"OK"

The Yelp API defines the following elements as JSON arrays:

Note that find stops on first match, so regular iteration must be used to access second and subsequent elements, as in the first example above (i.e., categories by "name").

Limitations

The Yelp servers sometime return spurious HTML 301 redirects (on a good day) for no apparent reason. There's a sizeable amount of information returned by default for the "near-" queries, so it makes sense to limit queries using #:number or #:category when possible.

Version History