Truveo 1.0.0

data/bin/truveo_example.rb

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+#
+#  Created by Adam Beguelin on 2007-04-23.
+#  Copyright (c) 2007. All rights reserved.
+
+# simple example program using Truveo API
+
+require 'truveo'
+
+begin
+  
+  t = Truveo.new('5jtbaln8c0m6um6pp')  # <----- use your own appid here
+  
+  # get_videos(query='', results=10, start=0, showRelatedItems=0, 
+  #            tagResults=10, channelResults=10, categoryResults=10, userResults=10, 
+  #            showAdult=0)
+  
+  res = t.get_videos("funny")
+
+  puts "number of videos in index: " + res.total_results_available
+  puts "number of results returned from query: " + res.total_results_returned
+  
+  # video_set is an array of videos in result set
+  puts "top videos"
+  res.video_set.each{|v|
+    puts "\t #{v['id']}: \t #{v['title']}"
+  }
+
+  puts "query '#{res.query}'"
+
+  puts "video[0] metadata"
+  res.video_set[0].each_pair { |key,value| puts "#{key}:\n\t#{value}\n"}
+ 
+  puts "\nTags for Madonna:"
+  res = t.get_related_tags(query = 'madonna', results = 10, start = 0)
+  res.tag_set.each_pair { |tag, val| puts "#{tag}: #{val}" }
+  
+  puts "\nChannels for Madonna:"
+  res = t.get_related_channels(query = 'madonna', results = 10, start = 0)
+  res.channel_set.each_pair { |tag, val| puts "#{tag}: #{val}" }
+  
+  puts "\nCategories for Madonna:"
+  res = t.get_related_categories(query = 'madonna', results = 10, start = 0)
+  res.category_set.each_pair { |tag, val| puts "#{tag}: #{val}" }
+  
+  puts "\nUsers for Madonna:"
+  res = t.get_related_users(query = 'madonna', results = 10, start = 0)
+  res.user_set.each_pair { |tag, val| puts "#{tag}: #{val}" }
+  
+end

data/lib/truveo.rb

