alexa 0.3.1 → 0.4.0

data/.travis.yml

@@ -2,11 +2,10 @@ notifications:
   disabled: true
 rvm:
   - ree
-  - 1.9.2
   - 1.9.3
 env:
-  - ALEXA_XML_PARSER=rexml
-  - ALEXA_XML_PARSER=nokogiri
-  - ALEXA_XML_PARSER=libxml
+  - XML_PARSER=rexml
+  - XML_PARSER=nokogiri
+  - XML_PARSER=libxml
   # does not work yet
-  # - ALEXA_XML_PARSER=ox
+  # - XML_PARSER=ox

data/Gemfile

@@ -1,6 +1,7 @@
 source "https://rubygems.org"
 
 gem "minitest", :platform => :ruby_18
+gem "debugger", :platform => :ruby_19
 gem "rake"
 
 # xml parsers

data/README.md

@@ -10,52 +10,107 @@ gem install alexa
 
 ## Usage
 
+### Url Info
+
 ``` ruby
-Alexa.url_info(:access_key_id => "key", :secret_access_key => "secret", :host => "site.com")
+client = Alexa::Client.new(access_key_id: "key", secret_access_key: "secret")
+url_info = client.url_info(url: "site.com")
 
 returns object with methods:
-:xml_response, :rank, :data_url, :site_title, :site_description, :language_locale, :language_encoding,
+:rank, :data_url, :site_title, :site_description, :language_locale, :language_encoding,
 :links_in_count, :keywords, :related_links, :speed_median_load_time, :speed_percentile,
 :rank_by_country, :rank_by_city, :usage_statistics
 ```
 
