InvisibleHand API Client Ruby

A Ruby client library to the InvisibleHand API. Allows for very easy programmatic access to the Invisible Hand API from Ruby.

Installation

Add this line to your application's Gemfile:

gem 'invisiblehand'

And then execute:

$ bundle

Alternately you can just install directly through the gem command:

$ gem install invisiblehand

Usage

The first thing you must do in order to use this gem is create a configuration that contains your app ID and app key. You can obtain these from the Invisible Hand API website: https://developer.getinvisiblehand.com/.

The sample configuration in this repository gives you a taste of what the config should look like. The gem will look for the config in the following locations in the following order:

- The path or Hash sent to the constructor
- An ENV variable called INVISIBLEHAND_CONFIG
- The current working directory at: ./invisiblehand.yml

Some example usage:

require 'invisiblehand'

# Instantiate the API object using the default config location
# ./invisiblehand.yml
api = InvisibleHand::API.new

# Instantiate the API object with a hard coded, not-in-file config.
api = InvisibleHand::API.new :app_id => "id", :app_key => "key"

# Instantiate the API object from a path to a file.
api = InvisibleHand::API.new "path/to/invisiblehand.yml"

# Search for products that match the query "ipad"
api.products({
  :query => "ipad"
})
#=> An InvisibleHand::Response object that contains the methods #results and
#   #info. #results is an array of InvisibleHand::Product objects and #info is
#   a Hash of meta information on the request (number of results, etc.)

# Search for products with sorting and ordering and a specific size.
api.products({
  :query => "galaxy",    # Search term
  :sort => "popularity", # What to order results by
  :order => "desc",      # Direction to order results by
  :size => "100"         # Number of results to return
})

# Do a live price search on a product (price comes back as the currency in the
# URL you specify. On amazon.com you get dollars, amazon.co.uk you get pounds.)
api.live_price "http://www.amazon.com/gp/product/B005SUHRZS"
#=> 11.25

# You can also specify an Invisible Hand API link to the live_price method and
# it will work fine.
api.live_price "http://api.invisiblehand.co.uk/v1/pages/live_price?url=http%3A%2F%2Fwww.amazon.com%2Fgp%2Fproduct%2FB007PRHNHO"

# Search for a specific product by its Invisible Hand ID
api.product "f619c3e117d50d1a2b10930e5b202336"
#=> An InvisibleHand::Product object.

Region

A little clarification surrounding what the :region parameter is for in the invisiblehand.sample.yml file.

Because product data differs depending on where that product is being sold (for example, amazon.com and amazon.co.uk can differ in price and such), the API returns you only the data relevant to the region that you specify.

A product that exists in our dataset and has only pages in the UK will not be returned for queries that are done on the US API endpoint.

Errors

If the API returns any error information, an InvisibleHand::Error::APIError is thrown and the #message method of the error object will contain the error output from the API.

The InvisibleHand::Error::APIError object also contains #url and #raw_response methods that give you what URL on the API got hit and what the raw response from the server was for debugging purposes.

Logging

The InvisibleHand gem does have debug logging that goes to an internal Logger object. It should not output anything higher than the debug level, which it does when the DEBUG environment variable is set.

If you wish to override the default logging object it builds internally, which outputs to STDOUT, you can do so with the following code:

require 'invisiblehand'

# Ignore all InvisibleHand logging.
InvisibleHand.logger = Logger.new('/dev/null')

Debugging

The gem looks for a DEBUG environment variable. If DEBUG is set, debugging information will be printed out to the screen. This includes URL information every time an API call is made.

Alternately, if you want to do ad-hoc debugging on single API calls you can pass in a debugging option:

require 'invisiblehand'

api = InvisibleHand::API.new :app_id => "id", :app_key => "key"

api.products query: "nickelback", debug: true
#=> Result is the same as normal, you'll just get verbose debugging output to
#   the gem's internal logger (which you can override, see Logging above).

Development

To run tests, first you will need a valid invisiblehand.yml config file inside the spec/ directory. The config you specify must be able to make API calls.

Once you have confirmed this, you can run tests with the following command:

$ rake

And if you wish to see debugging information:

$ DEBUG=true rake