Yelp Neighborhood API
Attribution
If you use the Yelp Neighborhood API, add a link to your application that says "Neighborhood Data from Yelp". This link (which should be follow-able) should point to the Yelp home page at http://www.yelp.com
Neighborhood API Overview:
The "Yelp Neighborhood API" allows the retrieval of neighborhood name information based on various input parameters. The use of this API enable users to determine what neigborhood a particular location belongs to.
Neighborhood Search By Geocode
Enables the determination of neighborhood name information for a single geo-point location.
Input Parameters:
| Name | Data Type | Required / Optional | Description |
|---|---|---|---|
| lat | double | required | Latitude of geo-point for which a neighborhood name is desired. |
| long | double | required | Longitude of geo-point for which a neighborhood name is desired. |
Sample Request:
http://api.yelp.com/neighborhood_search?lat=37.788022&long=-122.399797&ywsid=XXXXXXXXXXXXXXXXXX
Sample Response
Neighborhood Search By Location
Enables the determination of neighborhood name information for a particular address.
Input Parameters:
| Name | Data Type | Required / Optional | Description |
|---|---|---|---|
| location | string | required | Specifies the combination of "address, neighborhood, city, state or zip, optional country" to be used when searching for neighborhood(s). |
| 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). |
| location | string | required | Specifies the combination of "address, city, state or zip" to be used when searching for neighborhood(s) |
Sample Request:
http://api.yelp.com/neighborhood_search?location=1512%20Shattuck%20Avenue%2A%20Berkeley%2A%20CA&ywsid=XXXXXXXXXXXXXXXXXX
Sample Response
Response Values:
| Node Element | Type | Definition | Max Number In Result Set |
|---|---|---|---|
| neighborhoods | list | Node that contains a list of neighborhood(s) name(s) to which the specified location belongs. | 1 |
| name | node | Name of neighborhood in list. | 1 per neighborhood |
| borough | node | Name of borough where neighborhood is located (only used in New York City). | 1 per neighborhood |
| city | node | Name of city where neighborhood is located. | 1 per neighborhood |
| state | node | Displayable name or abbreviation for state where the neighborhood is located. In the UK, this is the name of an administrative subdivision (e.g. Greater London, Conwy, Scottish Borders). | 1 per neighborhood |
| state_code | node | ISO 3166-2 code. In the US and Canada, the two-letter state code for the state where the neighborhood 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 neighborhood |
| country | node | Country where the neighborhood is located. | 1 per neighborhood |
| country_code | node | ISO 3166-1 alpha-2 code. United States = US, Canada = CA, United Kingdom = GB. | 1 per neighborhood |
| url | node | URL that will execute a search on Yelp for this neighborhood. | 1 per neighborhood |
| message | list | Node that contains information regarding the execution of the API request. | 1 |
| message.text | node | Provides a string with details regarding the execution of the API request. This node will provide error message details if appropriate. | 1 |
| message.code | node | Provides a response code relating to the execution of the API request. Will contain error codes when appropriate. | 1 |
Response Codes:
| 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 |
| 100 | Bad lat/long parameters | Indicates that the latitude and longitude parameters to a neighborhood lookup query were invalid |
| 101 | Missing lat/long parameters | A request to do a neighborhood lookup by latitude and longitude was executed and was missing one or both latitude and longitude parameters |
| 102 | Bad location parameter | Yelp was unable to determine the location based on the value specified by "location" parameter |
| 103 | Missing location parameter | A request was made to do a neighborhood lookup by location but no "location" parameter was provided. |
Sample Response:
The following is a sample response from a call to the Yelp Neighborhood API
{'message': {'code': 0, 'text': 'OK', 'version': '1.1.0'},
'neighborhoods':
[{'city': 'Berkeley',
'name': 'Gourmet Ghetto',
'borough': '',
'state': 'CA',
'state_code': 'CA',
'country': 'USA',
'country_code': 'US',
'url': 'http://yelp.com/search?/find_loc=Gourmet+Ghetto%2C+Berkeley%2C+CA' },
{'city': 'Berkeley',
'name': 'North Berkeley',
'borough': '',
'state': 'CA',
'state_code': 'CA',
'country': 'USA',
'country_code': 'US',
'url': ' http://yelp.com/search?/find_loc=North+Berkeley%2C+Berkeley%2C+CA'}]
}