Monday, July 7, 2014

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
Your OAuth consumer key (from Manage API Access).
oauth_token
The access token, obtained (from Manage API Access).
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


Log In   Yelp.png

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

Sign Up   Yelp.png

step 3:
If have  an account, normally login like this.
Log In   Yelp111.png




After the login, automatically redirect to this page. To get manage api access keys cilck the button.
API Access   Yelp for Developers.png

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.
Getting Started   Yelp for Developers.png

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.