@@ -0,0 +1,498 @@
+#!/usr/bin/env ruby
+#
+#--
+#  Created by Adam Beguelin on 2007-03-27.
+#  Truveo Video Search Ruby API version 3.
+#  Copyright (c) 2007. AOL LLC.
+#  All rights reserved.
+#++
+
+$VERBOSE = 0
+
+require "net/http"
+require "uri"
+require "rexml/document"
+include REXML
+
+=begin rdoc
+TruveoResponse objects are returned from Truveo methods get_videos(), get_related_categories(), get_related_channels(),
+get_related_tags(), and get_related_users().  For example, the following line of code creates a new TruveoResponse object
+as the result of a call to Truveo.get_videos().
+
+  res = t.get_videos("funny")
+  
+The video_set attribute is an array of the videos returned by the TruveoResponse.get_videos call.
+
+  res.video_set.each{|v| ... } # iterates through the videos, each video is a hash of the metadata for that video
+  
+The channel_set is a hash of the channels that match the query.  The key is the name of the channel.  The value is
+the count of the number of videos in that channel that match the query.
+
+  res.channel_set.each_pair{|key,val| ... }
+
+The tag_set, cateogry_set, and user_set members are similar to the channel_set member described above. 
+
+The TruveoResponse also implements the <tt>each</tt> method which supports iteration through the all the videos that can be returned by the get_videos()
+query that created the TruveoResponse, up to 1,000 videos.
+
+  res = t.get_videos("funny")
+  res.each{|v| puts v['title']}
+    
+=end 
+
+class TruveoResponse
+  # Array of videos returned by the query. 
+  #   res.video_set # <-- array of the videos that matched query
+  attr :video_set, true                  
+  # Hash of channels and their related counts for your query
+  #   res.channel_set # <-- hash of the matching channels
+  attr :channel_set, true 
+  # Hash of categories and their related counts for your query
+  #   res.category_set # <-- hash of the matching categories
+  attr :category_set, true
+  # Hash of tags and their related counts for your query
+  #   res.tag_set # <-- hash of the matching tags
+  attr :tag_set, true
+  # Hash of users and their related counts for your query
+  #   res.user_set # <-- hash of the matching users
+  attr :user_set, true
+                                        
+  # String containing method, i.e., 'truveo.videos.getVideos'
+  #   res.method
+  attr :method, true
+  # String containing the query used to create this response object
+  #   res.query
+  attr :query, true
+  # String containging the sorter used to create this response
+  #   res.sortby
+  attr :sortby, true
+  
+  # String containing the query suggestion, if any
+  #   res.query_suggestion
+  attr :query_suggestion, true          
+  # String indicating the number of total results that matched the query
+  #   res.total_results_available
+  attr :total_results_available, true   
+  # String indicating the number of resutls returned in this result set.  For get_videos() the following should be true:  video_set.length == total_resutls_returned.to_i)
+  #   res.total_results_returned
+  attr :total_results_returned, true    
+  # String representing the position of the first Video in the entire set of matching videos.
+  #   res.first_result_position
+  attr :first_result_position, true     
+  # String containing the URL which will return an RSS feed for the set of videos returned in response to the submitted query.
+  #   res.rss_url
+  attr :rss_url, true                   
+  # String containing a human-readable title for the set of videos returned in response to the submitted request. 
+  # For example, this field would return a string such as "Most popular 'madonna' videos in Music on MTV" for the query 'madonna category:Music channel:MTV sort:mostPopular'.
+  #   res.video_set_title
+  attr :video_set_title, true           
+  
+  # String indicating the number of channel results returned 
+  #   res.channel_set.length == res.channel_results_returned.to_i # <-- true
+  attr :channel_results_returned, true  
+  # String indicating the number of category results returned 
+  #   res.category_set.length == res.cagegory_results_returned.to_i # <-- true
+  attr :category_results_returned, true 
+  # String indicating the number of tag results returned 
+  #   res.tag_set.length == res.tag_results_returned.to_i # <-- true
+  attr :tag_results_returned, true      
+  # String indicating the number of user results returned
+  #   res.user_set.length == res.user_results_returned.to_i # <-- true
+  attr :user_results_returned, true     
+      
+  # String indicating the integer code for the error if one occured    
+  attr :error_code, true                
+  # String containing text of error code if one occured.
+  attr :error_text, true                
+
+  # :stopdoc:  
+  
+  def initialize
+    @vidlist = Array.new
+  end
+  
+  attr :sphinxquery, true               # sqphinx query used
+  attr :sphinxfilters, true             # sqphinx filters used
+  
+  attr :params, true                    # parameters sent to truveo api call when TruveoResponse was created
+  attr :truveo, true                    # truveo object used to create the results, used for next_video
+
+  # copy over state for next_video call  
+  def next_self(res)
+    self.video_set = res.video_set
+    self.channel_set = res.channel_set
+    self.category_set = res.category_set
+    self.tag_set = res.tag_set
+    self.user_set = res.user_set
+
+    self.query_suggestion = res.query_suggestion
+    self.total_results_available = res.total_results_available
+    self.total_results_returned = res.total_results_returned
+    self.first_result_position = res.first_result_position
+    self.rss_url = res.rss_url
+    self.video_set_title = res.video_set_title
+
+    self.channel_results_returned = res.channel_results_returned
+    self.category_results_returned = res.category_results_returned
+    self.tag_results_returned = res.tag_results_returned
+    self.user_results_returned = res.user_results_returned
+
+    self.sphinxquery = res.sphinxquery
+    self.sphinxfilters = res.sphinxfilters
+  end
+
+# :startdoc:
+
+=begin rdoc
+
+Iterate through all the videos in the response.  Each video is a hash where the key is the metadata field, like title, 
+and the value is the actual metadata.  The videos are returned in whatever order was specified by the sorter, if any,
+used in the query that created the TruveoResponse object.
+
+The following goes through all the videos that match the query and prints the title.  If more than one thousand
+videos match the query, the each method will only iterate through the first thousand.
+
+  # create a Truveo object with my app id (apply for a free app id at http://developer.truveo.com/)
+  t = Truveo.new("appid")
+  res = t.get_videos("funny")
+  
+  # print lots of titles
+  res.each{|vid| puts vid['title']}
+
+Note that the each method will invoke another get_videos() method behind the scenes.  These calls will count against your
+daily limit.  This means iterating through a thousand results using <tt>each</tt> will result in 100 calls to <tt>get_videos()</tt>
+by default.
+
+=end rdoc
+
+  def each #  :yields: video
+    # if we've stored the results so fare
+    @vidlist.each { |v| yield v }
+    # get any more videos, storing the results for later calls to self.each
+    while v = next_video do
+      @vidlist << v
+      yield v
+    end
+  end
+  
+# :stopdoc:
+  
+  # get the next video, assumes a query has already been made, @video_set, @params, and @next_start have been set in get_videos_hash()
+  def next_video
+    return nil if video_set.nil?
+
+    # get more video if video_set has been depleted
+    if video_set.length  < 1
+      next_start = first_result_position.to_i + total_results_returned.to_i      
+      # check for valid start, we never return more than 1000 results
+      return nil if next_start >= 1000
+      # try to get another video_set
+      self.params[:start] = next_start.to_s
+      res = truveo.get_videos_hash(params)
+      next_self(res)
+      return nil if video_set.nil? || video_set.length < 1
+    end
+
+    video_set.shift
+  end
+# :startdoc:
+      
+end
+
+=begin rdoc
+
+The Truveo class implements a Ruby version of the Truveo API (see the {Truveo Developer Site}[http://developer.truveo.com] for details).  
+A Truveo object is initialized with an developer id, which is free and can be obtained from 
+the {Truveo Developer Site}[http://developer.truveo.com].  A developer id will allow you to call the Truveo API 
+up to 10,000 times per day.
+
+Currently user functions, like ratings, are not implemented in the Ruby API.
+
+=end
+
+class Truveo
+
+  @@sorter = %w(sort:mostPopular sort:mostPopularNow sort:mostPopularThisWeek sort:mostPopularThisMonth sort:vrank sort:mostRecent sort:mostRelevant sort:topFavorites sort:highestRated)
+  @@filter = %w(days_old: bitrate: type:free type:reg type:sub type:rent type:buy runtime: quality:poor quality:fair quality:good quality:excellent format:win format:real format:qt format:flash format:hi-q site: file_size:) # XXXX add these, should there be two types?  One that takes a comparison and one that doesn't?
+  @@modifier = %w(category: channel: tag: user: id: sim: title: description: artist: album: show: actor: director: writer: producer: distributor:)
+
+  # array of Truveo supported sorters such as <tt>sort:vrank</tt>
+  #
+  # Example:
+  #   Truveo.sorter.each{|s| puts s } # print all the sorters
+  #
+  def Truveo.sorter
+    @@sorter
+  end
+
+  # array of Truveo supported filters such as <tt>type:free</tt>
+  #
+  # Example:
+  #   Truveo.filter.each{|f| puts f } # print all the filters
+  #
+  def Truveo.filter
+    @@filter
+  end
+  
+  # array of Truveo supported modifiers such as <tt>tag:</tt>
+  # 
+  # Example:
+  #   Truveo.modifier.each{|m| puts m } # print all the modifiers
+  #
+  def Truveo.modifier
+    @@modifier
+  end
+  
+  # Create a new Truveo object for querying the Truveo video search engine.
+  # The appid is required.  For your free appid go to {My API Account}[http://developer.searchvideo.com/APIMyAccount.php]
+  # where you easily sign up for your own appid, allowing you up to 10,000 Truveo queries per day.
+  # :call-seq: new(appid)
+  #
+  # Example:
+  #     t = Truveo.new('my_appid')  # create a new Truveo object with your app_id
+  #
+  def initialize(appid, site = 'xml.searchvideo.com', path = "/apiv3?", port=80)
+    @appid = appid 
+    @site = site
+    @path = path
+    @port = port
+  end
+
+  # generic rest call
+  def rest(parms) # :nodoc:
+    call = String.new(@path)
+    parms.each{|k,v| call << "#{k}=#{v}&"}
+    call.chop! 
+    call = URI.escape(call)
+    api_site = Net::HTTP.new(@site,@port)
+    # puts call
+    xml = REXML::Document.new(body = api_site.request_get(call).body)
+    return xml
+  rescue REXML::ParseException => e
+    puts "rest parse rescue: " # + e.to_s
+    puts "zzz>>> #{body}<<<zzz"
+    return nil
+  rescue Exception => e
+    puts "rest rescue: " + e.to_s.split("\n")[0]
+    pp e
+    puts "site, path, parms: #{@site}, #{@path}, :#{call}:"
+    return nil
+  end
+
+  # return the error as hash or nil if no error
+  def api_error(xml) #:nodoc:
+    if xml.nil?
+      res = TruveoResponse.new
+      res.error_code = '69'
+      res.error_text = 'bad xml'
+      return res
+    end
+    #<?xml version='1.0' encoding='UTF-8'?><Response><Error Code='14'>Access Denied: invalid appid.</Error></Response>
+    if elt = xml.elements['//Error']
+      res = TruveoResponse.new
+      res.error_code = elt.attributes["Code"]
+      res.error_text = elt.text
+      return res
+    end
+    nil
+  end
+  
+  # convert an xml element to a string
+  def elt_text(xml,s) #:nodoc:
+    if elt = xml.elements[s]
+      return elt.text
+    end
+    return nil
+  end
+  
+  # convert xml to hash  
+  def xml_to_hash(xml) #:nodoc:
+    h = Hash.new
+    xml.elements.each{|e| h[e.name] = e.text }
+    h 
+  end
+  
+  # performs the specified query and returns the results in the form of a TruveoResponse object.
+  # query:: this is the search query to run.  See {Building Search Queries}[http://developer.truveo.com/SearchQueryOverview.php] for details.
+  # results:: number of results to return, the default is 10, the maximum is 50.
+  # start:: where to start the result set being returned,  defaults to 0.  Can be used to page through results.
+  # showRelatedItems:: indicates if the tag set, category set, and user set should be returned.  Values should be 0 or 1, the default is 0.
+  # tagResults:: number of tags requested in the tag_set response.  
+  # channelResults:: number of channels requested in the channel_set response.
+  # categoryResults:: number of categories requested in the category_set response.
+  # userResults:: number of users requested in the user_set response.
+  # showAdult:: flag indicating whether or not adult content should be included in the result set.
+  # All of the result sizes above are maximums.  A query may return fewer than the requested number of results if the requested  
+  # number of results don't match.
+  #       
+  # If the query string is empty, then the top results are returned in vrank order.
+  #    
+  # If showRelatedItems is zero, the response will only includea a video_set.  The tag_set, channel_set, category_set, and user_set
+  # parameters will be left out.
+  
+  def get_videos(query='', results=10, start=0, showRelatedItems=0, tagResults=10, channelResults=10, categoryResults=10, userResults=10, showAdult=0)
+    params = Hash.new
+    params[:method] = 'truveo.videos.getVideos'
+    params[:query] = query    
+    params[:showRelatedItems] = showRelatedItems
+    params[:tagResults] = tagResults
+    params[:channelResults] = channelResults
+    params[:categoryResults] = categoryResults
+    params[:userResults] = userResults
+    params[:showAdult] = showAdult
+    params[:appid]  = @appid              
+    params[:results] = results
+    params[:start] = start
+
+    get_videos_hash(params)
+  
+  end
+  
+  def get_videos_hash(params) #:nodoc:
+
+
+    xml = rest(params)
+    
+    res = TruveoResponse.new
+    
+    # save params for next_video call
+    res.params = params
+    res.truveo = self
+    
+    # check for error codes
+    err = api_error(xml)
+    puts "get_videos(#{params[:query]}) returned error: #{err.error_code} #{err.error_text}" if $VERBOSE && !err.nil?
+    return err if !err.nil?
+
+    res.method = elt_text(xml,'//Response/method')
+    res.query = elt_text(xml,'//Response/query')
+    res.sortby = elt_text(xml,'//Response/sortby')
+    res.query_suggestion = elt_text(xml,'//Response/querySuggestion')   
+    
+    res.total_results_available = elt_text(xml, '//VideoSet/totalResultsAvailable')
+    res.total_results_returned = elt_text(xml, '//VideoSet/totalResultsReturned')    
+    res.first_result_position = elt_text(xml, '//VideoSet/firstResultPosition')        
+
+    res.rss_url = elt_text(xml, '//rssUrl')        
+    res.video_set_title = elt_text(xml, '//VideoSet/title')        
+    
+    res.sphinxquery = elt_text(xml,'//Response/sphinxquery')
+    res.sphinxfilters = elt_text(xml,'//Response/sphinxfilters')    
+         
+    # store the video set
+    res.video_set = Array.new
+    @video_set = Array.new
+    xml.elements.each('//Video') {|v| 
+      res.video_set << (tvid = xml_to_hash(v))
+      @video_set << tvid      
+    }
+    
+    @next_start = res.total_results_returned.to_i + res.first_result_position.to_i
+    
+    if res.total_results_returned.to_i != res.video_set.length
+      puts "Warning: results mismatch: res.total_results_returned (#{res.total_results_returned}) != res.video_set.length (#{res.video_set.length})"
+      # puts xml.to_s
+    end
+    
+    # the channel_set is a hash, one entry per channel.  the key is the channel name, the value is the count.
+    res.channel_results_returned = elt_text(xml, '//ChannelSet/totalResultsReturned')        
+    res.channel_set = set_hash(xml,'//Channel')
+    
+    res.tag_results_returned = elt_text(xml, '//TagSet/totalResultsReturned')            
+    res.tag_set = set_hash(xml,'//Tag')
+    
+    res.category_results_returned = elt_text(xml, '//CategorySet/totalResultsReturned')            
+    res.category_set = set_hash(xml, '//Category')
+    
+    res.user_results_returned = elt_text(xml, '//UserSet/totalResultsReturned')            
+    res.user_set = set_hash(xml, '//User')
+    
+    res
+    
+  end
+  
+  # return the hash for the given set (category, channel, tag, or user)
+  def set_hash(xml,s) #:nodoc:
+    h = Hash.new
+    xml.elements.each(s){|v| h[v.elements['name'].text] = v.elements['count'].text.to_i}   
+    h
+  end
+  
+
+  # generic get_related for each of the get_related type calls
+  def get_related(type='Tags', query='', results=10, start=0) #:nodoc:
+
+    params = Hash.new
+    params[:method] = "truveo.videos.getRelated#{type}"
+    params[:query] = query    
+    params[:appid]  = @appid              
+    params[:results] = results
+    params[:start] = start    
+
+    xml = rest(params)
+    
+    res = TruveoResponse.new
+    
+    # check for error codes
+    err = api_error(xml)
+    return err if !err.nil?
+
+    res.method = elt_text(xml,'//Response/method')
+    res.query = elt_text(xml,'//Response/query')
+    res.sortby = elt_text(xml,'//Response/sortby')
+    res.query_suggestion = elt_text(xml,'//Response/querySuggestion')   
+    
+    res.sphinxquery = elt_text(xml,'//Response/sphinxquery')
+    res.sphinxfilters = elt_text(xml,'//Response/sphinxfilters')
+    
+    res.total_results_returned = elt_text(xml, '//totalResultsReturned')    
+    res.first_result_position = elt_text(xml, '//firstResultPosition')       
+     
+    res.send("#{singularize(type).downcase}_set=", set_hash(xml,"//#{singularize(type)}"))
+    
+    res
+    
+  end
+
+  # Return a hash of the tags and counts related to the query.
+  #  
+  # The results and start parameters are used for paging through the result set.
+  #
+  # Example:
+  #   t = Truveo.new('appid_goes_here')
+  #   res = t.get_related_tags('funny')
+  #   res.tag_set.each_pair{|k,v| puts "tag: #{k} count: #{v}" }
+  def get_related_tags(query='', results=10, start=0)
+    get_related('Tags', query, results, start)
+  end
+  
+  # Return a hash of the channels and counts related to the query.
+  #
+  # The results and start parameters are used for paging through the result set.
+  def get_related_channels(query='', results=10, start=0)
+    get_related('Channels',query, results, start)
+  end
+  
+  # Return a hash of the users and counts related to the query.
+  #
+  # The results and start parameters are used for paging through the result set.
+  def get_related_users(query='', results=10, start=0)
+    get_related('Users',query, results, start)
+  end
+  
+  # Return a hash of the categories and counts related to the query.
+  #
+  # The results and start parameters are used for paging through the result set.
+  def get_related_categories(query='', results=10, start=0)
+    get_related('Categories',query, results, start)
+  end
+
+  def singularize(s) #:nodoc:
+    return s.chop if s =~ /(Tags|Channels|Users)/
+    return 'Category' if s =~ /Categories/
+    return s
+  end
+  
+  private :singularize
+  
+end

data/test/test_api.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+#
+#  Created by Adam Beguelin on 2007-06-27.
+#  Copyright (c) 2007. All rights reserved.
+# 
+#  a few interesting tests just to sanity check things
+#  please add your appid to the Truveo.new call in setup()
+
+require 'test/unit'
+require 'truveo'
+
+class TestTruveo < Test::Unit::TestCase
+
+  def setup
+    @t = Truveo.new('5jtbaln8c0m6um6pp')  # <----- use your own appid here
+    # use the empty query with showRealtedItems on
+    @res = @t.get_videos(query='', results=50, start=0, showRelatedItems=1, tagResults=50, channelResults=50, categoryResults=50, userResults=50, showAdult=1)
+  end
+
+  def test_tag_hash
+    assert_equal('50', @res.tag_results_returned)
+    @res.tag_set.each{|k,v| assert(v>0, "Tag count < 1 for tag #{k} count #{v}")}
+  end
+  
+  def test_user_hash
+    assert_equal('50', @res.user_results_returned)
+    @res.user_set.each{|k,v| assert(v>0, "User count < 1 for user #{k} count #{v}")}
+  end
+  
+  def test_video_hash
+    assert_not_nil(@res.video_set)
+    assert_equal(50, @res.total_results_returned.to_i)
+    assert_equal(50, @res.video_set.length)
+    @res.video_set.each{|e| assert_not_nil(@res.video_set[0]['title']) }
+    @res.video_set.each{|e| assert_not_nil(@res.video_set[0]['description']) }
+    # vrank should be descending
+    rank = 1.0
+    @res.video_set.each{|e| assert(e['vRank'].to_f <= rank); rank = e['vRank'].to_f }
+  end
+  
+  def test_sorters
+    assert_equal(9,Truveo.sorter.size)
+    assert_equal(19,Truveo.filter.size)
+    assert_equal(16,Truveo.modifier.size)
+  end
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.4
+specification_version: 1
+name: Truveo
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+date: 2007-07-09 00:00:00 -07:00
+summary: Ruby interface to Truveo
+require_paths: 
+- lib
+email: adam @nospam@ truveo.com
+homepage: http://developer.truveo.com
+rubyforge_project: 
+description: 
+autorequire: truveo
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Adam Beguelin
+files: 
+- lib/truveo.rb
+- bin/truveo_example.rb
+- test/test_api.rb
+test_files: 
+- test/test_api.rb
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+