= Google Custom Search

This project is a Ruby API to Google's Custom Search Engine (http://www.google.com/cse).

If you want a Google-like search engine for your web site, why not use Google? For $100/yr (more if you have over 1,000 pages) you can get access to Google search results for your site in XML format. The google_custom_search gem helps you access this web service and publish the results on your site however you like (all covered under Google's acceptable use policy).

<b>Google Custom Search is currently compatible with Rails 2.x and Rails 3.</b>


== 1. Install

Install either as a Rails plugin:

  script/plugin install git://github.com/alexreisner/google_custom_search.git

or as a gem:

  # add to config/environment.rb:
  config.gem "google_custom_search", :source => "http://gemcutter.org/"
  
  # at command prompt:
  sudo rake gems:install

or as a standalone gem (outside of Rails):

  sudo gem install google_custom_search --source http://gemcutter.org


== 2. Configure

You *must* define a constant in your application called <tt>GOOGLE_SEARCH_CX</tt>. For example, if you're using Rails, create a file <tt>config/initializers/google_custom_search.rb</tt>:

  GOOGLE_SEARCH_CX = "..."

You can find the CX value for your custom search engine via the search control panel on Google's site (click the "Get code" link and you'll see a hidden "cx" field in the sample HTML form).

Optionally, you can set default Google search params, such as encoding, by setting up the <tt>GOOGLE_SEARCH_PARAMS</tt> hash in the same initializer:

  GOOGLE_SEARCH_PARAMS = {
    :ie => 'utf8',
    :oe => 'utf8'
  }

If you're working outside of Rails you'll also need some +require+ statements:

  require 'rubygems'
  require 'rexml/document'
  require 'google_custom_search'


== 3. Use

To perform a search:

  results = GoogleCustomSearch.search("Hank Aaron")
  
The +results+ variable is now a GoogleCustomSearch::ResultSet object:
  
  results.total            # number of results (integer)
  results.pages            # array of result objects
  results.suggestion       # suggested search term, if any

Iterate through the results:

  results.pages.each do |result|
    result.title           # result title
    result.url             # result URL
    result.description     # excerpt, with terms highlighted
  end


== Future

* prevent NameError when GOOGLE_SEARCH_CX is missing: show nice msg
* access to all data returned by Google
* support for features of CSE free version
* support for multiple CSEs in one app (GOOGLE_SEARCH_CX should be a hash)


Copyright (c) 2009 Alex Reisner, released under the MIT license