source: project/wiki/eggref/4/yelp @ 27385

Last change on this file since 27385 was 27385, checked in by anonymous, 9 years ago

Add note about API version being deprecated.

  • Property svnwiki:tags set to egg web
  • Property svnwiki:title set to yelp
File size: 8.7 KB
Line 
1[[tags: egg]]
2== yelp
3
4[[toc:]]
5
6== Introduction
7
8This 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]].
9
10NB: this egg implements the (now) depracated Yelp v1.0 API.
11
12[[image:http://static1.px.yelp.com/static/200911301285253944/i/developers/Powered_By_Yelp_Red.png|Yelp logo]]
13
14== Examples
15
16 #;1> (use yelp)
17 #;2> (set-ywsid! "qvGjCuKXg8adMmACm7haqw")     ;; example YWSID
18 #;3> (define y (by-phone "4154376800"))
19 #;4> (display-info y)
20 Categories: Pizza
21 Neighborhood: Mission
22 Pizzeria Delfina
23 3611 18th Street
24 San Francisco, CA 94110
25 (415)437-6800
26 37.761398 -122.424003
27 #;5> (decode y)
28 message:
29   text: OK
30   code: 0
31   version: 1.1.1
32 businesses: (1)
33   country_code: US
34   id: bai6umLcCNy9cXql0Js2RQ
35   is_closed: #f
36   city: San Francisco
37   mobile_url: http://mobile.yelp.com/biz/bai6umLcCNy9cXql0Js2RQ
38   review_count: 836
39   zip: 94110
40   state: CA
41   ...
42 #;6> (find y "businesses.phone")
43 "4154376800"
44 #;7> (find y "businesses.categories.name")
45 "Pizza"
46 #;8> (find y "businesses.neighborhoods.name")
47 "Mission"
48
49== Authors
50
51Derrell Piper
52
53== Requirements
54
55Requires the [[json]] egg.
56
57In 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:
58
59 (set-ywsid! "<your-personal-ywsid-goes-here>")
60
61...and then doing a {{chicken-install -test}} in the {{yelp}} subdirectory, should work.
62
63None of this matters if you don't care about regression tests or if you do not specify {{-test}} to {{chicken-install}}.
64
65== API
66
67=== Authorization and Introspection
68
69<procedure>(set-ywsid! YWSID)</procedure>
70
71Sets the Yelp web service ID to the value of {{YWSID}}.  '''This must be done before calling any other function in this egg.'''
72
73<procedure>(valid? OBJECT)</procedure>
74
75Is the {{OBJECT}} a valid Yelp response?  There's no need to check {{valid?}} if you check for {{'yelp-success}}.
76
77All Yelp responses include this structure:
78
79 message:
80   text: OK
81   code: 0
82   version: 1.1.1
83
84{{valid?}} checks for both {{"OK"}} and {{0}}.
85
86=== Error Handling
87
88The Yelp API consists of the following functions:
89
90* {{by-phone}}
91* {{hood-for-address}}
92* {{hood-for-geocode}}
93* {{near-address}}
94* {{near-geocode}}
95* {{near-geobox}}
96
97Each 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:
98
99* {{'yelp-success}}
100* {{'yelp-invalid-response}}
101* {{'yelp-unavailable}}
102* {{'yelp-undocumented-response}}
103
104Other values represent the translation of {{"message.code"}} in the Yelp response.  {{'yelp-success}} implies {{valid?}}.
105
106=== Yelp Phone API
107
108See [[http://www.yelp.com/developers/documentation/phone_api|Yelp Phone API]].
109
110<procedure>(by-phone NUMBER)</procedure>
111
112Look up a business by its phone number, {{NUMBER}}.
113
114The following phone syntax is understood:
115
116* aaaxxxnnnn
117* (aaa)xxx-nnnn
118* aaa.xxx.nnnn
119
120This egg currently understands only the North American Numbering Plan syntax (US and Canada).  Sorry mates.
121
122=== Yelp Neighborhood API
123
124See [[http://www.yelp.com/developers/documentation/neighborhood_api|Yelp Neighborhood API]].
125
126<procedure>(hood-for-address LOCATION #:CC)</procedure>
127
128Returns the neighborhood name associated with a street address, {{LOCATION}}.
129
130<procedure>(hood-for-geocode LAT LON)</procedure>
131
132Returns the neighborhood name associated with a geocode location, {{LAT}} and {{LON}}.
133
134=== Yelp Review Search API
135
136See [[http://www.yelp.com/developers/documentation/search_api|Yelp Review Search API]]
137
138<procedure>(near-address TERM LOCATION #:NUMBER #:CC #:CATEGORY)</procedure>
139
140Returns 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"}}.
141
142Yelp'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:
143
144 #;1> (display-info (near-address "tokyo a go-go" "mission sf"))
145 Categories: Sushi Bars, Japanese
146 Neighborhood: Mission
147 Tokyo Go Go
148 3174 16th Street
149 Suite 250I
150 San Francisco, CA 94103
151 (415)864-2288
152 37.764900 -122.424003
153 #;2> (display-info (near-address "john's pizzeria" "nyc"))
154 Categories: Pizza
155 Neighborhood: West Village
156 John's Pizzeria
157 278 Bleecker St
158 New York, NY 10014
159 (212)243-1680
160 40.731712 -74.003274
161
162<procedure>(near-geocode TERM LAT LON #:NUMBER #:RADIUS #:CATEGORY)</procedure>
163
164Returns 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"}}.
165
166<procedure>(near-geobox TERM TL-LAT TL-LON BR-LAT BR-LON #:NUMBER #:CATEGORY)</procedure>
167
168Returns 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"}}.
169
170=== Display and Query
171
172<procedure>(display-info RESPONSE [PORT])</procedure>
173
174Display basic information for a Yelp {{RESPONSE}} on {{PORT}}.  For example:
175
176 #;1> (display-info (by-phone "415.673.3163"))
177 Categories: Vietnamese
178 Neighborhood: Civic Center/Tenderloin
179 Pho Tan Hoa
180 431 Jones St
181 San Francisco, CA 94102
182 (415)673-3163
183 37.785377 -122.412916
184
185<procedure>(decode RESPONSE [PORT])</procedure>
186
187Walks the JSON tree and decodes the response to {{PORT}}.  Primarily useful during development to determine the pathname of interest.
188
189<procedure>(find RESPONSE PATH)</procedure>
190
191Walks 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}}.
192
193=== Implementation Notes
194
195The 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:
196
197 #;1> (define y (by-phone "(415)864-2288"))
198 #;2> (define c (find y "businesses.categories"))
199 #;3> (find c "name")
200 "Sushi Bars"
201 #;4> (find (list-ref c 0) "name")
202 "Sushi Bars"
203 #;5> (for-each (lambda (c) (let ((n (find c "name"))) (print n))) c)
204 Sushi Bars
205 Japanese
206 #;6> (define m (find y "message"))
207 #;7> (decode m)
208 text: OK
209 code: 0
210 version: 1.1.1
211 #;8> (find m "text")
212 "OK"
213
214The Yelp API defines the following elements as JSON arrays:
215
216* {{businesses}}
217* {{businesses.categories}}
218* {{businesses.neighborhoods}}
219* {{businesses.reviews}}
220
221Note 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"}}).
222
223=== Limitations
224
225The 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.
226
227== Version History
228
229* 1.0.2 Add note to regression test about Yelp API key (you need one!)
230* 1.0.1 Fix short header exception.  Clarify license is BSD.
231* 1.0   Initial release
232
233== License
234
235Copyright (C) 2009 Derrell Piper.  BSD-licensed.
Note: See TracBrowser for help on using the repository browser.