yelp (historical revision 16737) - The CHICKEN Scheme wiki

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

This egg provides an interface to the public Yelp API. Yelp is a social database of customer 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 queries are rate-limited and use is subject to Yelp's API Terms of Use.

This egg includes Dominique Boucher's JSON parser from Gambit's snow repository. It maps JSON dictionaries to hash-tables, which is the outer layer of the RESPONSE objects.

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 procedure in this egg.

[procedure] (valid? OBJECT) => BOOLEAN

Is the OBJECT a valid Yelp response?

All Yelp responses include this dictionary:

message:
  text: OK
  version: 1.1.1
  code: 0

valid? checks for both "OK" and 0. The Yelp API was not so much designed as hacked on, it seems.

Yelp Phone API

[procedure] (by-phone NUMBER) => RESPONSE

Lookup a business by its phone number, NUMBER.

Yelp Neighborhood API

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

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

[procedure] (hood-for-geocode LAT LONG) => RESPONSE

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

Yelp Review Search API

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

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".

[procedure] (near-geocode TERM LAT LONG #:NUMBER #:RADIUS #:CATEGORY) => RESPONSE

Returns a list of NUMBER reviews for businesses containing TERM and located in a circle around the geocode location LAT and LONG for a radius of RADIUS. The Yelp API fails to specify the units. 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-LONG BR-LAT BR-LONG #:NUMBER #:CATEGORY) => RESPONSE

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

Display and Query

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

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

Pho Tan Hoa
431 Jones St
San Francisco, CA 94102
(415)673-3163
Neighborhood: Civic Center/Tenderloin
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 path to the information you're interested in.

[procedure] (find RESPONSE PATH) => STRING

Walks the JSON tree and searches for the JSON key specified by PATH. find uses simple dotted notation to describe the path, for example: businesses.categories.name or message.code.

Examples

#;1> (use yelp)
; loading /usr/local/chicken/lib/chicken/4/yelp.import.so ...
; loading /usr/local/chicken/lib/chicken/4/srfi-18.import.so ...
; loading /usr/local/chicken/lib/chicken/4/srfi-69.import.so ...
; loading /usr/local/chicken/lib/chicken/4/tcp.import.so ...
; loading /usr/local/chicken/lib/chicken/4/yelp.so ...
#;2> (by-phone "4154376800")
invalid-ywsid
"Invalid YWSID"
#;3> ,l ../ywsid
; loading ../ywsid.scm ...
#;4> (define y (by-phone "4154376800"))
#;5> (valid? y)
#t

#;6> (display-info y)
Pizzeria Delfina
3611 18th Street
San Francisco, CA 94110
(415)437-6800
Neighborhood: Mission
37.761398 -122.424003

#;7> (decode y)
businesses: (1)
  rating_img_url: http://static1.px.yelp.com/static/200911304084228337/i/ico/stars/stars_4.png
  country: USA
  phone: 4154376800
  rating_img_url_small: http://static3.px.yelp.com/static/20091130418129184/i/ico/stars/stars_small_4.png
  state: CA
  longitude: -122.424003601074
  mobile_url: http://mobile.yelp.com/biz/bai6umLcCNy9cXql0Js2RQ
  is_closed: #f
  latitude: 37.7613983154297
  name: Pizzeria Delfina
  ...
message:
  text: OK
  version: 1.1.1
  code: 0

#;8> (find y "businesses.phone")
"4154376800"
#;9> (find y "message.code")
0
#;10> (find y "businesses.neighborhoods.name")
"Mission"

Authors

Derrell Piper

License

BSD

Requirements

None.

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 you do not specify -test to chicken-install.

Version History

1.0 Initial release

yelp

Introduction

API