= 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 all sites

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

== Retrieving a single site

  require 'muddyit_fu'
  muddyit = Muddyit.new('muddyit.yml')
  puts muddyit.sites.find('a0ret4').label

== Categorisation request

  require 'muddyit_fu'
  muddyit = Muddyit.new('muddyit.yml')
  site = muddyit.sites.first
  site.pages.create({: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.find(:all) do |page|
    puts page.title
    page.entities.each do |entity|
      puts entity.uri
    end
  end

== View all pages containing 'Gordon Brown'

  require 'muddyit_fu'
  muddyit = Muddyit.new('muddyit.yml')
  site = muddyit.sites.find(:all).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.find(:all).first
  site.entities.find_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.find(:all).first
  page = site.pages.find(:all, :uri => 'http://news.bbc.co.uk/1/hi/uk_politics/7878418.stm').first
  puts "Our page : #{page.title}\n\n"
  page.related_content.each do |results|
    puts "#{results[:page].title} #{results[:count]}"
  end

== Obtaining oauth access credentials

See http://gist.github.com/178993

== Contact

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