RBoss Gem – Yahoo! Boss Search

Description

A handy gem to make using the Yahoo Boss API nice and easy in ruby.

Yahoo! Boss Search official site

Yahoo! Boss Search API

Add feature requests and bugs here: http://eshopworks.lighthouseapp.com/projects/15732-rboss/overview

Features

Search

• Images
• News
• Web

Also spelling suggestions

Return results as:

• JSON string
• XML string
• Plain old ruby objects (POROs)

Install

  gem sources --add http://gems.github.com/ 
  gem install eshopworks-rboss

Get a yahoo boss api-key: http://developer.yahoo.com/wsregapp

Usage

  require 'rubygems'
  require 'boss'
  
  api = Boss::Api.new('boss-api-key-got-from-yahoo')
  
  #Search defaults to web search with following defaults
  # count = 10  
  # lang = eng
  # Results by default are ruby objects
  api.search('monkeys')
  
  #Delimit multiple search terms with commas
  api.search('dancing,monkeys')

  #Delimit Exact search with quotation marks
  api.search('"dancing monkeys"')
    
  #Use '-' for minus terms
  api.search('monkeys -dancing')

  #Search images, spelling, news and web
  api.search_images('monkeys')
  api.search_spelling('monkeys')
  api.search_news('monkeys')
  api.search_web('monkeys')

  #By default returns ruby object results
  results = api.search_web('monkeys')
  results.each { |web| puts web.title }

  #Configure search with hash
  xml = api.search_spelling('monkeys', :format => 'xml', :count => 5)

  #Configure search with block
  xml = api.search_spelling('monkeys') do |config|
    config.format = 'xml'
    config.count = 5
  end
  
  #Access general search result information
  results = api.search('monkeys', :count => 5)
  puts results.totalhits

Global Search Options (applies to news/images/web search)

  api.search('monkeys') do |config|
    config.start = 1
    config.count = 10
    config.lang = 'en'
    config.region = 'us'
    config.format = 'xml'
    config.callback = ''     #name of the callback function to wrap the result (valid only if format is set to "json")
    config.sites = 'abc.com,cnn.com'
  end

Global Search Results data (applies to news/images/web search results)

  results = api.search('monkeys', :count => 1)
  puts results.deephits      #approximate count that includes duplicates
  puts results.totalhits     #approximate count that excludes duplicates
  puts results.responsecode  #response code return by Yahoo webservice
  puts results.start         #the first numeric result to display
  puts results.count         #Indicates how many results to show per page
  puts results.nextpage      #link to what would be the next page of search results

Web Search Result

  #We filter here to exclude certain types of content
  results = api.search_web('monkeys', :filter => '-porn')
  results.each do |web|
    puts web.abstract
    puts web.date
    puts web.dispurl  #URL of document matching the query result.
    puts web.clickurl #navigation URL that leads to the target URL
    puts web.size     #document’s size in bytes
    puts web.title
    puts web.url
  end

News Search Result

  #We retrieve documents by age (possible options: [1-30]d ) 
  results = api.search_news('monkeys', :age => '7d')
  results.each do |news|
    puts news.abstract
    puts news.clickurl
    puts news.title
    puts news.language
    puts news.date
    puts news.time
    puts news.source
    puts news.sourceurl
    puts news.url
  end

Image Search Result

  #Add constraint on dimension (possible options: 'small', 'medium', 'large', 'wallpaper')
  #Activate the Offensive Content Reduction filter
  results = api.search_images('monkeys', :dimensions => 'small', :filter => 'true')
  results.each do |image|

    puts image.abstract
    puts image.clickurl
    puts image.filename
    puts image.size
    puts image.format
    puts image.height
    puts image.date
    puts image.mimetype
    puts image.refererclickurl
    puts image.refererurl
    puts image.title
    puts image.url
    puts image.width
    puts image.thumbnail_height
    puts image.thumbnail_url
    puts image.thumbnail_width
  end

Spell Search Result

  results = api.search_spelling('monkeys')
  results.each do |spell|
    puts spell.suggestion
  end