NAME

Search::Google - search Google using the REST (aka AJAX) API

VERSION

This documentation refers to Search::Google version 1.0.2

SYNOPSIS

use Search::Google::Web;

# you should provide a valid http referer address according
# to Google AJAX Search API terms of use!
Search::Google::Web->http_referer('http://example.com');

my $res = Search::Google::Web->new(
	q => 'Larry Wall',
);

die "response status failure" if $res->responseStatus != 200;

my $data = $res->responseData;

my $cursor = $data->cursor;

printf "pages: %s\n", $cursor->pages;
printf "current page index: %s\n", $cursor->currentPageIndex;
printf "estimated result count: %s\n", $cursor->estimatedResultCount;

my @results = $data->results;

foreach my $r (@results) {
	printf "\n";
	printf "title: %s\n", $r->title;
	printf "url: %s\n", $r->url;
}

DESCRIPTION

Search::Google is a set of modules that use Google REST (aka AJAX) API for searching and provide OO interface to Google response objects. Search::Google itself is a base class for all these modules and usually not meant to be used separately.

METHODS

service_uri

A class method to set service URI. Each module (from Search::Google::*) use it's own predefined HTTP URI, so you don't have to change it normally.

http_referer

A class method that sets Referer header to use for next searches.

Search::Google::Images->http_referer('http://example.org/search.html');

Default is 'http://example.com'.

Note: Google says that you should supply a valid HTTP referer header each time you perform the search request using their AJAX API.

new

The constructor use it's arguments to build a valid HTTP GET request using the service_uri, so it takes the same arguments as the relevant web service takes. Please refer to 'Google AJAX Search API' documentation for complete list of arguments. Example:

my $res = Search::Google::Web->new(
	q => 'Pamela Anderson',
	start => 4,
	hl => 'fr',
);

The code above will perform the HTTP GET request using the following URL:

http://ajax.googleapis.com/ajax/services/search/web?hl=fr&q=Pamela+Anderson&v=1.0&start=4

The $res is a Search::Google::Web object that represents Google Web Search response format.

Note: You can left protocol version number unspecified while making your searches since v=1.0 is passed by default.

Search::Google::* objects completely represent Google AJAX API search responses and have the following structure:

{
	"responseData" => {
		"results" => [],
		"cursor" => {}
	},
	"responseDetails" => undef | string-on-error,
	"responseStatus" => 200 | error-code
}

responseStatus

The responseStatus property contains a value of 200 on success and a non-200 HTTP error status code on failure. If there is a failure, responseDetails contains a diagnostic string.

responseDetails

Contain an error string if responseStatus is not 200.

responseData

Returns an object that provides OO access to Google responseData structure. This object has actually two methods: a results that returns the array of result object for the given search type and cursor method that return cursor object object (if exists).

Please refer to 'Google AJAX Search API' documentation for response structure details of exact services for exact search types.

AVAILABLE CLASSES

Search::Google::Web

Search::Google::Blogs

Search::Google::Books

Search::Google::Images

Search::Google::Local

Search::Google::Video

Search::Google::News

WARNING

This is alpha software. If you like this module, please provide us with failing tests and API suggestions.

DEPENDENCIES

Search::Google uses JSON::Any for decoding Google AJAX Search API response and LWP for search request sending.

SEE ALSO

http://code.google.com/p/search-google/ - this project on Google code;

http://code.google.com/apis/ajaxsearch/documentation/#fonje - information about Google AJAX API in non-Javascript environments;

http://code.google.com/apis/ajaxsearch/documentation/reference.html#_intro_fonje - detailed specification for Google AJAX Search API.

LICENSE AND COPYRIGHT

Copyright 2008, Eugen Sobchenko <ejs@cpan.org> and Sergey Sinkovskiy <glorybox@cpan.org>

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.