class Amazon::Search::Request
This is the class around which most others in this library revolve. It contains the most common search methods and exception classes and is the class from which most others in the library inherit.
Attributes
Public Class Methods
Use this method to instantiate a basic search request object. dev_token is your AWS developer token, associate is your Associates ID, locale is the search locale in which you wish to work (us, uk, de, fr, ca or jp), cache is whether or not to utilise a response cache, and user_agent is the name of the client you wish to pass when performing calls to AWS. locale and cache can also be set later, if you wish to change the current behaviour.
For example:
require 'amazon/search' include Amazon::Search r = Request.new('D23XFCO2UKJY82', 'foobar-20', 'us', false) # Do a bunch of things in the US locale with the cache off, then: # r.locale = 'uk' # Switch to the UK locale r.id = 'foobaruk-21' # Use a different Associates ID # in this locale. r.cache = Cache.new('/tmp/amazon') # Start using a cache.
Note that reassigning the locale will dynamically and transparently set up a new HTTP connection to the correct server for that locale.
You may also put one or more of these parameters in a configuration file,
which will be read in the order of /etc/amazonrc
and
~/.amazonrc
. This allows you to have a system configuration
file, but still override some of its directives in a per user configuration
file.
For example:
dev_token = 'D23XFCO2UKJY82' associate = 'calibanorg-20' cache_dir = '/tmp/amazon/cache'
If you do not provide an Associate ID, the one belonging to the author of
the Ruby/Amazon library will be used. If locale is not provided,
us will be used. If cache == true
,
but you do not specify a cache_dir in a configuration file,
/tmp/amazon will be used. However, this last convenience
applies only when a Request object is
instantiated. In other words, if you started off without a cache, but now
wish to use one, you will need to directly assign a Cache object, as shown above.
If your environment requires the use a HTTP proxy server, you should define this in the environment variable $http_proxy. Ruby/Amazon will detect this and channel all outbound connections via your proxy server.
# File lib/amazon/search.rb, line 384 def initialize(dev_token=nil, associate=nil, locale=nil, cache=nil, user_agent = USER_AGENT) def_locale = locale locale = 'us' unless locale locale.downcase! configs = [ '/etc/amazonrc' ] configs << File.expand_path('~/.amazonrc') if ENV.key?('HOME') @config = {} configs.each do |config| if File.exists?(config) && File.readable?(config) Amazon::dprintf("Opening %s ...\n", config) File.open(config) { |f| lines = f.readlines }.each do |line| line.chomp! # Skip comments and blank lines next if line =~ /^(#|$)/ Amazon::dprintf("Read: %s\n", line) # Store these, because we'll probably find a use for these later begin match = line.match(/^(\S+)\s*=\s*(['"]?)([^'"]+)(['"]?)/) key, begin_quote, val, end_quote = match[1,4] raise ConfigError if begin_quote != end_quote rescue NoMethodError, ConfigError raise ConfigError, "bad config line: #{line}" end @config[key] = val # Right now, we just evaluate the line, setting the variable if # it does not already exist eval line.sub(/=/, '||=') end end end # take locale from config file if no locale was passed to method locale = @config['locale'] if @config.key?('locale') && ! def_locale validate_locale(locale) if dev_token.nil? raise TokenError, 'dev_token may not be nil' end @token = dev_token @id = associate || DEFAULT_ID[locale] @user_agent = user_agent @cache = unless cache == false Amazon::Search::Cache.new(@config['cache_dir'] || '/tmp/amazon') else nil end self.locale = locale end
Public Instance Methods
Search for a product by actor and return an Amazon::Search::Response. If a block is given, that Response's @products will be passed to the block.
E.g.
resp = req.actor_search('ricky gervais', 'dvd', LITE, 1, '+titlerank', 'ThirdPartyNew')
# File lib/amazon/search.rb, line 568 def actor_search(actor, mode='dvd', weight=HEAVY, page=1, sort_type=nil, offerings=nil, keyword=nil, price=nil, &block) url = AWS_PREFIX + "?t=%s&ActorSearch=%s&mode=%s&f=xml" + "&type=%s&dev-t=%s&page=%s" url << "&price=" << price unless price.nil? url << get_offer_string(offerings) @type = WEIGHT[weight] sort_string = get_sort_string(sort_type, mode) actor = url_encode(actor) modes = %w[dvd vhs video] unless modes.include? mode raise ModeError, "mode must be one of %s" % modes.join(', ') end mode = localise_mode(mode) url = url % [@id, actor, mode, @type, @token, page] << sort_string url << "&keywords=" << url_encode(keyword) unless keyword.nil? search(url, &block) end
Search for a product by artist and return an Amazon::Search::Response. If a block is given, that Response's @products will be passed to the block.
# File lib/amazon/search.rb, line 598 def artist_search(artist, mode='music', weight=HEAVY, page=1, sort_type=nil, offerings=nil, keyword=nil, price=nil, &block) url = AWS_PREFIX + "?t=%s&ArtistSearch=%s&mode=%s&f=xml" + "&type=%s&dev-t=%s&page=%s" url << "&price=" << price unless price.nil? url << get_offer_string(offerings) @type = WEIGHT[weight] sort_string = get_sort_string(sort_type, mode) artist = url_encode(artist) modes = %w[music classical] unless modes.include? mode raise ModeError, "mode must be one of %s" % modes.join(', ') end mode = localise_mode(mode) url = url % [@id, artist, mode, @type, @token, page] << sort_string url << "&keywords=" << url_encode(keyword) unless keyword.nil? search(url, &block) end
Search for a product by ASIN(s) and returns an
Amazon::Search::Response. If a block is given,
that Response's @products will be passed to the block. The
offer_page parameter is ignored unless offerings is not
nil
.
# File lib/amazon/search.rb, line 629 def asin_search(asin, weight=HEAVY, offer_page=nil, offerings=nil, &block) url = AWS_PREFIX + "?t=%s&AsinSearch=%s&f=xml&type=%s&dev-t=%s" @type = WEIGHT[weight] unless offerings.nil? url << get_offer_string(offerings) url << "&offerpage=%s" % (offer_page || 1) end asin.gsub!(/ /, ',') if asin.is_a? String asin = asin.join(',') if asin.is_a? Array if asin.count(',') >= (weight ? MAX_HEAVY_ASINS : MAX_LITE_ASINS) raise TermError, "too many ASINs" end search(url % [@id, asin, @type, @token], &block) end
Search for a product by director and return an Amazon::Search::Response. If a block is given, that Response's @products will be passed to the block.
# File lib/amazon/search.rb, line 682 def director_search(director, mode='dvd', weight=HEAVY, page=1, sort_type=nil, offerings=nil, keyword=nil, price=nil, &block) url = AWS_PREFIX + "?t=%s&DirectorSearch=%s&mode=%s&f=xml" + "&type=%s&dev-t=%s&page=%s" url << "&keywords=" << url_encode(keyword) unless keyword.nil? url << "&price=" << price unless price.nil? url << get_offer_string(offerings) @type = WEIGHT[weight] sort_string = get_sort_string(sort_type, mode) director = url_encode(director) modes = %w[dvd vhs video] unless modes.include? mode raise ModeError, "mode must be one of %s" % modes.join(', ') end mode = localise_mode(mode) url = url % [@id, director, mode, @type, @token, page] << sort_string url << "&keywords=" << url_encode(keyword) unless keyword.nil? search(url, &block) end
Search for a product by keyword(s) and return an Amazon::Search::Response. If a block is given, that Response's @products will be passed to the block.
# File lib/amazon/search.rb, line 713 def keyword_search(keyword, mode='books', weight=HEAVY, page=1, sort_type=nil, offerings=nil, price=nil, editions=SINGLE_EDITION, &block) url = AWS_PREFIX + "?t=%s&KeywordSearch=%s&mode=%s&f=xml" + "&type=%s&dev-t=%s&page=%s" url << "&price=" << price unless price.nil? url << "&variations=yes" if editions == ALL_EDITIONS url << get_offer_string(offerings) @type = WEIGHT[weight] sort_string = get_sort_string(sort_type, mode) keyword = url_encode(keyword) unless Search.modes.include? mode raise ModeError, "mode must be one of %s" % Search.modes.join(', ') end mode = localise_mode(mode) url = url % [@id, keyword, mode, @type, @token, page] << sort_string search(url, &block) end
Return an Amazon::Search::Response of the products on a Listmania list. If a block is given, that Response's @products will be passed to the block.
# File lib/amazon/search.rb, line 742 def listmania_search(list_id, weight=HEAVY, &block) url = AWS_PREFIX + "?t=%s&ListManiaSearch=%s&f=xml&type=%s&dev-t=%s" @type = WEIGHT[weight] unless list_id.length.between?(12, 13) raise TermError, "list ID length must be 12 or 13 characters" end search(url % [@id, list_id, @type, @token], &block) end
# File lib/amazon/search.rb, line 446 def locale=(l) old_locale = @locale ||= nil @locale = validate_locale(l) # Use the new locale's default ID if the ID currently in use is the # current locale's default ID. @id = DEFAULT_ID[@locale] if @id == DEFAULT_ID[old_locale] # We must now set up a new HTTP connection to the correct server for # this locale, unless the same server is used for both. connect(@locale) unless LOCALES[@locale] == LOCALES[old_locale] end
Search for a product by manufacturer and return an Amazon::Search::Response. If a block is given, that Response's @products will be passed to the block.
# File lib/amazon/search.rb, line 759 def manufacturer_search(director, mode='electronics', weight=HEAVY, page=1, sort_type=nil, offerings=nil, keyword=nil, price=nil, &block) url = AWS_PREFIX + "?t=%s&ManufacturerSearch=%s&mode=%s" + "&f=xml&type=%s&dev-t=%s&page=%s" url << "&price=" << price unless price.nil? url << get_offer_string(offerings) @type = WEIGHT[weight] sort_string = get_sort_string(sort_type, mode) director = url_encode(director) modes = %w[electronics kitchen videogames software photo pc-hardware] unless modes.include? mode raise ModeError, "mode must be one of %s" % modes.join(', ') end mode = localise_mode(mode) url = url % [@id, director, mode, @type, @token, page] << sort_string url << "&keywords=" << url_encode(keyword) unless keyword.nil? search(url, &block) end
Search for a product by browse node. The default of '1000' is for best-selling books. Returns an Amazon::Search::Response. If a block is given, that Response's @products will be passed to the block.
# File lib/amazon/search.rb, line 791 def node_search(browse_node='1000', mode='books', weight=HEAVY, page=1, sort_type=nil, offerings=nil, keyword=nil, price=nil, &block) url = AWS_PREFIX + "?t=%s&BrowseNodeSearch=%s&mode=%s&f=xml" + "&type=%s&dev-t=%s&page=%s" url << "&price=" << price unless price.nil? url << get_offer_string(offerings) @type = WEIGHT[weight] sort_string = get_sort_string(sort_type, mode) if browse_node.is_a? Array raise TypeError, "string or integer required" elsif browse_node =~ / / raise TermError, "single item expected" end unless Search.modes.include? mode raise ModeError, "mode must be one of %s" % Search.modes.join(', ') end mode = localise_mode(mode) url = url % [@id, browse_node, mode, @type, @token, page] << sort_string url << "&keywords=" << url_encode(keyword) unless keyword.nil? search(url, &block) end
Search for a book, using a power search, and return an Amazon::Search::Response. If a block is given, that Response's @products will be passed to the block.
# File lib/amazon/search.rb, line 825 def power_search(query, mode='books', weight=HEAVY, page=1, sort_type=nil, offerings=nil, editions=SINGLE_EDITION, &block) url = AWS_PREFIX + "?t=%s&PowerSearch=%s&mode=%s&f=xml" + "&type=%s&dev-t=%s&page=%s" url << "&variations=yes" if editions == ALL_EDITIONS url << get_offer_string(offerings) sort_string = get_sort_string(sort_type, mode) @type = WEIGHT[weight] query = url_encode(query) raise ModeError, 'mode must be books' unless mode == 'books' mode = localise_mode(mode) url = url % [@id, query, mode, @type, @token, page] << sort_string search(url, &block) end
Search for a product's similar products and return an Amazon::Search::Response. If a block is given, that Response's @products will be passed to the block.
# File lib/amazon/search.rb, line 851 def similarity_search(asin, weight=HEAVY, page=1, &block) url = AWS_PREFIX + "?t=%s&SimilaritySearch=%s&f=xml" + "&type=%s&dev-t=%s&page=%s" @type = WEIGHT[weight] asin.gsub!(/ /, ',') if asin.is_a? String asin = asin.join(',') if asin.is_a? Array if asin.count(',') >= 5 raise TermError, "too many ASINs (max. 5 for this search)" end search(url % [@id, asin, @type, @token, page], &block) end
Perform a text stream search and return an Amazon::Search::Response. If a block is given, that Response's @products will be passed to the block.
# File lib/amazon/search.rb, line 872 def text_stream_search(text_stream, mode='books', weight=HEAVY, sort_type=nil, page=1, &block) # this search type not available for international sites unless @locale == 'us' raise LocaleError, "search type invalid in '#{@locale}' locale" end url = AWS_PREFIX + "?t=%s&TextStreamSearch=%s&mode=%s&f=xml" + "&type=%s&dev-t=%s&page=%s" @type = WEIGHT[weight] sort_string = get_sort_string(sort_type, mode) modes = %w[electronics books videogames apparel toys photo music dvd wireless-phones] unless modes.include? mode raise ModeError, "mode must be one of %s" % modes.join(', ') end # strip a few useless words from the text stream %w[and or not the a an but to for of on at].each do |particle| text_stream.gsub!(/\b#{particle}\b/, '') end text_stream = url_encode(text_stream) url = url % [@id, text_stream, mode, @type, @token, page] << sort_string search(url, &block) end
Search for a product by UPC code(s) and return an Amazon::Search::Response. If a block is given, that Response's @products will be passed to the block.
# File lib/amazon/search.rb, line 908 def upc_search(upc, mode='music', weight=HEAVY, &block) unless @locale == 'us' raise LocaleError, "search type invalid in '#{@locale}' locale" end url = AWS_PREFIX + "?t=%s&UpcSearch=%s&mode=%s&f=xml&type=%s&dev-t=%s" @type = WEIGHT[weight] upc.gsub!(/ /, ',') if upc.is_a? String upc = upc.join(',') if upc.is_a? Array if upc.count(',') >= (weight ? MAX_HEAVY_UPCS : MAX_LITE_UPCS) raise TermError, "too many UPCs" end modes = %w[music classical software dvd vhs video electronics pc-hardware photo] unless modes.include? mode raise ModeError, "mode must be one of %s" % modes.join(', ') end mode = localise_mode(mode) search(url % [@id, upc, mode, @type, @token], &block) end
Return an Amazon::Search::Response of the products on a wishlist. If a block is given, that Response's @products will be passed to the block.
# File lib/amazon/search.rb, line 939 def wishlist_search(list_id, weight=HEAVY, page=1, &block) url = AWS_PREFIX + "?t=%s&WishlistSearch=%s&f=xml" + "&type=%s&dev-t=%s&page=%s" @type = WEIGHT[weight] unless list_id.length.between?(12, 13) raise TermError, "list ID length must be 12 or 13 characters" end search(url % [@id, list_id, @type, @token, page], &block) end