You can edit this page using wiki syntax for markup.

Article contents:== Outdated egg! This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for [[/eggref/5/yelp|the CHICKEN 5 version of this egg]], if it exists. If it does not exist, there may be equivalent functionality provided by another egg; have a look at the [[https://wiki.call-cc.org/chicken-projects/egg-index-5.html|egg index]]. Otherwise, please consider porting this egg to the current version of CHICKEN. [[tags: egg]] == yelp [[toc:]] == Introduction This egg provides an interface to the [[http://www.yelp.com/about|Yelp]] [[http://www.yelp.com/developers/getting_started|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 [[http://www.yelp.com/developers/getting_started|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 [[http://www.yelp.com/developers/getting_started/api_terms|API Terms of Use]]. NB: this egg implements the (now) deprecated Yelp v1.0 API. [[image:http://static1.px.yelp.com/static/200911301285253944/i/developers/Powered_By_Yelp_Red.png|Yelp logo]] == 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 == Requirements Requires the [[json]] and [[http-client]] eggs. In addition, the {{chicken-install}} tests require the [[test]] egg. {{-test}} also requires a valid [[http://www.yelp.com/developers/getting_started|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)</procedure> 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)</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}}. === 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}} * {{'yelp-invalid-response}} * {{'yelp-unavailable}} * {{'yelp-undocumented-response}} Other values represent the translation of {{"message.code"}} in the Yelp response. {{'yelp-success}} implies {{valid?}}. === Yelp Phone API See [[http://www.yelp.com/developers/documentation/phone_api|Yelp Phone API]]. <procedure>(by-phone NUMBER)</procedure> Look up a business by its phone number, {{NUMBER}}. The following phone syntax is understood: * aaaxxxnnnn * (aaa)xxx-nnnn * aaa.xxx.nnnn This egg currently understands only the North American Numbering Plan syntax (US and Canada). Sorry mates. === Yelp Neighborhood API See [[http://www.yelp.com/developers/documentation/neighborhood_api|Yelp Neighborhood API]]. <procedure>(hood-for-address LOCATION #:CC)</procedure> Returns the neighborhood name associated with a street address, {{LOCATION}}. <procedure>(hood-for-geocode LAT LON)</procedure> Returns the neighborhood name associated with a geocode location, {{LAT}} and {{LON}}. === Yelp Review Search API See [[http://www.yelp.com/developers/documentation/search_api|Yelp Review Search API]] <procedure>(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 [[http://www.yelp.com/developers/documentation/category_list|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)</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 [[http://www.yelp.com/developers/documentation/category_list|category]] name, e.g., {{"pizza"}}. <procedure>(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 [[http://www.yelp.com/developers/documentation/category_list|category]] name, e.g., {{"divebars+lounges"}}. === Display and Query <procedure>(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 <procedure>(decode RESPONSE [PORT])</procedure> Walks the JSON tree and decodes the response to {{PORT}}. Primarily useful during development to determine the pathname of interest. <procedure>(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}}. === 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: * {{businesses}} * {{businesses.categories}} * {{businesses.neighborhoods}} * {{businesses.reviews}} 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 * 1.0.4 Fixed tests to not fail when '../../yswid.scm' does not exist * 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 == License Copyright (C) 2009 Derrell Piper. BSD-licensed. Description of your changes:

I would like to authenticate

Spam control

What do you get when you add 14 to 8?