wordstream_client 0.0.2

data/README.md

@@ -0,0 +1,199 @@
+# Wordstream API Gem
+
+A wrapper around the Wordstream API calls.
+
+* [Github](http://github.com/mtchavez/wordstream-client "Github Repo")
+* [Rubygems](https://rubygems.org/gems/wordstream-client "Rubygems Page")
+
+## Disclaimer
+
+The Wordstream API is constructed very poorly in my personal opinion. In addition to this I have had issues with it's
+reliability and usability. I take no responsibility for you using their service and I advise you use them 
+**at your own risk**. This library was written due to the lack of libraries for Ruby and due to the only one out there does
+not look maintained nor does it implement all the current endpoints available.
+
+## Description
+
+Wordstream API gem to wrap the API calls available. Allows you to login/logout, get your api credits, get keyword volumes,
+get keyword suggestions, get keyword niches, get question keywords and get related keywords. Currently the callback parameter
+is not implemented on any of the endpoints. This may change in the future if it becomes a needed feature.
+
+## Install
+
+    gem install wordstream_client
+
+## Setup
+
+  To set up the gem you need to set your Wordstream username and password before making any API requests.
+
+    require 'wordstream_client'
+    
+    WordstreamClient::Config.username = 'user@example.com'
+    WordstreamClient::Config.password = 'password'
+
+## Authentication Endpoints
+
+---
+
+### Login
+
+  After configuring your username and password you need to login to Wordstream to get a session_id
+  in order to make API requests. This will be configured for you automatically after login.
+
+    WordstreamClient::Auth.login
+
+### Logout
+
+  If you want to destroy your Wordstream session you can use the logout endpoint to do so.
+
+    WordstreamClient::Auth.logout
+
+### Get API Credits
+
+  Wordstream allows you to get your monthly API credits and your monthly credits used. Use this endpoint to
+  see your API credit usage.
+
+    data = WordstreamClient::Auth.get_api_credits
+    
+    # Returns hash of credits
+    # { "remaining_monthly_credits" => 19, "credits_per_month" => 20 }
+    
+    remaining = data['remaining_monthly_credits']
+    total     = data['credits_per_month']
+
+## Keyword Tool Endpoints
+
+---
+
+### Volumes
+
+  To get keyword volumes you can pass in an array of keywords to get their volumes *relative* to each other.
+
+    keywords = %w[running apple ipod ipad race triathlon]
+    data     = WordstreamClient::KeywordTool.get_volumes(keywords)
+    
+    # Returns array of arrays with keywords and their volume
+    # [ ['running', 123], ['apple', 77], ['ipod', 34] ]
+    
+    keyword_volumes       = Hash[data]
+    keywords_with_volumes = keyword_volumes.keys
+
+### Niches
+
+  Make sure to pass in a smaller max then the default as it will most likely timeout from Wordstream.
+
+    keywords = %w[running apple ipod ipad race triathlon]
+    data     = WordstreamClient::KeywordTool.get_niches(keywords)
+    
+    # Example data response
+    # keyword_index refers to the array position in the 'keywords' dict element.
+    {
+      'total': number_of_suggestions,
+      'groupings': [
+        {
+          'title': display_label, 
+          'score': score, 
+          'wordlist': [query_word, ... , query_word], 
+          'matches': [keyword_index, ... , keyword_index]
+        }
+      ], 
+      'keywords': [ [keyword, relative_volume], ... , [keyword, relative_volume] ]
+    }
+    
+
+### Suggestions
+
+  Make sure to pass in a smaller max then the default as it will most likely timeout from Wordstream.
+
+    keywords = %w[running apple ipod ipad race triathlon]
+    data     = WordstreamClient::KeywordTool.get_suggestions(keywords)
+    
+    # Example data response
+    [["apple", 196], ["ipad 2 cases", 95], ["apple
+     stock", 75], ["apple cider vinegar", 72], ["apple store", 69], ["apple computers",
+     69], ["apple juice", 68], ["apple vacations", 60], ["apple ipod", 60], ["apple
+     crisp recipe", 53], ["apple earnings", 52], ["case for ipad 2", 51], ["cases
+     for the ipad 2", 48], ["valley apple", 46], ["apple laptops", 42], ["apple
+     iphone", 42], ["vinegar apple", 39], ["silver apple", 39], ["jeans apple bottom",
+     39], ["apple bottom", 39], ["what is in apple juice", 38], ["stock of apple",
+     38], ["stock in apple", 38], ["stock for apple", 38], ["stock apple com",
+     38], ["apple apple juice", 38], ["tree apple", 36], ["cider apple", 36], ["apple
+     stock shares", 34], ["ipad best buy", 33], ["apple pie", 33], ["apple jeans",
+     33], ["recipes for apple crisp", 31], ["recipe apple", 31], ["ipad charger",
+     31], ["apple osx tiger icons", 31], ["apple airport express", 31], ["wikipedia
+     apple", 29], ["green apple", 28], ["apple charger", 28], ["ipad 2 best buy",
+     26], ["fiona apple", 26], ["big apple", 26], ["wikipedia ipad", 25], ["keyboard
+     case for ipad 2", 25], ["ipad 2 keyboard case", 25], ["ipad 2 case with keyboard",
+     25], ["ipad 2 case and keyboard", 25], ["ipad 2 best cases", 25], ["best cases
+     for ipad 2", 25], ["pie recipe apple", 24], ["stocks on apple", 23], ["leather
+     ipad 2 case", 23], ["leather case for ipad 2", 23], ["cider from apple juice",
+     23], ["cider apple juice", 23], ["apple talk", 23], ["apple juice apple cider",
+     23], ["apple juice and apple cider", 23], ["apple cider or apple juice", 23],
+     ["apple cider from apple juice", 23], ["walmart ipad", 22], ["target ipad",
+     22], ["stock price of apple", 22], ["stock price for apple", 22], ["stock
+     price apple", 22], ["red apple", 22], ["price of stock for apple", 22], ["ipad
+     at target", 22], ["ipad 2 cover case", 22], ["apple lyrics", 22], ["apple
+     stocks and shares", 21], ["apple itunes", 21], ["apple federal credit union",
+     21], ["apple crisp", 21], ["value of apple stock", 20], ["stock quote for
+     apple", 20], ["stock quote apple", 20], ["pie crust for apple pie", 20], ["ipad
+     2 case review", 20], ["how to can apple juice", 20], ["crystal apple", 20],
+     ["can apple juice", 20], ["apple trailers", 20], ["apple stock value", 20],
+     ["apple stock share price", 20], ["apple stock price quote", 20], ["apple
+     pie crust", 20], ["apple picking", 20], ["apple ipad 2 case", 20], ["apple
+     cinnamon", 20], ["stock market for apple", 19], ["stock market apple", 19],
+     ["orchard apple", 19], ["ipad", 19], ["beatles apple", 19], ["apple in the
+     stock market", 19], ["apple caramel", 19], ["apple cake", 19], ["make apple
+     juice", 18]]
+    
+### Question Keywords
+
+    keywords = %w[running apple ipod ipad race triathlon]
+    data     = WordstreamClient::KeywordTool.get_questions(keywords)
+    
+    # Example data response
+    [["what is in apple juice", 38], ["how to can apple juice", 20], ["can apple juice", 20], 
+     ["why buy apple stock", 13], ["where to buy apple stock", 13], ["what s in apple juice", 13], 
+     ["what is apple juice concentrate", 13], ["how do i buy apple stock", 13], 
+     ["what is apple stock today", 12], ["what is apple juice made of", 12], ["how is apple juice made", 12], 
+     ["how much is apple juice", 11], ["does apple juice go bad", 10], ["kindle vs ipad", 9], 
+     ["is apple juice good for you", 9], ["how much is stock in apple", 9], ["how much is apple stock", 9], 
+     ["cider vs apple juice", 9], ["apple juice vs apple cider", 9], ["who owns apple", 8],
+     ["what is apple stock worth", 8], ["will apple stock split", 7], ...]
+
+### Related Keywords
+
+    keywords = %w[running apple ipod ipad race triathlon]
+    data     = WordstreamClient::KeywordTool.get_related(keywords)
+    
+    # Example data response
+    ["mac os x", "learn and earn", "all around
+     my", "store for education", "the crazy ones", "mac os rumors", "rip mix burn",
+     "ipaq pocket pc", "will ferrell", "steve jobs", "will farrell", "os x", "developer
+     connection", "think different", "power book", "learning interchange", "mac
+     rumors", "steven jobs", "knowledge navigator", "digital hub", "think secret",
+     "jonathan ive", "i mac", "data quest", "crazy ones", "rescue raiders", "mac
+     rumor", "next byte", "megahertz myth", "real losers", "pocket pc", "hard reset",
+     "concurso publico", "com br", "ipaq 2210", "ipaq 4150", "ipaq 1940", "detran
+     pernambuco", "detran pe", "iphone", "macintosh", "titanium", "laptops", "applescript",
+     "mac", "applesauce", "apples", "rumors", "mackintosh", "orchards", "appleseed",
+     "versiontracker", "resellers", "parody", "keynote", "imovie", "superdrive",
+     "crabapple", "wallstreet", "macworld", "iphoto", "appleworks", "applewood",
+     "cider", "parodies", "crumble", "laserwriter", "schnapps", "powerpc", "martinis",
+     "applecare", "performa", "crisp", "spoof", "rumor", "manzana", "stylewriter",
+     "gravis", "appletalk", "wozniak", "clarisworks", "pismo", "strudel", "macs",
+     "appel", "garamond", "pectin", "altair", "applejacks", "applestore", "macally",
+     "macrumors", "hypercard", "appleshare", "powerlogix", "macos", "applemac",
+     "isync", "thinkdifferent", "carbonlib"]
+
+## Todo
+
+1. Make RDoc for gem.
+2. Handle potential errors better when making requests to Wordstream.
+3. Refactor HTTP requests.
+4. Make a Response class to be returned from API calls instead of parsed JSON.
+
+## License
+
+Written by Chavez
+
+Released under the MIT License: http://www.opensource.org/licenses/mit-license.php

data/lib/wordstream_client/auth.rb

@@ -0,0 +1,81 @@
+module WordstreamClient
+
+  class Auth
+
+    def initialize(config)
+      @config = config
+    end
+
+    def self.clear_session
+      Config.session_id = nil
+    end
+
+    def clear_session
+      self.class.clear_session
+      @config.session_id = nil if @config
+    end
+
+    def self.login
+      Config.client.auth.login
+    end
+
+    def login
+      path  = '/authentication/login'
+      query = "?username=#{@config.username}&password=#{@config.password}"
+      resp  = RestClient.get(@config.default_host + path + query)
+      data  = JSON.parse resp.body
+
+      raise AuthError.new('login', data['error']) if data.has_key?('error')
+
+      session_id         = data['data']['session_id'] if data.has_key?('data')
+      Config.session_id  = session_id
+      @config.session_id = session_id
+
+      raise AuthError.new('login', 'Failed to get a session id from Wordstream.') if @config.session_id.nil?
+
+      return data
+    rescue JSON::ParserError => e
+      raise AuthError.new('login', 'Bad response from Wordstream when trying to login.')
+    end
+
+    def self.logout
+      Config.client.auth.logout
+    end
+
+    def logout
+      path  = '/authentication/logout'
+      query = "?session_id=#{@config.session_id}"
+      resp  = RestClient.get(@config.default_host + path + query)
+      data  = JSON.parse resp.body
+
+      raise AuthError.new('logout', data['error']) if data.has_key?('error')
+
+      clear_session
+
+      return data
+    rescue JSON::ParserError => e
+      raise AuthError.new('logout', 'Bad response from Wordstream when trying to logout.')
+    ensure
+      clear_session
+    end
+
+    def self.get_api_credits
+      Config.client.auth.get_api_credits
+    end
+
+    def get_api_credits
+      path  = '/authentication/get_api_credits'
+      query = "?session_id=#{@config.session_id}"
+      resp  = RestClient.get(@config.default_host + path + query)
+      data  = JSON.parse resp.body
+
+      raise AuthError.new('get_api_credits', data['detail']) if data['code'].match(/error/i)
+
+      return data
+    rescue JSON::ParserError => e
+      raise AuthError.new('get_api_credits', 'Bad response from Wordstream when trying to get api credits.')
+    end
+
+  end
+
+end

data/lib/wordstream_client/client.rb

@@ -0,0 +1,27 @@
+module WordstreamClient
+
+  class Client
+
+    attr_reader :config
+
+    def initialize(config)
+      @config = if config.is_a?(Hash)
+        Config.new(config)
+      elsif config.is_a?(WordstreamClient::Config)
+        config
+      else
+        raise ArgumentError, 'invalid configuration for client.'
+      end
+    end
+
+    def auth
+      Auth.new @config
+    end
+
+    def keyword_tool(keywords)
+      KeywordTool.new @config, keywords
+    end
+
+  end
+
+end

data/lib/wordstream_client/config.rb

@@ -0,0 +1,47 @@
+module WordstreamClient
+
+  class Config
+
+    class << self
+      attr_accessor :username, :password, :session_id
+    end
+
+    def self.instantiate # :nodoc:
+      new( username: username, password: password, session_id: session_id )
+    end
+
+    def self.client
+      Client.new instantiate
+    end
+
+    def initialize(options = {})
+      [:username, :password, :session_id].each do |var| 
+        instance_variable_set "@#{var}", options[var]
+      end
+    end
+
+    def username
+      @username
+    end
+
+    def password
+      @password
+    end
+
+    def session_id
+      @session_id
+    end
+
+    def session_id=(new_session)
+      # return false if new_session.to_s.empty?
+      instance_variable_set "@session_id", new_session
+      self.class.session_id = new_session
+    end
+
+    def default_host
+      'http://api.wordstream.com'
+    end
+
+  end
+
+end

data/lib/wordstream_client/exceptions.rb

@@ -0,0 +1,22 @@
+module WordstreamClient
+
+  class WordstreamClientError < ::StandardError; end
+
+  class AuthError < WordstreamClientError
+
+    def initialize(method, message) # :nodoc:
+      super "WordstreamClient::Auth.#{method} - #{message}"
+    end
+
+  end
+
+  class KeywordToolError < WordstreamClientError
+
+    def initialize(method, message) # :nodoc:
+      super "WordstreamClient::KeywordTool.#{method} - #{message}"
+    end
+
+  end
+  
+
+end

data/lib/wordstream_client/keyword_tool.rb

@@ -0,0 +1,114 @@
+module WordstreamClient
+
+  class KeywordTool
+
+    attr_accessor :keywords
+
+    def initialize(config, keywords = [])
+      @config   = config
+      @keywords = keywords.is_a?(Array) ? keywords.join("\n") : keywords.to_s
+      # Apache Web Server URL limit is 4000 characters
+      # The API is horrible and passes ALL the keywords
+      # In the URL string
+      @keywords = @keywords[0..3949]
+    end
+
+    def self.get_volumes(keywords, block_adult = 'false')
+      Config.client.keyword_tool(keywords).get_volumes(block_adult)
+    end
+
+    def get_volumes(block_adult = 'false')
+      path         = '/keywordtool/get_keyword_volumes'
+      url_keywords = URI.encode( @keywords, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]") )
+      query        = "?session_id=#{@config.session_id}&keywords=#{url_keywords}&block_adult=#{block_adult}"
+      resp         = RestClient.get( @config.default_host + path + query )
+      data         = JSON.parse resp.body
+
+      raise KeywordToolError.new('get_volumes', data['detail']) if data['code'].match(/error/i)
+
+      return data['data']
+    rescue JSON::ParserError => e
+      raise KeywordToolError.new('get_volumes', 'Bad response from Wordstream when trying to get keyword volumes.')
+    end
+
+    def self.get_niches(keywords, max = 2500, block_adult = 'false')
+      Config.client.keyword_tool(keywords).get_niches(max, block_adult)
+    end
+
+    def get_niches(max = 2500, block_adult = 'false')
+      max          = max.abs > 2500 ? 2500 : max.abs
+      path         = '/keywordtool/get_keyword_niches'
+      url_keywords = URI.encode( @keywords, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]") )
+      query        = "?session_id=#{@config.session_id}&seeds=#{url_keywords}&block_adult=#{block_adult}&max_niches=#{max}"
+      resp         = RestClient.get( @config.default_host + path + query )
+      data         = JSON.parse resp.body
+
+      # TODO: Handle Error Code
+      # "{\"code\": \"ERROR\", \"detail\": \"No keywords provided!!!\"}"
+      raise KeywordToolError.new('get_niches', data['detail']) if data['code'].match(/error/i)
+
+      return data['data']
+    rescue JSON::ParserError => e
+      raise KeywordToolError.new('get_niches', 'Bad response from Wordstream when trying to get keyword niches.')
+    end
+
+    def self.get_suggestions(keywords, max = 100000, block_adult = 'false')
+      Config.client.keyword_tool(keywords).get_suggestions(max, block_adult)
+    end
+
+    def get_suggestions(max = 100000, block_adult = 'false')
+      max          = max.abs > 100000 ? 100000 : max.abs
+      path         = '/keywordtool/get_keywords'
+      url_keywords = URI.encode( @keywords[0..19], Regexp.new("[^#{URI::PATTERN::UNRESERVED}]") )
+      query        = "?session_id=#{@config.session_id}&seeds=#{url_keywords}&block_adult=#{block_adult}&max_niches=#{max}"
+      resp         = RestClient.get( @config.default_host + path + query )
+      data         = JSON.parse resp.body
+
+      raise KeywordToolError.new('get_suggestions', data['detail']) if data['code'].match(/error/i)
+
+      return data['data']
+    rescue JSON::ParserError => e
+      raise KeywordToolError.new('get_suggestions', 'Bad response from Wordstream when trying to get keyword suggestions.')
+    end
+
+    def self.get_questions(keywords, max = 100000, block_adult = 'false')
+      Config.client.keyword_tool(keywords).get_questions(max, block_adult)
+    end
+
+    def get_questions(max = 100000, block_adult = 'false')
+      max          = max.abs > 100000 ? 100000 : max.abs
+      path         = '/keywordtool/get_question_keywords'
+      url_keywords = URI.encode( @keywords[0..19], Regexp.new("[^#{URI::PATTERN::UNRESERVED}]") )
+      query        = "?session_id=#{@config.session_id}&seeds=#{url_keywords}&block_adult=#{block_adult}&max_niches=#{max}"
+      resp         = RestClient.get( @config.default_host + path + query )
+      data         = JSON.parse resp.body
+
+      raise KeywordToolError.new('get_questions', data['detail']) if data['code'].match(/error/i)
+
+      return data['data']
+    rescue JSON::ParserError => e
+      raise KeywordToolError.new('get_questions', 'Bad response from Wordstream when trying to get keyword questions.')
+    end
+
+    def self.get_related(keywords, max = 100, block_adult = 'false')
+      Config.client.keyword_tool(keywords).get_related(max, block_adult)
+    end
+
+    def get_related(max = 100, block_adult = 'false')
+      max          = max.abs > 100 ? 100 : max.abs
+      path         = '/keywordtool/get_related_keywords'
+      url_keywords = URI.encode( @keywords[0..19], Regexp.new("[^#{URI::PATTERN::UNRESERVED}]") )
+      query        = "?session_id=#{@config.session_id}&seeds=#{url_keywords}&block_adult=#{block_adult}&max_niches=#{max}"
+      resp         = RestClient.get( @config.default_host + path + query )
+      data         = JSON.parse resp.body
+
+      raise KeywordToolError.new('get_related', data['detail']) if data['code'].match(/error/i)
+
+      return data['data']
+    rescue JSON::ParserError => e
+      raise KeywordToolError.new('get_related', 'Bad response from Wordstream when trying to get related keyword.')
+    end
+
+  end
+
+end

data/lib/wordstream_client.rb

@@ -0,0 +1,14 @@
+require 'json'
+require 'rest-client'
+require 'net/http'
+require 'pry'
+
+module WordstreamClient
+
+end
+
+require File.dirname(__FILE__) + '/wordstream_client/auth'
+require File.dirname(__FILE__) + '/wordstream_client/client'
+require File.dirname(__FILE__) + '/wordstream_client/config'
+require File.dirname(__FILE__) + '/wordstream_client/exceptions'
+require File.dirname(__FILE__) + '/wordstream_client/keyword_tool'

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: wordstream_client
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Chavez
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-07-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.6.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.6.7
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Wraps Wordstream API calls in a gem.
+email: ''
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- lib/wordstream_client/auth.rb
+- lib/wordstream_client/client.rb
+- lib/wordstream_client/config.rb
+- lib/wordstream_client/exceptions.rb
+- lib/wordstream_client/keyword_tool.rb
+- lib/wordstream_client.rb
+- README.md
+homepage: http://github.com/mtchavez/wordstream-client
+licenses: []
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8 --main=README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: wordstream-client
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Wordstream API Wrapper
+test_files: []
+has_rdoc: