/ 
WebService-Yelp-0.02
River stage zero No dependents
/ WebService::Yelp

NAME

WebService::Yelp - Yelp.com API Client Implementation

SYNOPSIS

use strict;
use WebService::Yelp;

my $yelp = WebService::Yelp->new({ywsid => 'XXXXXXXXXXXX'});

my $biz_res = $yelp->search_review_hood({
                                            term => 'cream puffs',
                                            location => 'San Francisco',
                                            };
for my $biz (@{$biz_res->businesses()}) {

  my @reviews = $biz->reviews();
  my @hoods = $biz->neighborhoods();

}

DESCRIPTION

This module implements a programmatic interface to yelp.com's public REST API.

REQUIREMENTS

Before you can use this module, you'll need to obtain your very own "Yelp Web Service ID" (ywsid) from http://www.yelp.com/developers. While you are there, I'd also urge you to read Yelp's Terms of Use and documentation.

Much more documentation is available on Yelp's site:

http://www.yelp.com/developers/documentation

Most of the functions here map directly to API commands, so it would be a good idea to familiarize yourself with their documentation first and then take a look at the methods and parameters here.

METHODS

new

my $yelp = WebService::Yelp->new($hash_ref);

Required Parameters

    * ywsid - your Yelp Web Service ID.

Optional Parameters

    * http_proxy - specify a proxy server to use

    * http_timeout - specify a timeout (Default is 10 seconds)

Return Value

    * A new WebService::Yelp object, or undef if there were problems.

Review Search Functions

This set of functions searches for and returns review and business information. The following two parameters are common across these functions. Note that output determines the return values for all search functions as well.

    * output - Result output type.

This controls what is returned by the API. The default is WebService::Yelp::* objects. Other options are 'php', 'json', and 'pickle'. If one of these three options is specified, the raw data will be returned by the search function as a scalar value. Otherwise, a WebService::Yelp::Result object will be returned. If there was a transport level error, search functions simply return undef and print the requests status line to STDERR.

Your first step should be to check the WebService::Yelp::Message object available by calling the WebService::Yelp::Result->message() method and checking the value of code(). See:

http://www.yelp.com/developers/documentation/search_api#rCode

for more information on the return codes, messages, and error descriptions.

    * category - Narrow results to specific categories.

By selecting only specific categories, search results can be confined to businesses that match those categories. Multiple categories can be speficied by combining them with a plus sign, i.e. bars+poolhalls

search_review_bb - Searching by Map Bounding Box

Limit the search to an area within a specific geographical box specified by four geographic points.

Required Parameters

    * tl_lat - Top Left latitude of bounding box

    * tl_long - Top Left longitude of bounding box

    * br_lat - Bottom right latitude of bounding box

    * br_long - Bottom right longitude of bounding box

Optional Parameters

    * term - Business name or search term.

    * num_biz_requested - Number of businesses to return (1-20, Default 10).

search_review_gpr - Search by Geo-Point and Radius

Given a point and an outward radius, search for businesses within the area.

Required Parameters

    * lat - The latitude of the point.

    * long - The longitude of the point.

Optional Parameters

    * radius - The outward radius from the two points above, Max is 25.

    * term - Business name or search term.

    * num_biz_requested - Number of businesses to return (1-20, Default 10).

search_review_hood - Search by Neighborhood, Address or City

Given a general or specific location, search for matching businesses.

Required Parameters

    * location - An address, neighborhood, city, state, or zip code.

Optional Parameters

    * radius - The outward radius from the two points above, Max is 25.

    * term - Business name or search term.

    * num_biz_requested - Number of businesses to return (1-20, Default 10).

search_phone - Search by Phone Number

Find a specific business by phone number.

Required Parameter

    * phone - An all digit phone number (like 1-234-567-8901)

Neighborhood Search Functions

The following functions return neighborhood data. The output parameter as described above is valid for these as well.

search_neighborhood_geocode - Search for Neighborhoods by Geo-Ppoint

Given a latitude and longitude, return neighborhood information for the location.

Required Parameters

    * lat - The latitude.

    * long - The longitude.

search_neighborhood_location - Search by Address, City, State or Zip

Given a general or specific location, search for matching neighborhoods.

Required Parameters

    * location - An address, neighborhood, city, state, or zip code.

Other Functions

call - The actual search function caller

Call is the actual search implementation. The other functions call it by specifying the search function first, so if you'd prefer you can use it directly. Search functions names are separated by periods (in the same way the methods above use underscores) i.e.

$yelp->search_review_gpr({ ....

is the same as

$yelp->call('search.review.gpr', { ....

SEE ALSO

LWP::UserAgent

This module's source and other documentation is hosted at http://code.google.com/p/perl-www-yelp-api/

AUTHOR

josh rotenberg, <joshrotenberg@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by josh rotenberg

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

Note that this software is not maintained, endorsed, sponsored, supported, or otherwise managed by Yelp. All inquiries related to this software should be directed to the author.