A website with information of any kind about a certain geographical location might find interesting to include a list of places, points of interest, businesses and services available in that area.
Yelp is one of the possible choices, together with Google Places, Facebook, etc. for a service provider that implements an API that can be used to retrieve that kind of information. This post explains how to query the Yelp API from a PHP script to obtain a list of nearby places.
Characteristics of the Yelp service
The Places API can be used to search for businesses, services and landmarks around a given point expressed as a (longitude,latitude) coordinate pair, or contained in a bounding box. The results can also be filtered based on categories.
The service is free of charge, with a limit of 10.000 requests/day.
Besides, there is an affiliate program through Commision Junction. Websites that publish business deals from Yelp can obtain an extra income in this way.
Obtaining access keys
Requests to the API must be authenticated with OAuth. Thus, the first step to use the API is obtaining a pair of keys from the “Manage API Access” page in the Yelp Developers website.
First, go to https://www.yelp.com/signup and register as a Yelp user.
Then, go to https://www.yelp.com/developers. The signup as developer is automatically done, and a confirmation email is sent to the email address entered. To proceed, the confirmation link in the message received must be clicked.
Next, go to “Manage API Access“, and fill the form displayed with the applicable information:
After the form has been submitted, the access keys are displayed. Copy and save them in a safe place:
Download and installation of the PHP library
To send signed requests to the API, a library implementing the OAuth protocol must be used. The easiest way to get the library is by downloading the yelp-api-master.zip package from the github page for the Yelp API.
The package is uncompressed into a directory tree with samples for a good number of programming languages, including Java, C#, Perl and PHP.
Specifically, the PHP OAuth library can be found in yelp-api-master/v2/php/lib/OAuth.php. There is also a sample PHP script in yelp-api-master/v2/php/sample.php
Issuing a simple query
The sample script “sample.php” can be analyzed to understand how to access the Yelp API from a PHP script.
The sample script queries for places to have dinner in San Francisco, CA. This is done with an authenticated access to the url:
(Where “San+Francisco%2c+CA” is the result of encoding “San Francisco, CA” as a valid URL).
First, the script loads the OAuth library, and defines several variables:
require_once('lib/OAuth.php'); $CONSUMER_KEY = YELP_CONSUMER_KEY; $CONSUMER_SECRET = YELP_CONSUMER_SECRET; $TOKEN = YELP_TOKEN; $TOKEN_SECRET = YELP_TOKEN_SECRET; $API_HOST = 'api.yelp.com'; $DEFAULT_TERM = 'dinner'; $DEFAULT_LOCATION = 'San Francisco, CA'; $SEARCH_LIMIT = 3; $SEARCH_PATH = '/v2/search/'; $BUSINESS_PATH = '/v2/business/';
Then, the request is created, and signed with the OAuth credentials:
$unsigned_url = "http://api.yelp.com/v2/search/?term=dinner&location=San+Francisco%2C+CA&limit=3"; // Create the token and consumer objects $token = new OAuthToken($GLOBALS['TOKEN'], $GLOBALS['TOKEN_SECRET']); $consumer = new OAuthConsumer($GLOBALS['CONSUMER_KEY'], $GLOBALS['CONSUMER_SECRET']); // Create the OAuth request $oauthrequest = OAuthRequest::from_consumer_and_token( $consumer, $token, 'GET', $unsigned_url ); // Sign the request $signature_method = new OAuthSignatureMethod_HMAC_SHA1(); $oauthrequest->sign_request($signature_method, $consumer, $token); // Obtener la url firmada $signed_url = $oauthrequest->to_url();
Finally, te signed URL is used to access the API. The response in JSON format is converted to a PHP structure and printed to standard output:
$ch = curl_init($signed_url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HEADER, 0); $data = curl_exec($ch); curl_close($ch); print_r(json_decode($data));
And this is the result:
stdClass Object ( [region] => stdClass Object ( [span] => stdClass Object ( [latitude_delta] => 0.014647263950323 [longitude_delta] => 0.016024466605387 ) [center] => stdClass Object ( [latitude] => 37.784977898311 [longitude] => -122.40405513651 ) ) [total] => 6245 [businesses] => Array (  => stdClass Object ( [is_claimed] => 1 [rating] => 4 [mobile_url] => http://m.yelp.com/biz/marlowe-san-francisco-2 [rating_img_url] => http://s3-media4.fl.yelpcdn.com/... [review_count] => 1346 [name] => Marlowe [snippet_image_url] => http://s3-media3.fl.yelpcdn.com/photo/... [rating_img_url_small] => http://s3-media4.fl.yelpcdn.com/assets/... [url] => http://www.yelp.com/biz/marlowe-san-francisco-2 [menu_date_updated] => 1421227117 [phone] => 4157771413 ... )  => stdClass Object ... )
Coordinate based searches
In the previous sample, the location to be searched was specified as free text in the value of the “location” parameter: “location=San+Francisco%2C+CA”.
The location can be more precisely specified with the “ll” parameter, whose value is a (latitude,longitude) coordinate pair. “ll” is commonly used in conjunction with the “radius_filter” parameter, to specify the maximum distance in meters that returned businesses should be from the the point.
Another possibility is to specify a rectangular area to be searched with the “bounds” parameter, as follows:
Filtering by category
Every record in the Yelp database is assigned one or several categories from the set of more than 1000 recognised categories. The complete category list can be found in https://www.yelp.com/developers/documentation/v2/all_category_list.
The “category_filter” parameter can be used to restrict the search to a given category or categories
Business in the Yelp database can create deals for the users: discounts, promotions, etc. The “deals_filter” parameter can be used to limit the search to only those businesses with active deals.