Yelp Review Search API
Overview:
The Yelp Review Search API allows the retrieval of Yelp business and review information. This section outlines the various types of searches and provides example requests and responses.
This API can be used to show review information regarding local businesses on your website, widget or mobile application.
- Searching by Map Bounding Box
- Searching by Geo-Point and Radius
- Searching by Neighborhood, Address and City
- Narrowing Result Set By Category
- Response Values
- Response Codes
Searching by Map Bounding Box:
This mechanism for searching allows the retrieval of business review information based on the bounding box of a particular map. A request can be sent to the Yelp API using the "top-left latitude and longitude" and "bottom-right latitude and longitude" for a geographical bounding box.
Input Parameters:
| Name | Data Type | Required / Optional | Description |
|---|---|---|---|
| term | string | optional | String representing the name of business or search term being requested. (E.G. "bars") |
| limit | integer | optional | Specifies the number of businesses to return in the result set. Default is 10. Minimum value is 1 and maximum value is 20 |
| tl_lat | double | required | Top left latitude of bounding box |
| tl_long | double | required | Top left longitude of bounding box |
| br_lat | double | required | Bottom right latitude of bounding box |
| br_long | double | required | Bottom right longitude of bounding box |
Sample Request:
http://api.yelp.com/business_review_search?term=yelp&tl_lat=37.9&tl_long=-122.5&br_lat=37.788022&br_long=-122.399797&limit=3&ywsid=XXXXXXXXXXXXXXXXXX
Sample Response
Search by Geo-Point and Radius:
Enables searching for business review information within a certain radius of a particular location.
Input Parameters:
| Name | Data Type | Required / Optional | Description |
|---|---|---|---|
| term | string | optional | String representing the name of business or search term being requested. (E.G. "bars") |
| limit | integer | optional | Specifies the number of businesses to return in the result set. Default is 10. Minimum value is 1 and maximum value is 20 |
| lat | double | required | Latitude of geo-point to search near. |
| long | double | required | Longitude of geo-point to search near. |
| radius | double | optional | Radius to use while searching around specified geo-point. Maximum value = 25. If a radius is not specified, it will be chosen based on the specificity of the location. |
Sample Request:
http://api.yelp.com/business_review_search?term=yelp&lat=37.788022&long=-122.399797&radius=10&limit=5&ywsid=XXXXXXXXXXXXXXXXXX
Sample Response
Search by Neighborhood, Address and City:
Enables searching for business review information based on a particular neighborhood, address or city.
Input Parameters:
| Name | Data Type | Required / Optional | Description |
|---|---|---|---|
| term | string | optional | String representing the name of business or search term being requested (E.G. "bars") |
| limit | integer | optional | Specifies the number of businesses to return in the result set. Default is 10. Minimum value is 1 and maximum value is 20 |
| location | string | required | Specifies the combination of "address, neighborhood, city, state or zip, optional country" to be used when searching for businesses. |
| cc | string | optional | ISO 3166-1 alpha-2 country code. Default country to use when parsing the location field. United States = US, Canada = CA, United Kingdom = GB (not UK). |
| radius | double | optional | Radius to use while searching around specified geo-point. Maximum value = 25. If a radius is not specified, it will be chosen based on the specificity of the location. |
Sample Request:
http://api.yelp.com/business_review_search?term=cream%20puffs&location=650%20Mission%20St%2ASan%20Francisco%2A%20CA&ywsid=XXXXXXXXXXXXXXXX
Sample Response
Narrowing Result Set By Category:
All result sets returned via the Yelp Review Search API can be narrowed to only include businesses that fall under a particular category.
The following input parameter can be used to accomplish category filtering.
Input Parameters:
| Name | Data Type | Required / Optional | Description |
|---|---|---|---|
| category | string | optional | This parameter allows filtering of result set by a particular category. You can search in multiple categories by separating them with a plus character, e.g category=bars+poolhalls |
A full list of supported categories is available here.
Sample Request:
http://api.yelp.com/business_review_search?term=dada&location=650%20Mission%20St%2ASan%20Francisco%2A%20CA&ywsid=XXXXXXXXXXX&category=bars
Sample Response
Response Values:
This section outlines the standard response values from a "business_review_search" operation.
| Node Element | Type | Definition | Max Number In Result Set |
|---|---|---|---|
| businesses | list | node that contains a list of business entries | 1 |
| address1 | node | line one of business address | 1 per business |
| address2 | node | line two of business address | 1 per business |
| address3 | node | line three of business address | 1 per business |
| categories | list | provides a list of categories that this business is associated with | 1 per business |
| categories.category_filter | node | filter name for this particular category | unbounded |
| categories.name | node | display name for a particular category | unbounded |
| categories.search_url | node | URL to execute a search for this particular category on Yelp.com | unbounded |
| city | node | name of city that business is located in | 1 per business |
| distance | node | distance that business is from center point of city | 1 per business |
| id | node | Yelp Id for this business | 1 per business |
| is_closed | node | boolean, true if the business is closed | 1 per business |
| latitude | node | latitude of business | 1 per business |
| longitude | node | longitude of business | 1 per business |
| mobile_url | node | URL for mobile business page on Yelp | 1 per business |
| name | node | name of business | 1 per business |
| nearby_url | node | URL to execute search for nearby businesses | 1 per business |
| neighborhoods | list | List that provides neighborhood(s) information for business | 1 per business |
| neighborhoods.name | node | Name of neighborhood to which this business belongs | unbounded |
| neighborhoods.url | node | URL to execute a search for that neighborhood on yelp | unbounded |
| phone | node | phone number for this business. Outside of the US and Canada, we include the international dialing code (e.g. +442079460000) | 1 per business |
| photo_url | node | URL of photo for this business | 1 per business |
| avg_rating | node | Numeric value representing the average review for this business | 1 per business |
| rating_img_url | node | URL to star rating image for this business (size = 84x17) | 1 per business |
| rating_img_url_small | node | URL to small version of rating image for this business (size = 50x10) | 1 per business |
| review_count | node | Number of reviews associated with this business | 1 per business |
| reviews | list | Contains a list of 3 reviews associated with business | 1 per business |
| reviews.id | node | Yelp Id for this review | 1 per review |
| reviews.text_excerpt | node | Excerpt of review text | 1 per review |
| reviews.url | node | URL to business profile page with this review selected | 1 per review |
| reviews.user_name | node | Name of user that created review | 1 per review |
| reviews.user_photo_url | node | URL to photo of the user that created review | 1 per review |
| reviews.user_photo_url_small | node | URL to small photo of the user that created review | 1 per review |
| reviews.rating | node | Numeric value representing the rating of this review | 1 per review |
| reviews.rating_img_url | node | URL to star rating image for this review | 1 per review |
| reviews.mobile_uri | node | URL for mobile business page with this review selected | 1 per review |
| reviews.user_url | node | URL of user's profile page (photo must link to this URL) | 1 per review |
| reviews.date | node | Date review was written, in ISO 8601 format (YYYY-MM-DD). | 1 per review |
| state | node | Displayable name or abbreviation for state where the business is located. In the UK, this is the name of an administrative subdivision (e.g. Greater London, Conwy, Scottish Borders). | 1 per business |
| state_code | node | ISO 3166-2 code. In the US and Canada, the two-letter state code for the state where the business is located. For the meaning of state_code in the UK, see this reference; a dummy code of XGL is used for all of Greater London. | 1 per business |
| country | node | Country where the business is located. | 1 per business |
| country_code | node | ISO 3166-1 alpha-2 code. United States = US, Canada = CA, United Kingdom = GB. | 1 per business |
| url | node | URL to business profile page on Yelp | 1 per business |
| zip | node | Postal code for this business | 1 per business |
| message | list | Contains meta data about request | 1 |
| message.text | node | Message describing response code | 1 |
| message.code | node | Numeric code indicating whether response was generated correctly or not | 1 |
Response Codes:
This section outlines the response codes that can be expected from a "business_review_search" operation.
| Response Code | Response Message | Description |
|---|---|---|
| 0 | OK | Indicates the request completed without error. |
| 1 | Server error | Indicates that a system error occurred and that the request was unable to be processed. |
| 2 | Invalid YWSID | Returned when an invalid YWSID is supplied with the API request. |
| 3 | Missing YWSID | Indicates that the required YWSID parameter was not supplied with the request. |
| 4 | Exceed daily API request limit | Returned when the number of requests executed for a particular YWSID on a particular day exceeds the specified limit. |
| 5 | API not available | Indicates that the Yelp API is currently not available |
| 6 | Did not understand query | Indicates an invalid API request was sent |
| 200 | Unspecified location | Enough information was not provided in the request to allow Yelp to determine a specific search location. |
| 201 | Bad term parameter | The term parameter provided in the request could not be understood |
| 202 | Bad location parameter | The location parameter provided in the request could not be understood |
| 203 | Area too large | Indicates that the geographical area is too large for this search request. Max search area is 2,500 sq miles. |
| 205 | Unknown category | Indicates that an unknown category was specified. |
Sample Response:
This section provides a sample response for a "BusinessReviewSearch" operation.
{'businesses': [{'address1': '466 Haight St',
'address2': '',
'address3': '',
'avg_rating': 4.0,
'categories': [{'category_filter': 'danceclubs',
'name': 'Dance Clubs',
'search_url': 'http://yelp.com/search?find_loc=466+Haight+St%2C+San+Francisco%2C+CA&cflt=danceclubs'},
{'category_filter': 'lounges',
'name': 'Lounges',
'search_url': 'http://yelp.com/search?find_loc=466+Haight+St%2C+San+Francisco%2C+CA&cflt=lounges'},
{'category_filter': 'tradamerican',
'name': 'American (Traditional)',
'search_url': 'http://yelp.com/search?find_loc=466+Haight+St%2C+San+Francisco%2C+CA&cflt=tradamerican'}],
'city': 'San Francisco',
'distance': 1.8780401945114136,
'id': 'yyqwqfgn1ZmbQYNbl7s5sQ',
'is_closed': False,
'latitude': 37.772201000000003,
'longitude': -122.42992599999999,
'mobile_url': 'http://mobile.yelp.com/biz/yyqwqfgn1ZmbQYNbl7s5sQ',
'name': 'Nickies',
'nearby_url': 'http://yelp.com/search?find_loc=466+Haight+St%2C+San+Francisco%2C+CA',
'neighborhoods': [{'name': 'Hayes Valley',
'url': 'http://yelp.com/search?find_loc=Hayes+Valley%2C+San+Francisco%2C+CA'}],
'phone': '4152550300',
'photo_url': 'http://static.ak.yelp.com/bpthumb/mPNTiQm5HVqLLcUi8XrDiA/ms',
'photo_url_small': 'http://static.ak.yelp.com/bpthumb/mPNTiQm5HVqLLcUi8XrDiA/ss',
'rating_img_url': 'http://static.ak.yelp.com/static/20070816/img/ico/stars/stars_4.png',
'rating_img_url_small': 'http://static.ak.yelp.com/static/20070816/img/ico/stars/stars_small_4.png',
'review_count': 32,
'reviews': [{'id': 't-sisM24K9GvvYhr-9w1EQ',
'rating': 3,
'rating_img_url': 'http://static.ak.yelp.com/static/20070816/img/ico/stars/stars_3.png',
'rating_img_url_small': 'http://static.ak.yelp.com/static/20070816/img/ico/stars/stars_small_3.png',
'text_excerpt': 'So I know gentrification is supposed to be a bad word and all (especially here in SF), but the Lower Haight might benefit a bit from it. At least, I like...',
'url': 'http://yelp.com/biz/yyqwqfgn1ZmbQYNbl7s5sQ#hrid:t-sisM24K9GvvYhr-9w1EQ',
'user_name': 'Trey F.',
'user_photo_url': 'http://static.ak.yelp.com/upthumb/ZQDXkIwQmgfAcazw8OgK2g/ms',
'user_photo_url_small': 'http://static.ak.yelp.com/upthumb/ZQDXkIwQmgfAcazw8OgK2g/ss',
'mobile_uri': 'http://mobile.yelp.com/biz/yyqwqfgn1ZmbQYNbl7s5sQ?srid=t-sisM24K9GvvYhr-9w1EQ',
'user_url': 'http://yelp.com/user_details?userid=XMeRHjiLhA9cv3BsSOazCA'},
{'id': '8xTNOC9L5ZXwGCMNYY-pdQ',
'rating': 4,
'rating_img_url': 'http://static.ak.yelp.com/static/20070816/img/ico/stars/stars_4.png',
'rating_img_url_small': 'http://static.ak.yelp.com/static/20070816/img/ico/stars/stars_small_4.png',
'text_excerpt': 'This place was definitely a great place to chill. The atmosphere is very non-threatening and very neighborly. I thought it was cool that they had a girl dj...',
'url': 'http://yelp.com/biz/yyqwqfgn1ZmbQYNbl7s5sQ#hrid:8xTNOC9L5ZXwGCMNYY-pdQ',
'user_name': 'Jessy M.',
'user_photo_url': 'http://static.ak.yelp.com/upthumb/Ghwoq23_alkaXawgqj7dBA/ms',
'user_photo_url_small': 'http://static.ak.yelp.com/upthumb/Ghwoq23_alkaXawgqj7dBA/ss',
'mobile_uri': 'http://mobile.yelp.com/biz/yyqwqfgn1ZmbQYNbl7s5sQ?srid=8xTNOC9L5ZXwGCMNYY-pdQ',
'user_url': 'http://yelp.com/user_details?userid=4F2QG3adYIUNXplqqp9ylA'},
{'id': 'pp33WfN_FoKlQKJ-38j_Ag',
'rating': 5,
'rating_img_url': 'http://static.ak.yelp.com/static/20070816/img/ico/stars/stars_5.png',
'rating_img_url_small': 'http://static.ak.yelp.com/static/20070816/img/ico/stars/stars_small_5.png',
'text_excerpt': "Love this place! I've been here twice now and each time has been a great experience. The bartender is so nice. When we had questions about the drinks he...",
'url': 'http://yelp.com/biz/yyqwqfgn1ZmbQYNbl7s5sQ#hrid:pp33WfN_FoKlQKJ-38j_Ag',
'user_name': 'Scott M.',
'user_photo_url': 'http://static.ak.yelp.com/upthumb/q0POOE3vv2LzNg1qN8MMyw/ms',
'user_photo_url_small': 'http://static.ak.yelp.com/upthumb/q0POOE3vv2LzNg1qN8MMyw/ss',
'mobile_uri': 'http://mobile.yelp.com/biz/yyqwqfgn1ZmbQYNbl7s5sQ?srid=pp33WfN_FoKlQKJ-38j_Ag',
'user_url': 'http://yelp.com/user_details?userid=FmcKafW272uSWXbUF2rslA'}],
'state': 'CA',
'state_code': 'CA',
'country': 'USA',
'country_code': 'US',
'url': 'http://yelp.com/biz/nickies-san-francisco',
'zip': '94117'}],
'message': {'code': 0, 'text': 'OK', 'version': '1.1.0'}}