Yelp Phone API
Overview
The Yelp Phone API enables the retrieval of business review information based on a phone number input parameter. If the phone number provided matches a business in the Yelp system, business and review information will be returned.
Input Parameters:
| Name | Data Type | Required / Optional | Description |
|---|---|---|---|
| phone | integer | required | Parameter that specifies the business phone number to search for. Outside of the US and Canada, include the international dialing code (e.g. +442079460000) or use the 'cc' parameter |
| cc | string | optional | ISO 3166-1 alpha-2 country code. Default country to use when parsing the phone number. United States = US, Canada = CA, United Kingdom = GB (not UK). |
Sample Request:
http://api.yelp.com/phone_search?phone=1234567890&ywsid=XXXXXXXXXXXXXXXX
Sample Response
Response Values:
This section outlines the standard response values from a "BusinessReviewSearch" 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.name | node | name of one category to which this business is associated with | 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 |
| 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 | 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 "BusinessReviewSearch" 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 |
| 300 | Invalid phone number | Indicates that the value of the "phone" parameter was not a valid 10-digit telephone number |
Sample Response:
This section provides a sample response for a "phone_search" 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',
'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'}}