NB: this egg implements the (now) deprecated Yelp v1.0 API.
#;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"
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:
...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.
- (set-ywsid! YWSID) procedure
Sets the Yelp web service ID to the value of YWSID. This must be done before calling any other function in this egg.
- (valid? OBJECT) procedure
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.
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?.
See Yelp Phone API.
- (by-phone NUMBER) procedure
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.
- (hood-for-address LOCATION #:CC) procedure
Returns the neighborhood name associated with a street address, LOCATION.
- (hood-for-geocode LAT LON) procedure
Returns the neighborhood name associated with a geocode location, LAT and LON.
- (near-address TERM LOCATION #:NUMBER #:CC #:CATEGORY) procedure
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
- (near-geocode TERM LAT LON #:NUMBER #:RADIUS #:CATEGORY) procedure
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".
- (near-geobox TERM TL-LAT TL-LON BR-LAT BR-LON #:NUMBER #:CATEGORY) procedure
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-info RESPONSE [PORT]) procedure
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
- (decode RESPONSE [PORT]) procedure
Walks the JSON tree and decodes the response to PORT. Primarily useful during development to determine the pathname of interest.
- (find RESPONSE PATH) procedure
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.
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").
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.
- 1.0.3 Switched to http-client
- 1.0.2 Add note to regression test about Yelp API key (you need one!)
- 1.0.1 Fix short header exception. Clarify license is BSD.
- 1.0 Initial release
Copyright (C) 2009 Derrell Piper. BSD-licensed.