= muddyit_fu

== Installation

  sudo gem install monkeyhelper-muddyit-fu --source http://gems.github.com

== Getting started

muddy.it uses oauth to manage it's api access.  To access the muddy.it data
programmatically you will need to register an application.  Login and visit :

http://www.muddy.it/oauth_clients/

You can register an application here, a callback URI isn't required.

The 'consumer token' and 'consumer secret' are used to generate a token for
accessing muddy.it.  For further details and an example of how to programatically
generate a new access token for muddy.it see here :

http://stakeventures.com/articles/2008/02/23/developing-oauth-clients-in-ruby

See the 'Authorising clients using irb' section for a sample irb session.

These details are then used to provide access to the service.  The credentials
can be stored in a yml file, an example of which is provided below.

== Example muddyit.yml

  ---
  consumer_key: "YOUR_CONSUMER_KEY"
  consumer_secret: "YOUR_CONSUMER_SECRET"
  access_token: "YOUR_ACCESS_TOKEN"
  access_token_secret: "YOUR_ACCESS_TOKEN_SECRET"

== Retrieving a site

  require 'muddyit_fu'
  muddyit = Muddyit.new('muddyit.yml')
  muddyit.sites.each do |site|
    puts "#{site.label} : #{site.token}"
  end

== Categorisation request

  require 'muddyit_fu'
  muddyit = Muddyit.new('muddyit.yml')
  site = muddyit.sites.first
  site.pages.categorise({:identifier => 'http://news.bbc.co.uk/1/hi/uk_politics/8011321.stm'}, {:minium_confidence => 0.2})

== View categorised pages

  require 'muddyit_fu'
  muddyit =  Muddyit.new(:consumer_key => 'aaa',
                         :consumer_secret => 'bbb',
                         :access_token => 'ccc',
                         :access_token_secret => 'ddd')
  site = muddyit.sites.first
  site.pages.index do |page|
    puts page.title
    page.results.each do |result|
      puts result.uri
    end
  end

== View all pages containing 'Gordon Brown'

  require 'muddyit_fu'
  muddyit = Muddyit.new('muddyit.yml')
  site = muddyit.sites.first
  site.pages.find_by_entity('http://dbpedia.org/resource/Gordon_Brown') do |page|
    puts page.identifier
  end

== Find related entities for 'Gordon Brown'

  require 'muddyit_fu'
  muddyit = Muddyit.new('muddyit.yml')
  site = muddyit.sites.first
  site.entities.related('http://dbpedia.org/resource/Gordon_Brown').each do |entity|
    puts "#{entity.uri} : #{entity.confidence}"
  end

== Find related content for : http://news.bbc.co.uk/1/hi/uk_politics/7878418.stm

  require 'muddyit_fu'
  muddyit = Muddyit.new('muddyit.yml')
  site = muddyit.sites.first
  page = site.pages.find('http://news.bbc.co.uk/1/hi/uk_politics/7878418.stm')
  puts "Our page : #{page.title}\n\n"
  page.related_content.each do |results|
    puts "#{results[:page].title} #{results[:count]}"
  end

== Authorising clients using irb

  robl@fry:~/$ irb
  irb(main):002:0> require 'rubygems'
  => true
  irb(main):003:0> require 'oauth'
  => true
  irb(main):004:0> require 'oauth/consumer'
  => false
  irb(main):005:0> @consumer=OAuth::Consumer.new "yourtoken", "yoursecret", {:site => 'http://www.muddy.it' }
  => #<OAuth::Consumer:0xb7683b7c @key="yourtoken", @secret="yoursecret", @options={:oauth_version=>"1.0",
  :signature_method=>"HMAC-SHA1", :request_token_path=>"/oauth/request_token",
  :site=>"http://www.muddy.it", :scheme=>:header,
  :authorize_path=>"/oauth/authorize", :access_token_path=>"/oauth/access_token",
  :http_method=>:post}>
  irb(main):006:0> @request_token=@consumer.get_request_token
  => #<OAuth::RequestToken:0xb76778e0 @consumer=#<OAuth::Consumer:0xb7683b7c @key="tokenkey",
  @http=#<Net::HTTP www.muddy.it:80 open=false>, @http_method=:post,
  @secret="tokensecret", @options={:oauth_version=>"1.0", :signature_method=>"HMAC-SHA1",
  :request_token_path=>"/oauth/request_token", :site=>"http://www.muddy.it",
  :scheme=>:header, :authorize_path=>"/oauth/authorize", :access_token_path=>"/oauth/access_token",
  :http_method=>:post}>, @token="tokenkey", @secret="tokensecret">
  irb(main):007:0> @request_token.authorize_url
  => "http://www.muddy.it/oauth/authorize?oauth_token=tokenkey"

To authorise the application, visit the URL, check the 'authorize access' box and
save.  The request token can now be exchanged for an access token :

  irb(main):008:0> @access_token=@request_token.get_access_token
  => #<OAuth::AccessToken:0xb7667c10 @consumer=#<OAuth::Consumer:0xb7683b7c @key="accesstoken_key",
  @http=#<Net::HTTP www.muddy.it:80 open=false>, @http_method=:post,
  @secret="accesstoken_secret", @options={:oauth_version=>"1.0",
  :signature_method=>"HMAC-SHA1", :request_token_path=>"/oauth/request_token",
  :site=>"http://www.muddy.it", :scheme=>:header, :authorize_path=>"/oauth/authorize",
  :access_token_path=>"/oauth/access_token", :http_method=>:post}>, @token="accesstoken",
  @secret="accesstoken_secret">

This token can also be used to access the service :

  irb(main):016:0> res = @access_token.get "/sites.json"
  => #<Net::HTTPOK 200 OK readbody=true>
  irb(main):017:0> res.body
  ....

The access token credentials to be used with muddyit_fu are :

  irb(main):011:0> @access_token.token
  => "sometoken"
  irb(main):012:0> @access_token.secret
  => "somesecret"

== Contact

  Author: Rob Lee
  Email: robl [at] monkeyhelper.com
  Main Repository: http://github.com/monkeyhelper/muddyit_fu/tree/master