NAME

Ruby/Google

SYNOPSIS

require 'google'

KEY = File.open("#{ENV['HOME']}/.google_key") {|kf| kf.readline.chomp}

query = ARGV.shift || 'ruby programming language'
google = Google::Search.new(KEY)
google.utf8('iso-8859-15')

i = 0
q = google.search(query)
q.resultElements.each do |result|
  printf "\nResult # %d\n\n", i += 1
  result.each do |key|
    printf("%s = %s\n", key, result.send(key))
  end
end

puts '---------------------------------'
i = 0
q.directoryCategories.each do |category|
  printf "\nCategory # %d\n\n", i += 1
  category.each do |key|
    printf("%s = %s\n", key, category.send(key))
  end
end

printf "Estimated number of results is %d.\n", q.estimatedTotalResultsCount
printf "Your query took %6f seconds.\n", q.searchTime

DESCRIPTION

Ruby/Google allows you to programmatically query the Google search-engine. It is currently in the alpha stage and the interface is liable to change at any time.

CLASS METHODS

Search.new(key): This constructs a new Google::Search object. The key parameter is the key that Google assigned to you when you registered for the Web API download. If you don't yet have a key, go to Google and obtain one.
Search.query_length_ok?(query): This checks to see whether the query length is under MAX_QUERY_LENGTH characters. It returns either true or false.
Search.query_words_ok?(query): This checks to see whether the number of words in query is under MAX_QUERY_WORDS. It returns either true or false.
Search.query_sites_ok?(query): This checks to see whether the number of site: restrict terms in query is below MAX_QUERY_SITES. It returns either true or false.

-

The above 3 methods check for compliance with the limitations of the Google Web API, as defined in section 2.7 of the APIs_Reference.html file that came with your Google API archive.

Search.query_ok?(query): This encapsulates the above 3 methods and can be used when one wishes to know if query is bad, but not necessarily why it is bad. It returns either true or false.
Search.restrict(type, *data): This assembles a query term, based on the restrict type and its parameter(s), passed as *data. A full list of query terms is given in section 2.2 of APIs_Reference.html.

If type is phrase, a double-quoted copy of each string passed as *data is returned.
If type is daterange, the first three parameters of *data must be the year, month, and day of a start date. The next three parameters, if given, form the year, month, and day of an end date. If these last three parameters are not given, today's date will be substituted.
Other supported restrict types are site, intitle, allintitle, inurl, allinurl, allintext, allinlinks, filetype, notfiletype, info, link, related, cache, include and exclude. Some of these names differ slightly from those given in section 2.2 of APIs_Reference.html in order to simplify their use and memorability.

INSTANCE METHODS

Search#utf8(source)

If source is not nil, subsequent invocations of Search#search and Search#spell will convert their first argument from encoding source to UTF-8 prior to sending the request to Google.

You should use this if your query string is not already UTF-8 and contains 8 bit characters. Otherwise, an XSD::ValueSpaceError exception may be thrown.

Search#search(query, start, max, filter, restrict, safe, lr, ie, oe)

This performs a standard Google query search. Only the query parameter is mandatory.

The meaning of the other parameters can be obtained from section 2.1 of APIs_Reference.html, although the ie and oe parameters are now deprecated and should not be used. A warning will be issued if Ruby is run in verbose mode and either of these parameters is used.

This method returns a Struct::Response object, the members of which are described in section 3.1 of APIs_Reference.html.

The resultElements member is an Array of Struct::ResultElement objects. Members of the Struct::ResultElement object are described in section 3.2 of APIs_Reference.html. Note that the URL parameter is actually represented by the url member, since Ruby does not allow a variable name to begin with a capital letter.

The directoryCategories member is an Array of Struct::DirectoryCategory. Members of the Struct::DirectoryCategory object are described in section 3.3 of APIs_Reference.html.

Search#spell(phrase)

This performs a Google spell-check on phrase. If Google has a spelling suggestion to make, a String is returned. Otherwise, nil is returned.

Search#cache(url)

This attempts to retrieve a copy of the page corresponding to url from Google's cache. If Google has not cached the URL in question, a page containing a message to this effect will be returned instead.

This method always returns a String.

ENVIRONMENT

HTTP_PROXY or http_proxy: If this is defined, the named system will be used as an HTTP proxy.

AUTHOR

Written by Ian Macdonald <ian@caliban.org>

COPYRIGHT

Copyright (C) 2002-2006 Ian Macdonald

This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.

BUGS

Send all bug reports, enhancement requests and patches to the author.

HISTORY

$Id: google.rb,v 1.37 2006/02/08 00:28:18 ianmacd Exp $