PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

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)

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.

INSTANCE METHODS

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-2003 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.

SEE ALSO

Ruby/Google home page - http://www.caliban.org/ruby/ Google Web APIs - http://www.google.com/apis/

BUGS

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

HISTORY

$Id: google.rb,v 1.31 2003/01/18 00:40:50 ianmacd Exp $