This is a small tutorial about using Partigi API in Ruby.

We are going to try to obtain, from the movies released in the last month, which of them have been rated with more than three stars by my friends.

These are the steps we are going to follow:

• Install the dependencies
• Register a new Partigi client application
• Perform the requests and filter the data

Install the dependencies

You need to install the gem oauth. Also, we are going to use REXML to parse the responses from the API.

Register a new Partigi client application

Visit http://www.partigi.com/applications and register a new application. As the requests we are going to perform doesn't require write permissions, you don't have to indicate a valid "Main Application URL" (use, for example, "http://localhost"). Leave "Callback URL" and "Support URL" fields empty.

Once you have created your application you'll see your consumer key and secret tokens. They are going to be used to sign the requests in the API

Perform the requests and filter the data

First of all we need to create a new consumer object, with the consumer key and secret values from our application.

   
require 'rubygems'   
require 'oauth'   
require 'rexml/document'      

consumer = OAuth::Consumer.new('xxxxx', 'yyyyyyyyyyy') 

After that we need a list of the movies that have been released this month in Spain. We can call the method items/index indicating as parameters that we want films which has been released in Spain from a month ago upto today.

We are going to parse the response with REXML, extracting from the field ptItem:id the identifier of each of the movies.

   
http = Net::HTTP.new('www.partigi.com')    
ids = []   
next_page = 1   
while next_page != nil     
  req = Net::HTTP::Get.new("/api/v1/items/index.atom?item_type=film&from_release_date_es=#{Date.today - 30}&locale=es&page=#{next_page}")     
  req.oauth!(http, consumer, nil)     
  res = http.request(req)      
  # store the id of each item     
  root = REXML::Document.new(res.body).root     
  root.each_element('//ptItem:id'){ |pt_item_id| ids << pt_item_id[0].to_s.to_i }     
  next_page = root.elements['partigi:next_page'][0]   
end 

Notice that we are requesting 10 items per page, as we are not indicating a per_page parameter. As this is a small number and there are more than 10 items, the element partigi:next_page indicates the value of the next page parameter that you have to use if you want to continue fetching items that fit the given conditions. That's why we are using a loop that performs requests while partigi:next_page is not nil.

The last step is to obtain the last reviews from my friends that has a good rating and match that list with the last released movies. Method reviews/friends is very powerful and has a lot of options, so it's perfect for our case. We are going to use it with the following options:

• user_id: the login or the identifier of our user. In our case "wadus"
• status: we want only those movies that have been watched, so we have to use the value "1" which represents that the item has been consumed. More information in the page of available status values
• from_rating: we want only those reviews with high rating, so we indicate that rating should be greater or equal than 4
• from_created_at: we want the reviews created in the last 30 days, because before of that is very improbable that our friends had watched the movie
• item_type: we only want reviews about movies, so we have to use the value "film"
• page: to iterate over the results

This is how the code should look like:

   
reviews = {}   
next_page = 1   
while next_page != nil     
  req = Net::HTTP::Get.new("/api/v1/reviews/friends.atom?user_id=wadus&status=1&from_rating=4&page=#{next_page}&from_created_at=#{Date.today - 30}&item_type=film")     
  req.oauth!(http, consumer, nil)     
  res = http.request(req)     
  root = REXML::Document.new(res.body).root     
  root.each_element('//entry'){ |e| reviews[e.elements['ptItem:id'][0].to_s.to_i] = e.elements['title'][0].to_s }      
  next_page = root.elements['partigi:next_page'][0]   
end 

Finally, we can intersect the reviewed movies identifiers with the premieres of this month and print the titles of the movies:

   puts "My friends favourite premieres are:"   (reviews.keys & ids).each do |item_id|     puts '  - ' + reviews[item_id]   end 

Conclusions and next steps

As you can see the API is very easy to use. There are some concepts about reviews, items, etc about which you can read more in the documentation.

If you are familiar with Ruby you should try our API wrapper: Partigirb.

Any questions or suggestions, feel free to contact us in our discussion group.