Yelp-Connector-Documentation
The Yelp connector allows you to connect to Yelp. Yelp is an online urban city guide that helps people to find cool places to eat, shop, drink, relax and play, based on the informed opinions of a vibrant and active community of locals in the know. Yelp is the fun and easy way to find, review and talk about what's great and not so great in your world.
The Yelp v2.0 API enables access to more relevant search results that more closely match the results on Yelp. It uses a standard and secure authorization protocol (OAuth 1.0a, xAuth).
Users of v2.0 will be able to:
- Find up to the 40 best results for a geographically-oriented search
- Sort results by the best match for the query, highest ratings, or distance
- Limit results to those businesses offering a Yelp Deal, displaying information about the deal such as title, savings and purchase URL
- Identify and display whether a business has been claimed on Yelp.com
The following sections describe how to perform various operations with the connector. General information on using connectors and their operations in your ESB configurations,
- Connecting to Yelp
- Search for yelp
- Business for business
Connecting to Yelp
To use the Yelp connector, add the <Yelp.init> element in your configuration before any Yelp operations.
init
|
<yelp.init>
<consumerKey>{$ctx:consumerKey}</consumerKey> <consumerKeySecret>{$ctx:consumerKeySecret}</consumerKeySecret> <accessToken>{$ctx:accessToken}</accessToken> <accessTokenSecret>{$ctx:accessTokenSecret}</accessTokenSecret> </yelp.init> |
Authentication
Overview
API requests must be authenticated in compliance with the OAuth 1.0a specification (Accessing Protected Resources).
Making a Request
Each request must contain the following OAuth protocol parameters:
OAuth Parameter
|
Value
|
oauth_consumer_key
| |
oauth_token
| |
oauth_signature_method
|
hmac-sha1
|
oauth_signature
|
The generated request signature, signed with the oauth_token_secret obtained (from Manage API Access).
|
oauth_timestamp
|
Timestamp for the request in seconds since the Unix epoch.
|
oauth_nonce
|
A unique string randomly generated per request.
|
These parameters may be passed in the HTTP (Authorization) header, as URL query keys, or in the POST data. Generating the OAuth signature is done by applying the HMAC-SHA1 with the oauth_token_secret. You may view your OAuth consumer key at Manage API Access. OAuth libraries are available to generate these requests.
Manage API Access
Step 1:
First login the yelp account for to get manage api access. Go to bellow link
Have account : Go to login (follow step 3)
Haven’t account: Go sign up (follow step 2)
step 2:
Yelp account can create only these countries, others wise get an error while creating account.
Countries:
Argentina, Australia, Austria, Belgium, Brazil, Canada, Czech Republic, Denmark, Finland, France, Germany, Ireland, Italy, Japan, Mexico, The Netherlands, New Zealand, Norway, Poland, Portugal, Singapore, Spain, Sweden, Switzerland, Turkey, UK, USA
step 3:
If have an account, normally login like this.
After the login, automatically redirect to this page. To get manage api access keys cilck the button.
According to click the button, get manage api access keys like this. if change api keys, click the Generate new API v2.0 token/secret button.
Search for yelp
search
|
<yelp.search>
<location>{$ctx:location}</location> <term>{$ctx:term}</term> <limit>{$ctx:limit}</limit> <offset>{$ctx:offset}</offset> <sort>{$ctx:sort}</sort> <category_filter>{$ctx:category_filter}</category_filter> <radius_filter>{$ctx:radius_filter}</radius_filter> <deals_filter>{$ctx:deals_filter}</deals_filter> <cc>{$ctx:country_code}</cc> <lang>{$ctx:language}</lang> <latitude>{$ctx:latitude}</latitude> <longitude>{$ctx:longitude}</longitude> <sw_latitude>{$ctx:sw_latitude}</sw_latitude> <sw_longitude>{$ctx:sw_longitude}</sw_longitude> <ne_latitude>{$ctx:ne_latitude}</ne_latitude> <ne_longitude>{$ctx:ne_longitude}</ne_longitude> </yelp.search> |
Search API
Overview:
- General Parameters
- Locale Parameters
- Methods of Specifying Location
- Specify Location by Geographical Bounding Box
- Specify Location by Geographic Coordinate
- Specify Location by Neighborhood, Address, or City
Request
Name
|
Method
|
Description
|
/v2/search
|
GET
|
Search for local businesses.
|
General Search Parameters
Name
|
Data
|
Required / Optional
|
Description
|
term
|
string
|
optional
|
Search term (e.g. "food", "restaurants"). If term isn't included we search everything.
|
limit
|
number
|
optional
|
Number of business results to return
|
offset
|
number
|
optional
|
Offset the list of returned business results by this amount
|
sort
|
number
|
optional
|
Sort mode: 0=Best matched (default), 1=Distance, 2=Highest Rated. If the mode is 1 or 2 a search may retrieve an additional 20 businesses past the initial limit of the first 20 results. This is done by specifying an offset and limit of 20. Sort by distance is only supported for a location or geographic search. The rating sort is not strictly sorted by the rating value, but by an adjusted rating value that takes into account the number of ratings, similar to a bayesian average. This is so a business with 1 rating of 5 stars doesn't immediately jump to the top.
|
category_
filter |
string
|
optional
|
Category to filter search results with. See the list of supported categories. The category filter can be a list of comma delimited categories. For example, 'bars,french' will filter by Bars and French. The category identifier should be used (for example 'discgolf', not 'Disc Golf').
|
radius_
filter |
number
|
optional
|
Search radius in meters. If the value is too large, a AREA_TOO_LARGE error may be returned. The max value is 40000 meters (25 miles).
|
deals_
filter |
boolean
|
optional
|
Whether to exclusively search for businesses with deals
|
Locale Parameters
The following lists optional locale parameters. Results will be localized in the region format and language if supported. Both cc and lang should be specified for proper localization.
Name
|
Data
|
Required / Optional
|
Description
|
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).
|
lang
|
string
|
optional
|
ISO 639 language code (default=en). Reviews and snippets written in the specified language will be shown.
|
Methods of Specifying Location
There are three available methods to specify location in a search. The location is a required parameter, and exactly one of these methods should be used for a request.
Specify Location by Geographical Bounding Box
Location is specified by a bounding box, defined by a southwest latitude/longitude and a northeast latitude/longitude geographic coordinate.
The bounding box format is defined as:
bounds=sw_latitude,sw_longitude|ne_latitude,ne_longitude
|
Bounds Parameters:
Name
|
Data
|
Required / Optional
|
Description
|
sw_latitude
|
double
|
required
|
Southwest latitude of bounding box
|
sw_longitude
|
double
|
required
|
Southwest longitude of bounding box
|
ne_latitude
|
double
|
required
|
Northeast latitude of bounding box
|
ne_longitude
|
double
|
required
|
Northeast longitude of bounding box
|
Specify Location by Geographic Coordinate
The geographic coordinate format is defined as:
ll=latitude,longitude,accuracy,altitude,altitude_accuracy
|
ll Parameters:
Name
|
Data
|
Required / Optional
|
Description
|
latitude
|
double
|
required
|
Latitude of geo-point to search near
|
longitude
|
double
|
required
|
Longitude of geo-point to search near
|
accuracy
|
double
|
optional
|
Accuracy of latitude, longitude
|
altitude
|
double
|
optional
|
Altitude
|
altitude_accuracy
|
double
|
optional
|
Accuracy of altitude
|
Specify Location by Neighborhood, Address, or City
Location is specified by a particular neighborhood, address or city.
The location format is defined below.
location=location
|
Location Parameters:
Name
|
Data
|
Required / Optional
|
Description
|
location
|
string
|
required
|
Specifies the combination of "address, neighborhood, city, state or zip, optional country" to be used when searching for businesses.
|
An optional latitude, longitude parameter can also be specified as a hint to the geocoder to disambiguate the location text.
The format for this is defined as:
cll=latitude,longitude
|
cll Parameters:
Name
|
Data
|
Required / Optional
|
Description
|
latitude
|
double
|
required
|
Latitude of current location
|
longitude
|
double
|
required
|
Longitude of current location
|
Business for yelp
business
|
<yelp.business>
<id>{$ctx:id}</id> <country_code>{$ctx:country_code}</country_code> <language>{$ctx:language}</language> <lang_filter>{$ctx:lang_filter}</lang_filter> </yelp.business> |
Business API
Request
Name
|
Method
|
Description
|
/v2/business/{id}
|
GET
|
Lookup business information by id.
|
Locale Parameters
The following lists optional locale parameters. Results will be localized in the region format and language if supported. Both cc and lang should be specified for proper localization.
Locale Parameters
Name
|
Data
|
Required
/Optional |
Description
|
country_code
|
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).
|
language
|
string
|
optional
|
ISO 639 language code (default=en). Reviews and snippets written in the specified language will be shown.
|
lang_filter
|
boolean
|
optional
|
Whether to filter business reviews by the specified lang
|
Errors
This section defines the standard error codes returned by the Yelp API.
Error Response:
Response codes are defined as strings rather than numeric constants.
ID
|
Text
|
Description
|
INTERNAL_
ERROR |
Internal error
|
Indicates an internal server error has occurred.
|
EXCEEDED_
REQS |
Exceeded max daily requests
|
Indicates that the number of requests executed for the given API key has exceeded its daily limit.
|
MISSING_
PARAMETER |
A parameter is missing from the request Indicates that an input parameter is missing from the request.
|
The error response will include the field that was missing.
|
INVALID_
PARAMETER |
Invalid parameter
|
Indicates that an input parameter value in the request is invalid. The error response will include the field that was invalid.
|
INVALID_
SIGNATURE |
Signature was invalid
|
Indicates that the oauth_signature for the request is invalid.
|
INVALID_
CREDENTIALS |
The email and password combination is invalid
|
Indicates that the email/password for Yelp account authorization is invalid.
|
INVALID_
OAUTH_ CREDENTIALS |
The OAuth credentials are invalid
|
Indicates that the OAuth credentials for the request are invalid.
|
INVALID_
OAUTH_USER |
The user specified by the OAuth request is missing or invalid.
|
The request requires a user and the user specified is missing or invalid. The user may be invalid if it is associated with a developer account.
|
ACCOUNT_
UNCONFIRMED |
The associated account's email is not yet confirmed
|
Indicates that the Yelp account has not yet been activated.
|
PASSWORD_
TOO_LONG |
Please enter a password of 16 characters or less
|
Indicates that the password for the Yelp account is too long.
|
UNAVAILABLE_
FOR_LOCATION |
API unavailable in this location
|
Indicates that API requests are unavailable in the given location.
|
AREA_TOO_
LARGE |
Location specified an area that is too large to search in
|
Indicates that the geographical area is too large for this search request. Max search area is 2,500 square miles.
|
MULTIPLE_
LOCATIONS |
Multiple locations match query
|
Indicates that the given search location could not be disambiguated.
|
BUSINESS_
UNAVAILABLE |
Business information is unavailable
|
We may not be able to provide details for certain businesses, for example if they don't have any reviews yet.
|