Introduction

This egg provides an interface to the YelpAPI. 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.

Authors

License (BSD)

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. </blockquote>

Requirements

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?

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 was not so much designed as hacked on, it seems.

API Error Handling

The Yelp API consists of the following functions:

by-phone

hood-for-address

hood-for-geocode

near-address

near-geocode

near-geobox

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:

'yelp-success

'invalid-yelp-response

'yelp-unavailable

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

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 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. The CATEGORY keyword may be used to limit the search to a particular Yelp [[http://www.yelp.com/developers/documentation/category_list|category] name, e.g., "pizza".

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-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 [[http://www.yelp.com/developers/documentation/category_list|category] name, e.g., "lounges".

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)

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.

Implementation Notes

The Yelp routines alway return an outermost JSON structure which the JSON egg maps to a vector. find may return a list or a vector (or a simple value), depending on what's being queried. Either may be passed to decode or find. For example:

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

Limitations

The Yelp servers seem to sometime return spurious HTML 301 redirects for no apparent reason. There's also quite a lot of information returned by default for the "near- queries. So it makes sense to limit your queries using #:number or #:category when you can.