-NOTE: You can specify option `:response_group => "Rank,ContactInfo"` or any other valid group.
+NOTE: You can specify option `response_group: ["rank", "contact_info"]` or any other valid group.
 See: [Docs](http://docs.amazonwebservices.com/AlexaWebInfoService/latest/)
 Default response group takes all the available options.
 
-You can set configuration in block like this:
+### Sites Linking In
 
 ``` ruby
-Alexa.configure do |config|
-  config.access_key_id     = "key"
-  config.secret_access_key = "secret"
-end
+client = Alexa::Client.new(access_key_id: "key", secret_access_key: "secret")
+sites_linking_in = client.sites_linking_in(url: "site.com")
+
+# returns object with `sites` method
 ```
 
-alexa is using `multi_xml` to parse XML documents. Tested with:
+NOTE: You can specify options:
 
-* rexml
-* nokogiri
-* libxml
+* count (how many results to retrieve - default to max value 20)
+* start (offset of results - default to 0)
+
+### Traffic History
+
+``` ruby
+client = Alexa::Client.new(access_key_id: "key", secret_access_key: "secret")
+traffic_history = client.traffic_history(url: "site.com")
+
+# returns object with `data` method
+```
+
+NOTE: You can specify options:
+
+* range (how many days to retrieve - default to max value 31)
+* start (start date - default to range days ago)
+
+### Category Browse
+
+``` ruby
+client = Alexa::Client.new(access_key_id: "key", secret_access_key: "secret")
+category_browse = client.category_browse(path: "Top/Games/Card_Games")
+
+# returns object with `categories`, `language_categories`, `related_categories`, `letter_bars` methods.
+```
 
-Currently alexa wont work with `ox` gem
+NOTE:
 
-## TODO
+You can find valid paths on [dmoz](http://www.dmoz.org/) site
 
-Support following:
+You can specify options:
 
-* Traffic History
-* Category Browse
-* Category Listings
-* Sites Linking In
+* response_group (any of: categories, related_categories, language_categories, letter_bars)
+* descriptions (include descriptions - boolean, true by default)
+
+### Category Listings
+
+``` ruby
+client = Alexa::Client.new(access_key_id: "key", secret_access_key: "secret")
+category_listings = client.category_listings(path: "Top/Games/Card_Games")
+
+# returns object with `recursive_count`, `listings` methods.
+```
+
+NOTE:
+
+You can find valid paths on [dmoz](http://www.dmoz.org/) site
+
+You can specify options:
+
+* sort_by (sort results by one of: popularity, title, average_review)
+* recursive (results for the given category only, or including subcategories - boolean, true by default)
+* count (how many results to retrieve - default to max value 20)
+* start (offset of results - default to 0)
+* descriptions (include descriptions - boolean, true by default)
+
+## Caveats
+
+Alexa is using `multi_xml` to parse XML documents. Tested with:
+
+* rexml
+* nokogiri
+* libxml
+
+Currently alexa will not work with `ox` gem
 
 ## Contributors
 
 * [rmoriz](https://github.com/rmoriz)
 
 ## Continuous Integration
-[![Build Status](https://secure.travis-ci.org/morgoth/alexa.png)](http://travis-ci.org/morgoth/alexa)
+
+[![Build Status](https://secure.travis-ci.org/morgoth/alexa.png?branch=master)](http://travis-ci.org/morgoth/alexa)
 
 ## Copyright
 
-Copyright (c) 2012 Wojciech Wnętrzak. See LICENSE for details.
+Copyright (c) Wojciech Wnętrzak. See LICENSE for details.

data/alexa.gemspec

@@ -18,13 +18,5 @@ Gem::Specification.new do |gem|
   gem.add_dependency "multi_xml", ">= 0.5.0"
 
   gem.add_development_dependency "mocha"
-  gem.add_development_dependency "fakeweb"
-
-  gem.post_install_message = %{
-
-Gem syntax of 0.4 version of this gem will change with backward incompatibilities.
-If you don't want to update your code, please specify in your Gemfile:
-gem "alexa", "~> 0.3.0"
-
-}
+  gem.add_development_dependency "webmock"
 end

data/lib/alexa.rb

@@ -1,28 +1,17 @@
-require "cgi"
-require "base64"
-require "openssl"
-require "digest/sha1"
-require "net/https"
-require "time"
-
 require "multi_xml"
 
 require "alexa/version"
-require "alexa/url_info"
+require "alexa/utils"
+require "alexa/exceptions"
+require "alexa/connection"
+require "alexa/client"
+require "alexa/api/category_browse"
+require "alexa/api/category_listings"
+require "alexa/api/sites_linking_in"
+require "alexa/api/traffic_history"
+require "alexa/api/url_info"
 
 module Alexa
-  class << self
-    attr_accessor :access_key_id, :secret_access_key
-
-    def configure
-      yield self
-    end
-
-    def url_info(options = {})
-      url_info = Alexa::UrlInfo.new(options)
-      xml = url_info.connect
-      url_info.parse_xml(xml)
-      url_info
-    end
-  end
+  API_VERSION = "2005-07-11"
+  API_HOST    = "awis.amazonaws.com"
 end

data/lib/alexa/api/category_browse.rb

@@ -0,0 +1,62 @@
+module Alexa::API
+  class CategoryBrowse
+    include Alexa::Utils
+
+    DEFAULT_RESPONSE_GROUP = ["categories", "related_categories", "language_categories", "letter_bars"]
+
+    attr_reader :response_group, :path, :descriptions, :response_body
+
+    def initialize(credentials)
+      @credentials = credentials
+    end
+
+    def fetch(arguments = {})
+      @path           = arguments[:path] || raise(ArgumentError.new("You must specify path"))
+      @response_group = Array(arguments.fetch(:response_group, DEFAULT_RESPONSE_GROUP))
+      @descriptions   = arguments.fetch(:descriptions, true)
+      @response_body  = Alexa::Connection.new(@credentials).get(params)
+      self
+    end
+
+    # Attributes
+
+    def categories
+      @categories ||= safe_retrieve(parsed_body, "CategoryBrowseResponse", "Response", "CategoryBrowseResult", "Alexa", "CategoryBrowse", "Categories", "Category")
+    end
+
+    def language_categories
+      @language_categories ||= safe_retrieve(parsed_body, "CategoryBrowseResponse", "Response", "CategoryBrowseResult", "Alexa", "CategoryBrowse", "LanguageCategories", "Category")
+    end
+
+    def related_categories
+      @related_categories ||= safe_retrieve(parsed_body, "CategoryBrowseResponse", "Response", "CategoryBrowseResult", "Alexa", "CategoryBrowse", "RelatedCategories", "Category")
+    end
+
+    def letter_bars
+      @letter_bars ||= safe_retrieve(parsed_body, "CategoryBrowseResponse", "Response", "CategoryBrowseResult", "Alexa", "CategoryBrowse", "LetterBars", "Category")
+    end
+
+    private
+
+    def params
+      {
+        "Action"        => "CategoryBrowse",
+        "ResponseGroup" => response_group_param,
+        "Path"          => path,
+        "Descriptions"  => descriptions_param
+      }
+    end
+
+    def response_group_param
+      response_group.sort.map { |group| camelize(group) }.join(",")
+    end
+
+    def descriptions_param
+      descriptions.to_s.capitalize
+    end
+
+    def parsed_body
+      @parsed_body ||= MultiXml.parse(response_body)
+    end
+  end
+end

data/lib/alexa/api/category_listings.rb

@@ -0,0 +1,66 @@
+module Alexa::API
+  class CategoryListings
+    include Alexa::Utils
+
+    attr_reader :path, :sort_by, :recursive, :start, :count, :descriptions, :response_body
+
+    def initialize(credentials)
+      @credentials = credentials
+    end
+
+    def fetch(arguments = {})
+      @path          = arguments[:path] || raise(ArgumentError.new("You must specify path"))
+      @sort_by       = arguments.fetch(:sort_by, "popularity")
+      @recursive     = arguments.fetch(:recursive, true)
+      @start         = arguments.fetch(:start, 0)
+      @count         = arguments.fetch(:count, 20)
+      @descriptions  = arguments.fetch(:descriptions, true)
+      @response_body = Alexa::Connection.new(@credentials).get(params)
+      self
+    end
+
+    # Attributes
+
+    def recursive_count
+      return @recursive_count if defined?(@recursive_count)
+      if recursive_count = safe_retrieve(parsed_body, "CategoryListingsResponse", "Response", "CategoryListingsResult", "Alexa", "CategoryListings", "RecursiveCount")
+        @recursive_count = recursive_count.to_i
+      end
+    end
+
+    def listings
+      @listings ||= safe_retrieve(parsed_body, "CategoryListingsResponse", "Response", "CategoryListingsResult", "Alexa", "CategoryListings", "Listings", "Listing")
+    end
+
+    private
+
+    def params
+      {
+        "Action"        => "CategoryListings",
+        "ResponseGroup" => "Listings",
+        "Path"          => path,
+        "Recursive"     => recursive_param,
+        "Descriptions"  => descriptions_param,
+        "SortBy"        => sort_by_param,
+        "Count"         => count,
+        "Start"         => start,
+      }
+    end
+
+    def recursive_param
+      recursive.to_s.capitalize
+    end
+
+    def descriptions_param
+      descriptions.to_s.capitalize
+    end
+
+    def sort_by_param
+      camelize(sort_by)
+    end
+
+    def parsed_body
+      @parsed_body ||= MultiXml.parse(response_body)
+    end
+  end
+end

data/lib/alexa/api/sites_linking_in.rb

@@ -0,0 +1,41 @@
+module Alexa::API
+  class SitesLinkingIn
+    include Alexa::Utils
+
+    attr_reader :url, :count, :start, :response_body
+
+    def initialize(credentials)
+      @credentials = credentials
+    end
+
+    def fetch(arguments = {})
+      @url           = arguments[:url] || raise(ArgumentError.new("You must specify url"))
+      @count         = arguments.fetch(:count, 20)
+      @start         = arguments.fetch(:start, 0)
+      @response_body = Alexa::Connection.new(@credentials).get(params)
+      self
+    end
+
+    # Attributes
+
+    def sites
+      @sites ||= safe_retrieve(parsed_body, "SitesLinkingInResponse", "Response", "SitesLinkingInResult", "Alexa", "SitesLinkingIn", "Site")
+    end
+
+    private
+
+    def params
+      {
+        "Action"        => "SitesLinkingIn",
+        "ResponseGroup" => "SitesLinkingIn",
+        "Count"         => count,
+        "Start"         => start,
+        "Url"           => url
+      }
+    end
+
+    def parsed_body
+      @parsed_body ||= MultiXml.parse(response_body)
+    end
+  end
+end

data/lib/alexa/api/traffic_history.rb

@@ -0,0 +1,45 @@
+module Alexa::API
+  class TrafficHistory
+    include Alexa::Utils
+
+    attr_reader :url, :range, :start, :response_body
+
+    def initialize(credentials)
+      @credentials = credentials
+    end
+
+    def fetch(arguments = {})
+      @url           = arguments[:url] || raise(ArgumentError.new("You must specify url"))
+      @range         = arguments.fetch(:range, 31)
+      @start         = arguments.fetch(:start) { Time.now - (3600 * 24 * range.to_i) }
+      @response_body = Alexa::Connection.new(@credentials).get(params)
+      self
+    end
+
+    # Attributes
+
+    def data
+      @data ||= safe_retrieve(parsed_body, "TrafficHistoryResponse", "Response", "TrafficHistoryResult", "Alexa", "TrafficHistory", "HistoricalData", "Data")
+    end
+
+    private
+
+    def params
+      {
+        "Action"        => "TrafficHistory",
+        "ResponseGroup" => "History",
+        "Range"         => range,
+        "Start"         => start_param,
+        "Url"           => url
+      }
+    end
+
+    def start_param
+      start.respond_to?(:strftime) ? start.strftime("%Y%m%d") : start
+    end
+
+    def parsed_body
+      @parsed_body ||= MultiXml.parse(response_body)
+    end
+  end
+end

data/lib/alexa/api/url_info.rb

@@ -0,0 +1,108 @@
+module Alexa::API
+  class UrlInfo
+    include Alexa::Utils
+
+    DEFAULT_RESPONSE_GROUP = ["adult_content", "contact_info", "keywords", "language", "links_in_count", "owned_domains", "rank", "rank_by_city", "rank_by_country", "related_links", "site_data", "speed", "usage_stats"]
+
+    attr_reader :url, :response_group, :response_body
+
+    def initialize(credentials)
+      @credentials = credentials
+    end
+
+    def fetch(arguments = {})
+      @url            = arguments[:url] || raise(ArgumentError.new("You must specify url"))
+      @response_group = Array(arguments.fetch(:response_group, DEFAULT_RESPONSE_GROUP))
+      @response_body  = Alexa::Connection.new(@credentials).get(params)
+      self
+    end
+
+    # attributes
+
+    def rank
+      return @rank if defined?(@rank)
+      if rank = safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "TrafficData", "Rank")
+        @rank = rank.to_i
+      end
+    end
+
+    def rank_by_country
+      @rank_by_country ||= safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "TrafficData", "RankByCountry", "Country")
+    end
+
+    def rank_by_city
+      @rank_by_city ||= safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "TrafficData", "RankByCity", "City")
+    end
+
+    def data_url
+      @data_url ||= safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "TrafficData", "DataUrl", "__content__")
+    end
+
+    def usage_statistics
+      @usage_statistics ||= safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "TrafficData", "UsageStatistics", "UsageStatistic")
+    end
+
+    def site_title
+      @site_title ||= safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "ContentData", "SiteData", "Title")
+    end
+
+    def site_description
+      @site_description ||= safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "ContentData", "SiteData", "Description")
+    end
+
+    def language_locale
+      @language_locale ||= safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "ContentData", "Language", "Locale")
+    end
+
+    def language_encoding
+      @language_encoding ||= safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "ContentData", "Language", "Encoding")
+    end
+
+    def links_in_count
+      return @links_in_count if defined?(@links_in_count)
+      if links_in_count = safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "ContentData", "LinksInCount")
+        @links_in_count = links_in_count.to_i
+      end
+    end
+
+    def keywords
+      @keywords ||= safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "ContentData", "Keywords", "Keyword")
+    end
+
+    def speed_median_load_time
+      return @speed_median_load_time if defined?(@speed_median_load_time)
+      if speed_median_load_time = safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "ContentData", "Speed", "MedianLoadTime")
+        @speed_median_load_time = speed_median_load_time.to_i
+      end
+    end
+
+    def speed_percentile
+      return @speed_percentile if defined?(@speed_percentile)
+      if speed_percentile = safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "ContentData", "Speed", "Percentile")
+        @speed_percentile = speed_percentile.to_i
+      end
+    end
+
+    def related_links
+      @related_links ||= safe_retrieve(parsed_body, "UrlInfoResponse", "Response", "UrlInfoResult", "Alexa", "Related", "RelatedLinks", "RelatedLink")
+    end
+
+    private
+
+    def params
+      {
+        "Action"        => "UrlInfo",
+        "ResponseGroup" => response_group_param,
+        "Url"           => url
+      }
+    end
+
+    def response_group_param
+      response_group.sort.map { |group| camelize(group) }.join(",")
+    end
+
+    def parsed_body
+      @parsed_body ||= MultiXml.parse(response_body)
+    end
+  end
+end