martijnsch / linkscape-gem

Provides an interface to SEOmoz's suite of APIs, including the free and site intelligence APIs.

Linkscape Gem¶ ↑

This is the official Gem to interact with the SEOmoz API. For more information, please check out the API page on SEOmoz and the SEOmoz API Wiki. Note: this gem is currently an alpha release, and is not intended for production use…yet.

Usage¶ ↑

First you must secure an accessID and secret key from SEOmoz. See the API page 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 response 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, data 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:

• :cols - An array of columns (see below) to return in the response, or the :all 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, :type can be either :page, :subdomain :domain. 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:

• :sourcecols - An array of data columns (see below) that should be returned for the link source.

• :targetcols - An array of data columns (see below) that should be returned for the link target.

• :linkcols - An array of data columns (see below) that should be returned for the link itself.

• :limit - The # of links (limit) you would like to return.

• :offset = 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, :type can be either :page, :subdomain :domain. 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:

• :sourcecols - An array of data columns (see below) that should be returned for the link source.

• :targetcols - An array of data columns (see below) that should be returned for the link target.

• :linkcols - An array of data columns (see below) that should be returned for the link itself.

• :filters - 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. :filters => [:internal,:follow,:redir301].

• :limit - The # of links (limit) you would like to return.

• :offset = The number of records to offset before returning the 1st record of results.

• :scope - 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, :type can be either :page, :subdomain :domain. 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:

• :cols - An array of data columns (see below) that should be returned for the link source.

• :limit - The # of links (limit) you would like to return.

• :offset = 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:

• :cols - An array of data columns (see below) that should be returned.

• :scope - A symbol representing the ‘scope’ of the anchor text data (see below).

• :sort - A symbol representing the ‘sort order’ of the anchor text data (see below).

• :filters - A symbol representing the ‘filter’ of the anchor text data (see below). NOTE: Only :external or internal filters may be used, separately.

• :limit - The # of links (limit) you would like to return.

• :offset = 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¶ ↑

• :all_external_links

• :canonical_internal_id

• :canonical_url

• :cblocks_linking

• :domain_authority

• :domain_authority_raw

• :external_links

• :external_mozrank

• :external_mozrank_raw

• :fq_domain

• :fq_domain_all_external_links

• :fq_domain_external_links

• :fq_domain_external_mozrank_sum

• :fq_domain_external_mozrank_sum_raw

• :fq_domain_fq_domains_linking

• :fq_domain_internal_links

• :fq_domain_juice_fq_domains_linking

• :fq_domain_juice_internal_links

• :fq_domain_juice_links

• :fq_domain_juice_pl_domains_linking

• :fq_domain_links

• :fq_domain_mozrank

• :fq_domain_mozrank_raw

• :fq_domain_mozrank_sum

• :fq_domain_mozrank_sum_raw

• :fq_domain_moztrust

• :fq_domain_moztrust_raw

• :fq_domain_pl_domains_linking

• :fq_domain_unfollowed_external_links

• :fq_domain_unfollowed_fq_domains_linking

• :fq_domain_unfollowed_internal_links

• :fq_domain_unfollowed_links

• :fq_domain_unfollowed_pl_domains_linking

• :fq_domain_updated_at

• :fq_domains_linking

• :internal_id

• :internal_links

• :ips_linking

• :juice_cblocks_linking

• :juice_fq_domains_linking

• :juice_internal_links

• :juice_ips_linking

• :juice_links

• :juice_pl_domains_linking

• :links

• :mozrank

• :mozrank_raw

• :moztrust

• :moztrust_raw

• :page_authority

• :page_authority_raw

• :pl_domain

• :pl_domain_all_external_links

• :pl_domain_cblocks_linking

• :pl_domain_external_links

• :pl_domain_external_mozrank_sum

• :pl_domain_external_mozrank_sum_raw

• :pl_domain_internal_links

• :pl_domain_ips_linking

• :pl_domain_juice_cblocks_linking

• :pl_domain_juice_internal_links

• :pl_domain_juice_ips_linking

• :pl_domain_juice_links

• :pl_domain_juice_pl_domains_linking

• :pl_domain_links

• :pl_domain_mozrank

• :pl_domain_mozrank_raw

• :pl_domain_mozrank_sum

• :pl_domain_mozrank_sum_raw

• :pl_domain_moztrust

• :pl_domain_moztrust_raw

• :pl_domain_pl_domains_linking

• :pl_domain_unfollowed_cblocks_linking

• :pl_domain_unfollowed_external_links

• :pl_domain_unfollowed_internal_links

• :pl_domain_unfollowed_ips_linking

• :pl_domain_unfollowed_links

• :pl_domain_unfollowed_pl_domains_linking

• :pl_domain_updated_at

• :pl_domains_linking

• :status

• :title

• :unfollowed_cblocks_linking

• :unfollowed_external_links

• :unfollowed_fq_domains_linking

• :unfollowed_internal_links

• :unfollowed_ips_linking

• :unfollowed_links

• :unfollowed_pl_domains_linking

• :updated_at

• :url

Link Metrics¶ ↑

• :text

• :mozrank (passed)

Anchor Text Metrics¶ ↑

• :flags

• :internal_mozrank

• :internal_pages_linking

• :external_subdomains_linking

• :external_mozrank

• :text

• :internal_subdomains_linking

• :external_domains_linking

• :record_id

• :external_pages_linking

Available Filters¶ ↑

Links may be filtered by any of the following. Anchor text may o

• :internal

• :external

• :redir301

• :follow

• :nofollow

Anchor Text Scope¶ ↑

When requesting anchor text data, the following scopes may be used.

• :phrase_to_page

• :phrase_to_subdomain

• :phrase_to_domain

• :term_to_page

• :term_to_subdomain

• :term_to_domain

Link Scope¶ ↑

When requesting links, the following scope may be used

• :page_to_page

• :page_to_subdomain

• :page_to_domain

• :domain_to_page

• :domain_to_subdomain

• :domain_to_domain

Sort Orders¶ ↑

When sorting links, the following sort orders are available.

• :page_athority

• :domain_authority

• :domains_linking_page

• :domains_linking_domain