sk_google_custom_search_api 2.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7242a2df55757ecf17e6e68e6176b2ed7d248727
+  data.tar.gz: f69674749f4670b55fa094862e36ea9d1bd05475
+SHA512:
+  metadata.gz: 8e05b306d9ddceb3cbb50fef1f829818b8a4b4e7ff4e441cdb5ae73aaa0b2c50cb62c21b13129fb31078bb6630b3ad201fcc348000df1a7bf4e8eded02dc2f46
+  data.tar.gz: 66de2254b6b00cb4cef34cf76aa872a80130c1e31dd9023cd260ecb3dd0a5cf2839d0420aa54202ce8b0e6a8c6a31ba6f42b3cbcb823d0cc5c3875b84edafb9a

data/CHANGELOG.rdoc

@@ -0,0 +1,2 @@
+= Changelog
+

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in importers.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,52 @@
+PATH
+  remote: .
+  specs:
+    google_custom_search_api (2.0.0)
+      addressable
+      httparty
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.3.8)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.2.5)
+    hashdiff (0.2.3)
+    httparty (0.13.7)
+      json (~> 1.8)
+      multi_xml (>= 0.5.2)
+    json (1.8.3)
+    multi_xml (0.5.5)
+    rspec (3.4.0)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+    rspec-core (3.4.1)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-mocks (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.1)
+    safe_yaml (1.0.4)
+    vcr (3.0.1)
+    webmock (1.22.5)
+      addressable (< 2.4.0)
+      crack (>= 0.3.2)
+      hashdiff
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  google_custom_search_api!
+  json
+  rspec
+  vcr
+  webmock
+
+BUNDLED WITH
+   1.10.6

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Ben Wiseley
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,276 @@
+# Google Custom Search
+
+This project is a Ruby lib for Google's Custom Search ENgine API (http://www.google.com/cse).  There seem to be quite a few cse libs out there that don't work so I rolled this up quickly.
+
+Questions/comments, etc: wiseleyb@gmail.com
+
+## Install
+
+Add to your Gemfile:
+
+  gem "sk_google_custom_search_api"
+
+then
+
+  bundle install
+
+Google's API management is confusing at best. At the time of this writing you codes like so:
+
+### GOOGLE_API_KEY
+
+* Go to [Google Projects](https://console.developers.google.com/project)
+* Create a project, open it
+* Under `Explore other services` choose `Enable APIs and get credentials like keys`
+* Search for `custom search` and click on it
+* In the left column click on `Credentials`
+* Under `API keys` grab your key. This is your `GOOGLE_API_KEY`
+
+### GOOGLE_SEARCH_CX
+
+* Go to [Google CSE](https://cse.google.com/cse)
+* Create a search engine and click on it
+* Under `Setup > Tabs > Basic` find `Details` and click `Search engine ID`
+* This is your GOOGLE_SEARCH_CX
+* Make sure to add a site under `Sites to search`
+
+## Use
+
+### Search
+
+To perform a search:
+
+```
+  results = GoogleCustomSearchApi.search("poker", {api_key: API_KEY, cx_key: CX_KEY})
+```
+Results now contains a raw version and a class'ed version of the data show in ```Sample results``` below.
+
+This means you can do:
+
+```
+  results["items"].each do |item|
+  	puts item["title"], item["link"]
+  end
+```
+
+or
+
+```
+  results.items.each do |item|
+    puts item.title, item.link
+  end
+```
+
+### Paging
+
+Google only returns 10 results at a time and a maximum of 100 results. The easiest way to page through results if to use `:page`. Paging is 1 based (1-10). The default page is 1
+
+```
+  results = GoogleCustomerSearchApi.search("poker", page: 2)
+  results.pages == 10
+  results.current_page == 2
+  results.next_page == 3
+  results.previous_page == 1
+
+  results = GoogleCustomerSearchApi.search("poker", page: 1)
+  results.pages == 10
+  results.current_page == 1
+  results.next_page == 2
+  results.previous_page == nil
+
+  results = GoogleCustomerSearchApi.search("poker", page: 10)
+  results.pages == 10
+  results.current_page == 10
+  results.next_page == nil
+  results.previous_page == 9
+```
+
+You can also use `:start` - which can be any number between 1 and 99. The `:page` helpers won't be accurate with `:start`
+
+Example: get results 13-23
+
+```
+  results = GoogleCustomerSearchApi.search('poker', start: 13)
+```
+
+See [Custom Search](http://code.google.com/apis/customsearch/v1/using_rest.html) documentation for an explanation of all fields available.
+
+### Search and return all results
+
+This method isn't so useful because it's pretty slow (do to fetching up to 10 pages from Google). Helpful for testing sometimes.
+
+```
+  results = search_and_return_all_results('poker')
+  results.first.items.size # == 10
+
+  search_and_resturn_all_results('poker') do |results|
+    results.items.size # == 10  10 times
+  end
+
+  search_and_return_all_results(
+    '"California cult winery known for its Rhône"') do |results|
+    results.items.size # == 3  1 time
+  end
+```
+
+### Errors
+
+Custom Search only returns a maximum of 100 results so - if you try something like
+
+```
+  results = GoogleCustomSearchApi.search('poker', start: 101)
+```
+You get error and empty items.
+
+```
+	{
+	  "error"=> {
+	    "errors"=> [
+	      {
+	        "domain"=>"global",
+	         "reason"=>"invalid",
+	         "message"=>"Invalid Value"
+	      }
+	    ],
+	    "code"=>400,
+	    "message"=>"Invalid Value"
+	  },
+	  "items"=>[]
+	}
+```
+
+So check for:
+
+```
+  if results.try(:error) || results.items.empty?
+```
+### Rails example
+
+In **Gemfile**
+
+```
+gem "google_custom_search_api"
+```
+
+In **config/initializers/google_search.rb**
+
+```
+GOOGLE_API_KEY = '...'
+GOOGLE_SEARCH_CX = '...'
+```
+
+In **config/routes.rb**
+
+```
+  get '/search' => 'search#index'
+```
+
+In **app/controllers/search_controller.rb** you'd have something like this:
+
+```
+class SearchController < ApplicationController
+  def index
+    if params[:q]
+      page = params[:page] || 1
+      @results = GoogleCustomSearchApi.search(params[:q],
+                                              page: page)
+	end
+  end
+end
+```
+
+And a simple view might look like this **app/search/index.html.erb** (this is using bootstrap styling)
+
+```
+<section class='search-section'>
+  <div class='text-center titles-with-yellow'>
+    <h1>Search/h1>
+  </div>
+  <div class='container'>
+    <div class='text-center search-bar'>
+      <%= form_tag search_path, method: :get  do %>
+        <div class="inner-addon right-addon">
+          <i class="glyphicon glyphicon-search"></i>
+          <%= text_field_tag :q, params[:q], class: 'form-control' %>
+        </div>
+      <% end %>
+    </div>
+  </div>
+
+  <% if @results && !@results.items.empty? %>
+    <div class='container'>
+      <% @results.items.each do |item| %>
+        <div class='row'>
+          <h4><%= link_to item.htmlTitle.html_safe, item.link %></h4>
+          <div>
+            <% if item['pagemap'] &&
+                  item['pagemap']['cse_thumbnail'] &&
+                  img = item.pagemap.cse_thumbnail.first %>
+              <div class='col-sm-2'>
+                <%= image_tag(img.src, width: '200px') %>
+              </div>
+              <div class='col-sm-10'>
+                <%= item.htmlSnippet.html_safe %>
+              </div>
+            <% else %>
+              <%= item.htmlSnippet.html_safe %>
+            <% end %>
+          </div>
+        </div>
+      <% end %>
+    </div>
+    <div class='container search-prev-next'>
+      <div class='row text-center'>
+        <% if @results.previous_page %>
+          <%= link_to '<< Previous',
+            search_path(q: params[:q], page: @results.previous_page),
+            class: 'btn' %>
+        <% end %>
+        <% @results.pages.times do |i| %>
+          <%= link_to i + 1,
+            search_path(q: params[:q], page: i+1),
+            class: 'btn btn-page' %>
+        <% end %>
+        <% if @results.next_page %>
+          <%= link_to 'Next >>',
+            search_path(q: params[:q],
+                        page: @results.next_page),
+            class: 'btn' %>
+        <% end %>
+      </div>
+    </div>
+  <% else %>
+    <h4>No results</h4>
+  <% end %>
+</section>
+```
+
+### Encoding issues
+
+TODO - this section needs work
+
+CSE will return non utf-8 results which can be problematic.  I might add in a config value that you can explicitly set encoding.  Until then a work around is doing stuff like:
+
+```
+  results.items.first.title.force_encoding(Encoding::UTF_8)
+```
+
+More on this here: http://code.google.com/apis/customsearch/docs/ref_encoding.html
+
+## Contributing - Running tests
+
+Pull requests welcome.
+
+To run tests
+```
+  git clone git@github.com:wiseleyb/google_custom_search_api.git
+  cd google_custom_search_api
+  bundle install
+  bundle exec rspec spec
+```
+
+## Credits
+* Based largely on the gem https://github.com/alexreisner/google_custom_search
+* Awesome ResponseData class from https://github.com/mikedemers/rbing
+* Work done while working on a project for the company http://reInteractive.net in sunny Sydney.  A great ruby shop should you need help with something.
+
+Copyright (c) 2012 Ben Wiseley, released under the MIT license

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Google Custom Search API #{GoogleCustomSearch::VERSION}"
+  rdoc.rdoc_files.include('*.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/init.rb

@@ -0,0 +1,2 @@
+require "addressable/uri"
+require 'google_custom_search_api'

data/lib/google_custom_search_api.rb

@@ -0,0 +1,178 @@
+##
+# Add search functionality (via Google Custom Search). Protocol reference at:
+# http://www.google.com/coop/docs/cse/resultsxml.html
+#
+
+require 'httparty'
+require 'addressable/uri'
+
+module GoogleCustomSearchApi
+  extend self
+
+  ##
+  # Search the site.
+  #
+  # opts
+  #   see list here for valid options
+  #   http://code.google.com/apis/customsearch/v1/using_rest.html#query-params
+  def search(query, opts = {})
+    opts[:start] ||= 1
+
+    if (page = opts.delete(:page))
+      page = page.to_i
+      opts[:start] = (page - 1).abs * 10 + 1
+    else
+      page = (opts[:start].to_i / 10) + 1
+    end
+    page = 10 if page > 10
+
+    # Get and parse results.
+    url = url(query, opts)
+    return nil unless results = fetch(url)
+
+    results['items'] ||= []
+
+    # paging
+    if results.keys.include?('queries')
+      data = results['queries']['request'].first
+      results['pages'] = data['totalResults'].to_i / 10
+      results['pages'] = 10 if results['pages'] > 10
+      results['current_page'] = page.to_i
+
+      results['next_page'] = nil
+      results['previous_page'] = nil
+
+      if results['queries'].include?('nextPage') && page < 10
+        results['next_page'] = results['current_page'] + 1
+      end
+
+      if page > 1
+        results['previous_page'] = page - 1
+      end
+    end
+
+    ResponseData.new(results)
+  end
+
+  ##
+  # Search the site for all available results (max 100)
+  #
+  # This isn't so useful because it's quite slow
+  #
+  # Returns an array of up to 10 search(query) results
+  #
+  # examples:
+  #
+  # results = search_and_return_all_results('poker')
+  # results.first.items.size # == 10
+  #
+  # search_and_resturn_all_results('poker') do |results|
+  #   results.items.size # == 10  10 times
+  # end
+  #
+  # search_and_return_all_results(
+  #   '"California cult winery known for its Rhône"') do |results|
+  #   results.items.size # == 3  1 time
+  # end
+  #
+  # opts
+  #   see list here for valid options
+  #   http://code.google.com/apis/customsearch/v1/using_rest.html#query-params
+  def search_and_return_all_results(query, opts = {})
+    res = []
+    opts[:start] ||= 1
+    begin
+      results = GoogleCustomSearchApi.search(query, opts)
+      return res unless results.keys.include?('queries')
+      yield results if block_given?
+      res << results
+      if results.queries.keys.include?("nextPage")
+        opts[:start] = results.queries.nextPage.first.startIndex
+      else
+        opts[:start] = nil
+      end
+    end while opts[:start].nil? == false
+    return res
+  end
+
+  # Convenience wrapper for the response Hash.
+  # Converts keys to Strings. Crawls through all
+  # member data and converts any other Hashes it
+  # finds. Provides access to values through
+  # method calls, which will convert underscored
+  # to camel case.
+  #
+  # Usage:
+  #
+  #  rd = ResponseData.new("AlphaBeta" => 1,
+  #                        "Results" => {
+  #                          "Gamma" => 2,
+  #                          "delta" => [3, 4]})
+  #  puts rd.alpha_beta
+  #  => 1
+  #  puts rd.alpha_beta.results.gamma
+  #  => 2
+  #  puts rd.alpha_beta.results.delta
+  #  => [3, 4]
+  #
+  class ResponseData < Hash
+  private
+    def initialize(data={})
+      data.each_pair {|k,v| self[k.to_s] = deep_parse(v) }
+    end
+
+    def deep_parse(data)
+      case data
+      when Hash
+        self.class.new(data)
+      when Array
+        data.map {|v| deep_parse(v) }
+      else
+        data
+      end
+    end
+
+    def method_missing(*args)
+      name = args[0].to_s
+      return self[name] if has_key? name
+
+      camelname = name.split('_').map do |w|
+        "#{w[0,1].upcase}#{w[1..-1]}"
+      end.join("")
+
+      if has_key? camelname
+        self[camelname]
+      else
+        super *args
+      end
+    end
+  end
+
+
+  private
+
+  ##
+  # Build search request URL.
+  #
+  # see list here for valid options
+  # http://code.google.com/apis/customsearch/v1/using_rest.html#query-params
+  def url(query, opts = {})
+    opts[:q] = query
+    opts[:alt] ||= "json"
+    uri = Addressable::URI.new
+    uri.query_values = opts
+    begin
+      params.merge!(GOOGLE_SEARCH_PARAMS)
+    rescue NameError
+    end
+    "https://www.googleapis.com/customsearch/v1?" \
+      "key=#{opts[:api_key]}&cx=#{opts[:cx_key]}&#{uri.query}"
+  end
+
+  ##
+  # Query Google, and make sure it responds.
+  #
+  def fetch(url)
+    return HTTParty.get(url)
+  end
+end

data/lib/version.rb

@@ -0,0 +1,3 @@
+module GoogleCustomSearchApi
+  VERSION = "2.0.1"
+end

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: sk_google_custom_search_api
+version: !ruby/object:Gem::Version
+  version: 2.0.1
+platform: ruby
+authors:
+- Andrey Skuratovsky
+- Ben Wiseley
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-02-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ruby lib for Google's Custom Search Api.
+email:
+- skuratowsky@gmail.com
+- wiseleyb@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.rdoc
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- init.rb
+- lib/google_custom_search_api.rb
+- lib/version.rb
+homepage: http://github.com/askuratovsky/google_custom_search_api
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.3
+signing_key: 
+specification_version: 4
+summary: Ruby lib for Google's Custom Search Api.
+test_files: []