linkscape 0.2.6

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009-2010 SEOmoz
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,228 @@
+= Linkscape Gem
+
+This is the official Gem to interact with the SEOmoz API.  For more information, please check out the {API page on SEOmoz}[http://www.seomoz.org/api] and the {SEOmoz API Wiki}[http://apiwiki.seomoz.org]
+
+== Usage
+
+First you must secure an accessID and secret key from SEOmoz.  See the {API page}[http://www.seomoz.org/api] for details.  Once you have your credentials, create an instance of your client:
+
+  client = Linkscape::Client.new(:accessID => "my_access_id", :secret => "$secretp@$$w0rd")
+  
+Then you should be able to make one of the predefined API calls
+
+  response = client.urlMetrics("http://gemcutter.org", :cols => :all)
+  
+At this point <tt>response</tt> should be a Linkscape::Response object.  You can get at its data by calling
+
+  response.data
+  
+This returns a Linkscape::Response::ResponseData object, which is the container class for the response data.
+
+For the urlMetrics and mozrank call, you can request specific data points, like:
+
+  response.data[:url]
+  response.data[:external_links]
+  response.data[:page_authority]
+  
+For all other calls, such as anchor text, top pages and link data sets, <tt>data</tt> is an array of ResponseData objects, with each one keyed on their respective types.  For example:
+
+ response.data.first[:source][:mozrank]               # :source just for topPages and link calls
+ response.data.first[:target][:page_authority]        # :target just for link calls
+ response.data.first[:link][:text]                    # :link just for link calls
+ response.data.first[:anchor][:text]                  # :anchor just for link anchorMetrics calls
+
+== Available API Calls
+
+The Linkscape::Client object can make the following API calls:
+
+=== mozRank
+
+Returns the mozRank of the supplied URI.
+
+  client.mozRank(uri)
+
+=== urlMetrics
+
+Returns metrics about the supplied URI.
+
+  client.urlMetrics(uri, :cols => :all)
+
+This call accepts the following options:
+
+* <tt>:cols</tt> - An array of columns (see below) to return in the response, or the <tt>:all</tt> keyword, which returns all columns.
+
+=== topLinks
+
+Returns a list of topLinks to the supplied URI and :type.
+
+  client.topLinks(uri, :page, :urlcols => :all, :linkcols => :all, :limit => 3))
+
+The 2nd parameter of this method, <tt>:type</tt> can be either <tt>:page</tt>, <tt>:subdomain</tt> <tt>:domain</tt>.  It specifies the type of links you are requesting (links to the supplied URI, Root Domain or the Subdomain of the supplied URI).
+
+This call accepts the following options:
+
+* <tt>:sourcecols</tt> - An array of data columns (see below) that should be returned for the link source.
+* <tt>:targetcols</tt> - An array of data columns (see below) that should be returned for the link target.
+* <tt>:linkcols</tt> - An array of data columns (see below) that should be returned for the link itself.
+* <tt>:limit</tt> - The # of links (limit) you would like to return.
+* <tt>:offset</tt> = The number of records to offset before returning the 1st record of results.
+
+=== allLinks
+
+Returns all the links to a specific URI and :type.
+
+  client.allLinks(uri, :page, :urlcols => [:title, :url, :page_authority, :domain_authority], :linkcols => :all, :filters => :external, :limit => 3)
+
+The 2nd parameter of this method, <tt>:type</tt> can be either <tt>:page</tt>, <tt>:subdomain</tt> <tt>:domain</tt>.  It specifies the type of links you are requesting (links to the supplied URI, Root Domain or the Subdomain of the supplied URI).
+
+This call accepts the following options:
+
+* <tt>:sourcecols</tt> - An array of data columns (see below) that should be returned for the link source.
+* <tt>:targetcols</tt> - An array of data columns (see below) that should be returned for the link target.
+* <tt>:linkcols</tt> - An array of data columns (see below) that should be returned for the link itself.
+* <tt>:filters</tt> - A String, Array or Symbol of filters (see below) that should be applied to the list of links.  NOTE: Multiple filters may be combined, i.e. <tt>:filters => [:internal,:follow,:redir301]</tt>.
+* <tt>:limit</tt> - The # of links (limit) you would like to return.
+* <tt>:offset</tt> = The number of records to offset before returning the 1st record of results.
+* <tt>:scope</tt> - A symbol representing the 'scope' of the links (see below).
+
+=== topPages
+
+Returns a list of the top pages on the URI in question
+
+  client.topPages(uri, :page, :cols => :all, :limit => 3)
+
+The 2nd parameter of this method, <tt>:type</tt> can be either <tt>:page</tt>, <tt>:subdomain</tt> <tt>:domain</tt>.  It specifies the type of top pages you are requesting (top pages on the supplied URI, Root Domain or the Subdomain of the supplied URI).
+
+This call accepts the following options:
+
+* <tt>:cols</tt> - An array of data columns (see below) that should be returned for the link source.
+* <tt>:limit</tt> - The # of links (limit) you would like to return.
+* <tt>:offset</tt> = The number of records to offset before returning the 1st record of results.
+
+=== anchorMetrics
+
+Returns anchor text metrics about the URI in question
+
+  client.anchorMetrics(uri, :cols => :all, :scope => "page_to_domain", :filters => :external, :sort => :domains_linking_page, :limit => 3, :scope => :phrase_to_page)
+
+This call accepts the following options: 
+
+* <tt>:cols</tt> - An array of data columns (see below) that should be returned.
+* <tt>:scope</tt> - A symbol representing the 'scope' of the anchor text data (see below).
+* <tt>:sort</tt> - A symbol representing the 'sort order' of the anchor text data (see below).
+* <tt>:filters</tt> - A symbol representing the 'filter' of the anchor text data (see below).  NOTE: Only <tt>:external</tt> or <tt>internal</tt> filters may be used, separately.
+* <tt>:limit</tt> - The # of links (limit) you would like to return.
+* <tt>:offset</tt> = The number of records to offset before returning the 1st record of results.
+
+== Requesting Data on Multiple URLs
+
+For the API calls which support it, you may request data on multiple URLs by passing an
+array of URLs to the API call.
+
+  urls = ["http://www.seomoz.org/blog/21-tactics-to-increase-blog-traffic", "http://www.seomoz.org/tools"]
+  response = client.urlMetrics(urls, :cols => :all)
+  response.data.first[:url]
+  >> "http://www.seomoz.org/blog/21-tactics-to-increase-blog-traffic"
+  response.data.first[:external_links]
+  >> 436
+
+== Available Response Columns
+
+Depending on the type of data point return, you may access certain data points inside the ResponseData object.
+
+=== Source/Target/URL Metrics
+
+* <tt>:status</tt>
+* <tt>:fq_domain_mozrank</tt>
+* <tt>:pl_domain_links</tt>
+* <tt>:pl_domain_external_links</tt>
+* <tt>:fq_domain</tt>
+* <tt>:fq_domain_moztrust</tt>
+* <tt>:fq_domain_pl_domains_linking</tt>
+* <tt>:pl_domain</tt>
+* <tt>:url</tt>
+* <tt>:page_authority_raw</tt>
+* <tt>:pl_domain_external_mozrank_sum_raw</tt>
+* <tt>:links</tt>
+* <tt>:external_mozrank</tt>
+* <tt>:pl_domain_mozrank</tt>
+* <tt>:juice_links</tt>
+* <tt>:title</tt>
+* <tt>:fq_domains_linking</tt>
+* <tt>:page_authority</tt>
+* <tt>:fq_domain_external_mozrank_sum_raw</tt>
+* <tt>:pl_domain_moztrust</tt>
+* <tt>:fq_domain_external_links</tt>
+* <tt>:domain_authority_raw</tt>
+* <tt>:canonical_url</tt>
+* <tt>:pl_domain_mozrank_sum_raw</tt>
+* <tt>:fq_domain_links</tt>
+* <tt>:all</tt>
+* <tt>:mozrank</tt>
+* <tt>:pl_domain_pl_domains_linking</tt>
+* <tt>:external_links</tt>
+* <tt>:fq_domain_fq_domains_linking</tt>
+* <tt>:pl_domains_linking</tt>
+* <tt>:domain_authority</tt>
+* <tt>:fq_domain_mozrank_sum_raw</tt>
+* <tt>:moztrust</tt>
+
+=== Link Metrics
+
+* <tt>:text</tt>
+* <tt>:mozrank</tt> (passed)
+
+=== Anchor Text Metrics
+
+* <tt>:flags</tt>
+* <tt>:internal_mozrank</tt>
+* <tt>:internal_pages_linking</tt>
+* <tt>:external_subdomains_linking</tt>
+* <tt>:external_mozrank</tt>
+* <tt>:text</tt>
+* <tt>:internal_subdomains_linking</tt>
+* <tt>:external_domains_linking</tt>
+* <tt>:all</tt>
+* <tt>:record_id</tt>
+* <tt>:external_pages_linking</tt>
+
+== Available Filters
+
+Links may be filtered by any of the following.  Anchor text may o
+
+* <tt>:internal</tt>
+* <tt>:external</tt>
+* <tt>:redir301</tt>
+* <tt>:follow</tt>
+* <tt>:nofollow</tt>
+
+== Anchor Text Scope
+
+When requesting anchor text data, the following scopes may be used.
+
+* <tt>:phrase_to_page</tt>
+* <tt>:phrase_to_subdomain</tt>
+* <tt>:phrase_to_domain</tt>
+* <tt>:term_to_page</tt>
+* <tt>:term_to_subdomain</tt>
+* <tt>:term_to_domain</tt>
+
+== Link Scope
+
+When requesting links, the following scope may be used
+
+* <tt>:page_to_page</tt>
+* <tt>:page_to_subdomain</tt>
+* <tt>:page_to_domain</tt>
+* <tt>:domain_to_page</tt>
+* <tt>:domain_to_subdomain</tt>
+* <tt>:domain_to_domain</tt>
+
+== Sort Orders
+
+When sorting links, the following sort orders are available.
+
+* <tt>:page_athority</tt>
+* <tt>:domain_authority</tt>
+* <tt>:domains_linking_page</tt>
+* <tt>:domains_linking_domain</tt>

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "linkscape"
+    gem.summary = %Q{Provides an interface to the SEOmoz API}
+    gem.description = %Q{Provides an interface to SEOmoz's suite of APIs, including the free and site intelligence APIs.}
+    gem.email = %q{api@seomoz.org}
+    gem.homepage = "http://www.seomoz.org/api"
+    gem.authors = ["Marty Smyth", "Jeff Pollard"]
+    gem.add_dependency "ruby-hmac", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "linkscape #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.6

data/lib/hash-ext.rb

@@ -0,0 +1,24 @@
+# Copied from ActiveSupport, included if we don't already have it
+
+class Hash
+  # Return a new hash with all keys converted to symbols.
+  def symbolize_keys
+    inject({}) do |options, (key, value)|
+      options[(key.downcase.to_sym rescue key) || key] = value
+      options
+    end
+  end
+  def symbolize_keys!
+    self.replace(self.symbolize_keys)
+  end
+  # Return a new hash with all keys converted to strings.
+  def stringify_keys
+    inject({}) do |options, (key, value)|
+      options[(key.to_s rescue key) || key] = value
+      options
+    end
+  end
+  def stringify_keys!
+    self.replace(self.stringify_keys)
+  end
+end

data/lib/linkscape.rb

@@ -0,0 +1,17 @@
+require 'rubygems'
+require 'cgi'
+require 'base64'
+require 'hmac-sha1'
+
+directory = File.expand_path(File.dirname(__FILE__))
+
+require File.join(directory, 'hash-ext') unless Hash.method_defined?(:symbolize_keys)
+require File.join(directory, 'string-ext')
+
+require File.join(directory, 'linkscape', 'signer')
+require File.join(directory, 'linkscape', 'constants')
+
+require File.join(directory, 'linkscape', 'client')
+require File.join(directory, 'linkscape', 'request')
+require File.join(directory, 'linkscape', 'response')
+require File.join(directory, 'linkscape', 'errors')

data/lib/linkscape/client.rb

@@ -0,0 +1,210 @@
+module Linkscape
+  class Client
+    def initialize(*args)
+      options = Hash === args.last ? args.pop : {}
+      @accessID = args.first ? args.shift : (options[:id] || options[:ID] || options[:accessID])
+      @secretKey = args.first ? args.shift : (options[:secret] || options[:secretKey] || options[:key])
+      
+      @options = {
+        :apiHost => 'lsapi.seomoz.com',
+        :apiRoot => 'linkscape',
+        :accessID => @accessID,
+        :secretKey => @secretKey
+      }.merge(options)
+      
+    end
+
+
+    def mozRank(*args)
+      options = Hash === args.last ? args.pop.symbolize_keys : {}
+      url = args.first ? args.shift : options[:url]
+
+      raise MissingArgument, "mozRank requires a url." unless url
+
+      options[:url] = url
+      options[:api] = 'mozrank'
+
+      Linkscape::Request.run(@options.merge(options))
+    end
+
+
+    def urlMetrics(*args)
+      options = Hash === args.last ? args.pop.symbolize_keys : {}
+      url = args.first ? args.shift : options[:url]
+
+      raise MissingArgument, "urlMetrics requires a url." unless url
+
+      options[:url] = url
+      options[:api] = 'url-metrics'
+
+      options[:query] = {
+        'Cols' => translateBitfield(options[:cols], options[:columns], options[:fields], :type => :url)
+      }
+      
+      raise MissingArgument, "urlMetrics requires a list of columns to return." unless options[:query]['Cols'].nonzero?
+      
+      Linkscape::Request.run(@options.merge(options))
+    end
+
+
+    def topLinks(*args)
+      options = Hash === args.last ? args.pop.symbolize_keys : {}
+      url = args.first ? args.shift : options[:url]
+      whichSet = (args.first ? args.shift : (options[:set] || 'none')).to_sym
+      
+      raise MissingArgument, "topLinks requires a set (:page, :subdomain, :domain) and a url." unless whichSet and url
+      
+      options[:url] = url
+
+      options[:api] = {
+        :page => 'page-linklist',
+        :subdomain => 'subdomain-linklist',
+        :domain => 'rootdomain-linklist',
+      }[whichSet]
+      
+      raise InvalidArgument, "topLinks set must be one of :page, :subdomain, :domain" unless options[:api]
+      
+      options[:query] = {
+        'SourceCols' => translateBitfield(options[:sourcecols], options[:sourcecolumns], options[:urlcols], :type => :url),
+        'TargetCols' => translateBitfield(options[:targetcols], options[:targetcolumns], options[:urlcols], :type => :url),
+        'LinkCols' => translateBitfield(options[:cols], options[:columns], options[:linkcols], :type => :link),
+      }
+
+      raise MissingArgument, "topLinks requires a list of columns for Source, Target, and/or Link." unless options[:query]['SourceCols'].nonzero? or options[:query]['TargetCols'].nonzero? or options[:query]['LinkCols'].nonzero?
+      
+      Linkscape::Request.run(@options.merge(options))
+    end
+
+
+    def allLinks(*args)
+      options = Hash === args.last ? args.pop.symbolize_keys : {}
+      url = args.first ? args.shift : options[:url]
+      scope = args.length >= 2 ? "#{args.shift}_to_#{args.shift}" : (args.first ? args.shift : options[:scope])
+      sortOrder = (args.first ? args.shift : (options[:sort] || options[:sortOrder] || 'domains_linking_page')).to_sym
+      filters = args.first ? args.shift : (options[:filters] || options[:filter] || '')
+
+      raise MissingArgument, "allLinks requires a scope ([page, domain] to [page, subdomain, domain]) and a url." unless scope and url
+      raise InvalidArgument, "allLinks scope must be valid ([page, domain] to [page, subdomain, domain])" unless scope.to_s =~ /^(page|domain)_to_(page|subdomain|domain)$/
+      raise InvalidArgument, "allLinks sort order must be valid (domain_authority, page_authority, domains_linking_page, domains_linking_domain)" unless [:domain_authority, :page_authority, :domains_linking_page, :domains_linking_domain].include? sortOrder
+
+      if String === filters
+        filters = filters.downcase.split(/[,\s\+]+/).sort.collect(&:to_sym)
+      elsif Hash === filters
+        filters = filters.keys.collect{|k|k.to_s.downcase}.sort.collect(&:to_sym)
+      elsif Array === filters
+        filters = filters.collect{|k|k.to_s.downcase}.sort.collect(&:to_sym)
+      elsif Symbol === filters
+        filters = [filters]
+      else
+        raise InvalidArgument, "allLinks filters must be a string, hash, or array"
+      end
+      raise InvalidArgument, "allLinks filters must be from the set (:internal, :external, :redir301, :follow, :nofollow)" unless (filters - [:internal, :external, :redir301, :follow, :nofollow]).empty?
+
+      options[:url] = url
+      options[:api] = 'links'
+
+      options[:query] = {
+        'SourceCols' => translateBitfield(options[:sourcecols], options[:sourcecolumns], options[:urlcols], :type => :url),
+        'TargetCols' => translateBitfield(options[:targetcols], options[:targetcolumns], options[:urlcols], :type => :url),
+        'LinkCols' => translateBitfield(options[:cols], options[:columns], options[:linkcols], :type => :link),
+        'Scope' => scope,
+        'Filter' => filters.join(' ').gsub(/redir/, ''),
+        'Sort' => sortOrder.to_s,
+      }
+
+      raise MissingArgument, "allLinks requires a list of columns for Source, Target, and/or Link." unless options[:query]['SourceCols'].nonzero? or options[:query]['TargetCols'].nonzero? or options[:query]['LinkCols'].nonzero?
+      
+      Linkscape::Request.run(@options.merge(options))
+    end
+
+    
+    def topPages(*args)
+      options = Hash === args.last ? args.pop.symbolize_keys : {}
+      url = args.first ? args.shift : options[:url]
+      
+      options[:url] = url
+      options[:api] = 'top-pages'
+      
+      options[:query] = {
+        'Cols' => translateBitfield(options[:cols], options[:columns], options[:sourcecols], options[:sourcecolumns], options[:urlcols], :type => :url),
+      }
+
+      raise MissingArgument, "topPages requires a list of columns to return." unless options[:query]['Cols'].nonzero?
+      
+      Linkscape::Request.run(@options.merge(options))
+    end
+
+
+    def anchorMetrics(*args)
+      options = Hash === args.last ? args.pop.symbolize_keys : {}
+      url = args.first ? args.shift : options[:url]
+      scope = args.length >= 2 ? "#{args.shift}_to_#{args.shift}" : (args.first ? args.shift : options[:scope])
+      filters = args.first ? args.shift : (options[:filters] || options[:filter] || '')
+      sortOrder = (args.first ? args.shift : (options[:sort] || options[:sortOrder] || 'domains_linking_page')).to_sym
+
+      raise InvalidArgument, "anchorMetrics scope must be valid ([phrase, term] to [page, subdomain, domain])" unless scope.to_s =~ /^(phrase|term)_to_(page|subdomain|domain)$/
+      raise InvalidArgument, "anchorMetrics sort order must be valid (domain_authority, page_authority, domains_linking_page, domains_linking_domain)" unless [:domain_authority, :page_authority, :domains_linking_page, :domains_linking_domain].include? sortOrder
+
+      if String === filters
+        filters = filters.downcase.split(/[,\s\+]+/).sort.collect(&:to_sym)
+      elsif Hash === filters
+        filters = filters.keys.collect{|k|k.to_s.downcase}.sort.collect(&:to_sym)
+      elsif Array === filters
+        filters = filters.collect{|k|k.to_s.downcase}.sort.collect(&:to_sym)
+      elsif Symbol === filters
+        filters = [filters]
+      else
+        raise InvalidArgument, "anchorMetrics filters must be a string, hash, or array"
+      end
+      raise InvalidArgument, "anchorMetrics filters must be from the set (:internal, :external)" unless (filters - [:internal, :external]).empty?
+
+      options[:url] = url
+      options[:api] = 'anchor-text'
+
+      options[:query] = {
+        'Cols' => translateBitfield(options[:cols], options[:columns], options[:anchorcols], :type => :anchors),
+        'Scope' => scope,
+        'Filter' => filters.join(' ').gsub(/redir/, ''),
+        'Sort' => sortOrder.to_s,
+      }
+
+      # raise MissingArgument, "anchorMetrics requires a list of columns to return." unless options[:query]['Cols'].nonzero?
+      
+      Linkscape::Request.run(@options.merge(options))
+    end
+
+
+
+
+    def inspect
+      %Q[#<#{self.class}:#{"0x%x" % self.object_id} api="#{@options[:apiHost]}/#{@options[:apiRoot]}" accessID="#{@options[:accessID]}">]
+    end
+    
+    private
+    
+    def translateBitfield *columns
+      options = Hash === columns.last ? columns.pop : {}
+
+      columns.flatten!
+      columns.compact!
+
+      bits = columns.inject(0) do |bitfield, key|
+        requestBit = 
+          if options[:type] == :url
+            Linkscape::Constants::URLMetrics::RequestBits[key]
+          elsif options[:type] == :link
+            Linkscape::Constants::LinkMetrics::RequestBits[key]
+          elsif options[:type] == :anchors
+            Linkscape::Constants::AnchorMetrics::RequestBits[key]
+          else
+            Linkscape::Constants::URLMetrics::RequestBits[key] || Linkscape::Constants::LinkMetrics::RequestBits[key]
+          end
+        raise InvalidArgument, "Unknown #{options[:type]} flag '#{key.inspect}'".gsub(/  +/, ' ') unless requestBit
+        bitfield |= requestBit[:flag]
+      end
+      
+      bits
+    end
+    
+  end
+end