| Path: | README |
| Last Update: | Mon Jul 09 06:43:42 -0700 2007 |
The Ruby API allows developers to access the Truveo search engine using programs written in Ruby. (This is a pure Ruby implementation, not tied to Ruby on Rails.) Using this API, developers can build a variety of custom applications that feature video search results and functionality. The Truveo Ruby API is designed to work with version 1.8 of Ruby.
To gain access to the Truveo Ruby API, you must first set up an API account. To create a new API account or view your existing API account, please consult the My API Account page. When you first create a new API account, you will be assigned a unique key, or Application ID. This Application ID is a string that uniquely identifies your organization‘s application and authorizes it to access the Truveo video search index.
To start using the API in your Ruby application, you will first need to include the `truveo.rb` file into your application. To do this, first download the latest version of the truveo.rb file and place the file in the same directory as your Ruby program (or in a directory that is in your current include path). You then add the require ‘truveo‘ line to the beginning of your Ruby program. This will give you access to two Ruby classes, Truveo and TruveoResponse. The Truveo class provides an interface to the video search methods while the TruveoResponse class is a container that is returned from calls to the Truveo search methods.
Here‘s a simple example program. This program will create a Truveo object using your application id. It then calls the get_videos() method to find videos that match the query funny. The get_videos() call returns a TruveoResponse object. One member of the TruveoResponse object is the video_set array.
require 'truveo'
t = Truveo.new("app_id") # <--- add your appid here
res = t.get_videos("funny")
res.video_set.each{|v| puts v['title'] }
The output from this program will vary because our search index is constantly changing, but the output will look something like this:
Cat Attacks Toy Cat
Baby Eats A Lemon
Hot Intern Will Get You Fired
Caged Monkey vs. Dog
100 Ton Bomb
Finger Licking Kitty
Daily Show: Steve Carell
Biggins Ball Strikes Back
Station Wagon Car Jump
The Impotence of Proofreading
The first parameter to the get_videos() call is the query string. The syntax of the query string is documented in the Building Search Queries section, but essentially you include query terms, filters, and sorters as part of the query string. There are other parameters to get_videos() which control the number and type of results to return. See the rest of the documentation for Truveo and TruveoReponse classes.
The TruveoResponse object is returned from the get_videos() call (and a few other calls). It is a container normally chock full of information returned from your query. As shown above, the video_set array contains an array of videos in the order returned by Truveo. Each element of the `video_set` is a `Hash` of all the metadata we have for that video. As shown above, v[‘title’] is the title of the video. You can access all the metadata fields just like you access any Ruby hash. For example, you can print all the metadata fields and their corresponding values like this:
v.each_pair{|k,v| puts "Field: #{k} \t Value: #{v}"}
By default the get_videos() call returns up to ten results in the video_set array, as a member of the TruveoResponse object. If you want to retrieve the next set of results, you can pass in a start parameter, indicating which result you would like to start with, allowing you to page through the results 10 items at a time up. The get_videos() will return up to the first 1,000 results that match a query.
The TruveoResponse object also supports an `each` method, allowing you to iterate through the results the Ruby way. For instance, the following line of code will print out all the titles for all the videos that match the query, up to 1,000 results if the total number of results is over 1,000.
res.each{|v| puts v['title']}
The TruveoResponse object also has a number of other attributes described in the documentation for the TruveoResponse class.
See bin/truveo_example.rb file if you installed from the gem.