<img src=“https://travis-ci.org/cosm/google_custom_search.png?branch=master” alt=“Build Status” /> <img src=“https://gemnasium.com/cosm/google_custom_search.png” alt=“Dependency Status” />

Google Custom Search¶ ↑

This project is a Ruby API to Google’s Custom Search Engine (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).

Google Custom Search is currently compatible with Rails 3. It should also work with Rails 2.x but that hasn’t been tested.

Install¶ ↑

As a Gem¶ ↑

Add to your Gemfile:

gem "google_custom_search"

and run at the command prompt:

bundle install

Configure¶ ↑

You must configure the gem before use. If you are using Rails, the best way to do this is to create an initializer in config/initializers/google_custom_search.rb:

GoogleCustomSearch.configure do |config|
  config.cx = "1234abcd" # your search engine ID obtained from the Google Custom Search setup page
  config.default_params = { :ie => 'utf8', :oe => 'utf8' } # any default params you want to add to all requests
  config.secure = true # if set to true make requests over SSL
  config.timeout = 5 # timeout in seconds to pass to Net::HTTP
end

If you aren’t using Rails, then you just need to add this initialization block somewhere that will be executed as your app boots.

Use¶ ↑

To perform a search:

search = GoogleCustomSearch.search("Hank Aaron")
search = GoogleCustomSearch.search("Hank Aaron", :offset => 20, :per_page => 20)
search = GoogleCustomSearch.search("Hank Aaron", :page => 2)

If the page parameter is supplied then this will overwrite offset (behind the scenes we calculate a new offset derived from the page number and per_page value.

The results variable is now a GoogleCustomSearch::ResultSet object:

search.total_entries    # total number of results (integer)
search.per_page         # current page size
search.results          # array of result objects
search.suggestion       # suggested search term, if any
search.start_index      # index of the first result in the current page
search.end_index        # index of the last result in the current page
search.current_page     # current page number (calculated from above values)
search.total_pages      # total number of pages for the current query
search.offset           # offset parameter

Iterate through the results:

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

Future¶ ↑

• 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 © 2009-11 Alex Reisner, released under the MIT license