alexa 0.4.0 → 0.4.1

data/README.md

@@ -10,91 +10,128 @@ gem install alexa
 
 ## Usage
 
+All success response objects contain `response_id` method.
+
 ### Url Info
 
 ``` ruby
 client = Alexa::Client.new(access_key_id: "key", secret_access_key: "secret")
 url_info = client.url_info(url: "site.com")
-
-returns object with methods:
-: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", "contact_info"]` or any other valid group.
-See: [Docs](http://docs.amazonwebservices.com/AlexaWebInfoService/latest/)
-Default response group takes all the available options.
+Returns object that contains methods:
+
+* 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
+
+You can specify options:
+
+* url - address to be measured
+* response_group - which data to include in response (i.e. ["rank", "contact_info"]) - defaults to all available
+
+See: [Docs](http://docs.amazonwebservices.com/AlexaWebInfoService/latest/) for valid groups.
 
 ### Sites Linking In
 
 ``` ruby
 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
 ```
 
-NOTE: You can specify options:
+Returns object that contains method:
+
+* sites
+
+You can specify options:
 
-* count (how many results to retrieve - default to max value 20)
-* start (offset of results - default to 0)
+* url - address to be measured
+* count - how many results to retrieve - defaults to max value that is 20
+* start - offset of results - defaults 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:
+Returns object that contains method:
+
+* site
+* range
+* start
+* data
 
-* range (how many days to retrieve - default to max value 31)
-* start (start date - default to range days ago)
+You can specify options:
+
+* url - address to be measured
+* range - how many days to retrieve - defaults to max value 31
+* start - start date (i.e. "20120120", 4.days.ago) - defaults to range number 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.
 ```
 
-NOTE:
+Returns object that contains methods:
 
-You can find valid paths on [dmoz](http://www.dmoz.org/) site
+* categories
+* language_categories
+* related_categories
+* letter_bars
 
 You can specify options:
 
-* response_group (any of: categories, related_categories, language_categories, letter_bars)
-* descriptions (include descriptions - boolean, true by default)
+* path - category to be measured (i.e. "Top/Games/Card_Games") - valid paths can be found on [dmoz](http://www.dmoz.org/)
+* response_group - any of: categories, related_categories, language_categories, letter_bars - defaults to all
+* descriptions - should response include descriptions (i.e. false) - defaults to true
 
 ### 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:
+Returns object that contains methods:
 
-You can find valid paths on [dmoz](http://www.dmoz.org/) site
+* count
+* recursive_count
+* listings
 
 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)
+* path - category to be measured (i.e. "Top/Games/Card_Games") - valid paths can be found on [dmoz](http://www.dmoz.org/)
+* sort_by - sort results by one of: popularity, title, average_review - defaults to popularity
+* recursive - should result include subcategories (i.e. false)- defaults to true
+* count - how many results to retrieve - defaults to max value, that is 20
+* start - offset of results - defaults to 0
+* descriptions - should response include descriptions (i.e. false) - defaults to true
 
 ## Caveats
 
+### Status Code
+
+You can retrieve Alexa status code calling `status_code` method.
+
+It happens (so far in TrafficHistory) that Alexa returns response `200` with `AlexaError` status.
+
+### Parsers
+
 Alexa is using `multi_xml` to parse XML documents. Tested with:
 
 * rexml

data/lib/alexa/api/base.rb

@@ -0,0 +1,20 @@
+module Alexa
+  module API
+    class Base
+      include Utils
+
+      attr_reader :arguments, :response_body
+
+      def initialize(credentials)
+        if MultiXml.parser.to_s == "MultiXml::Parsers::Ox"
+          raise StandardError, "MultiXml parser is set to :ox - alexa gem will not work with it currently, use one of: :libxml, :nokogiri, :rexml"
+        end
+        @credentials = credentials
+      end
+
+      def parsed_body
+        @parsed_body ||= MultiXml.parse(response_body)
+      end
+    end
+  end
+end

data/lib/alexa/api/category_browse.rb

@@ -1,62 +1,65 @@
-module Alexa::API
-  class CategoryBrowse
-    include Alexa::Utils
+require "alexa/api/base"
 
-    DEFAULT_RESPONSE_GROUP = ["categories", "related_categories", "language_categories", "letter_bars"]
+module Alexa
+  module API
+    class CategoryBrowse < Base
+      DEFAULT_RESPONSE_GROUP = ["categories", "related_categories", "language_categories", "letter_bars"]
 
-    attr_reader :response_group, :path, :descriptions, :response_body
+      def fetch(arguments = {})
+        raise ArgumentError.new("You must specify path") unless arguments.has_key?(:path)
+        @arguments = arguments
 
-    def initialize(credentials)
-      @credentials = credentials
-    end
+        @arguments[:response_group] = Array(arguments.fetch(:response_group, DEFAULT_RESPONSE_GROUP))
+        @arguments[:descriptions]   = arguments.fetch(:descriptions, true)
 
-    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
+        @response_body = Alexa::Connection.new(@credentials).get(params)
+        self
+      end
 
-    # Attributes
+      # Response attributes
 
-    def categories
-      @categories ||= safe_retrieve(parsed_body, "CategoryBrowseResponse", "Response", "CategoryBrowseResult", "Alexa", "CategoryBrowse", "Categories", "Category")
-    end
+      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 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 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
+      def letter_bars
+        @letter_bars ||= safe_retrieve(parsed_body, "CategoryBrowseResponse", "Response", "CategoryBrowseResult", "Alexa", "CategoryBrowse", "LetterBars", "Category")
+      end
 
-    private
+      def status_code
+        @status_code ||= safe_retrieve(parsed_body, "CategoryBrowseResponse", "Response", "ResponseStatus", "StatusCode")
+      end
 
-    def params
-      {
-        "Action"        => "CategoryBrowse",
-        "ResponseGroup" => response_group_param,
-        "Path"          => path,
-        "Descriptions"  => descriptions_param
-      }
-    end
+      def request_id
+        @request_id ||= safe_retrieve(parsed_body, "CategoryBrowseResponse", "Response", "OperationRequest", "RequestId")
+      end
 
-    def response_group_param
-      response_group.sort.map { |group| camelize(group) }.join(",")
-    end
+      private
 
-    def descriptions_param
-      descriptions.to_s.capitalize
-    end
+      def params
+        {
+          "Action"        => "CategoryBrowse",
+          "ResponseGroup" => response_group_param,
+          "Path"          => arguments[:path],
+          "Descriptions"  => descriptions_param
+        }
+      end
+
+      def response_group_param
+        arguments[:response_group].sort.map { |group| camelize(group) }.join(",")
+      end
 
-    def parsed_body
-      @parsed_body ||= MultiXml.parse(response_body)
+      def descriptions_param
+        arguments[:descriptions].to_s.capitalize
+      end
     end
   end
 end

data/lib/alexa/api/category_listings.rb

@@ -1,66 +1,76 @@
-module Alexa::API
-  class CategoryListings
-    include Alexa::Utils
+require "alexa/api/base"
 
-    attr_reader :path, :sort_by, :recursive, :start, :count, :descriptions, :response_body
+module Alexa
+  module API
+    class CategoryListings < Base
+      def fetch(arguments = {})
+        raise ArgumentError, "You must specify path" unless arguments.has_key?(:path)
+        @arguments = arguments
 
-    def initialize(credentials)
-      @credentials = credentials
-    end
+        @arguments[:sort_by]      = arguments.fetch(:sort_by, "popularity")
+        @arguments[:recursive]    = arguments.fetch(:recursive, true)
+        @arguments[:descriptions] = arguments.fetch(:descriptions, true)
+        @arguments[:start]        = arguments.fetch(:start, 0)
+        @arguments[:count]        = arguments.fetch(:count, 20)
 
-    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
+        @response_body = Alexa::Connection.new(@credentials).get(params)
+        self
+      end
 
-    # Attributes
+      # Response 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
+      def count
+        return @count if defined?(@count)
+        if count = safe_retrieve(parsed_body, "CategoryListingsResponse", "Response", "CategoryListingsResult", "Alexa", "CategoryListings", "Count")
+          @count = count.to_i
+        end
       end
-    end
 
-    def listings
-      @listings ||= safe_retrieve(parsed_body, "CategoryListingsResponse", "Response", "CategoryListingsResult", "Alexa", "CategoryListings", "Listings", "Listing")
-    end
+      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
 
-    private
+      def listings
+        @listings ||= safe_retrieve(parsed_body, "CategoryListingsResponse", "Response", "CategoryListingsResult", "Alexa", "CategoryListings", "Listings", "Listing")
+      end
 
-    def params
-      {
-        "Action"        => "CategoryListings",
-        "ResponseGroup" => "Listings",
-        "Path"          => path,
-        "Recursive"     => recursive_param,
-        "Descriptions"  => descriptions_param,
-        "SortBy"        => sort_by_param,
-        "Count"         => count,
-        "Start"         => start,
-      }
-    end
+      def status_code
+        @status_code ||= safe_retrieve(parsed_body, "CategoryListingsResponse", "Response", "ResponseStatus", "StatusCode")
+      end
 
-    def recursive_param
-      recursive.to_s.capitalize
-    end
+      def request_id
+        @request_id ||= safe_retrieve(parsed_body, "CategoryListingsResponse", "Response", "OperationRequest", "RequestId")
+      end
 
-    def descriptions_param
-      descriptions.to_s.capitalize
-    end
+      private
 
-    def sort_by_param
-      camelize(sort_by)
-    end
+      def params
+        {
+          "Action"        => "CategoryListings",
+          "ResponseGroup" => "Listings",
+          "Path"          => arguments[:path],
+          "Recursive"     => recursive_param,
+          "Descriptions"  => descriptions_param,
+          "SortBy"        => sort_by_param,
+          "Count"         => arguments[:count],
+          "Start"         => arguments[:start],
+        }
+      end
 
-    def parsed_body
-      @parsed_body ||= MultiXml.parse(response_body)
+      def recursive_param
+        arguments[:recursive].to_s.capitalize
+      end
+
+      def descriptions_param
+        arguments[:descriptions].to_s.capitalize
+      end
+
+      def sort_by_param
+        camelize(arguments[:sort_by])
+      end
     end
   end
 end

data/lib/alexa/api/sites_linking_in.rb

@@ -1,41 +1,44 @@
-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)
+require "alexa/api/base"
+
+module Alexa
+  module API
+    class SitesLinkingIn < Base
+      def fetch(arguments = {})
+        raise ArgumentError, "You must specify url" unless arguments.has_key?(:url)
+        @arguments = arguments
+
+        @arguments[:count] = arguments.fetch(:count, 20)
+        @arguments[:start] = arguments.fetch(:start, 0)
+
+        @response_body = Alexa::Connection.new(@credentials).get(params)
+        self
+      end
+
+      # Response attributes
+
+      def sites
+        @sites ||= safe_retrieve(parsed_body, "SitesLinkingInResponse", "Response", "SitesLinkingInResult", "Alexa", "SitesLinkingIn", "Site")
+      end
+
+      def status_code
+        @status_code ||= safe_retrieve(parsed_body, "SitesLinkingInResponse", "Response", "ResponseStatus", "StatusCode")
+      end
+
+      def request_id
+        @request_id ||= safe_retrieve(parsed_body, "SitesLinkingInResponse", "Response", "OperationRequest", "RequestId")
+      end
+
+      private
+
+      def params
+        {
+          "Action"        => "SitesLinkingIn",
+          "ResponseGroup" => "SitesLinkingIn",
+          "Count"         => arguments[:count],
+          "Start"         => arguments[:start],
+          "Url"           => arguments[:url]
+        }
+      end
     end
   end
 end