A simple Ruby wrapper around the bol.com developer API
A Ruby wrapper around the bol.com developers API, that will be made available as a Gem. Currently in beta stage.
Bol is a simple Ruby gem, so it requires a working installation of Ruby with Ruby gems. Note: Ruby 1.9 is required. Install the gem:
$ gem install bol
Or, if your project uses Bundler simply add it to your Gemfile
:
gem 'bol'
Then, simply require
it in your code, provide some configuration settings and
query away.
To be allowed to make requests to the Bol.com API you need to register on their site and request a access key and secret. Configure the Bol gem as follows:
Bol.configure do |c|
c.key = 'your public access key'
c.secret = 'your private secret'
c.per_page = 10
end
See an example Sinatra application implementing basic search-and-display functionality: https://gist.github.com/1724664. There's an introductory blog post to go with it.
Here are the currently working operations:
If you know an ID, you can load a product directly:
product = Bol::Product.find(params[:id])
product.title
product.cover(:medium)
product.referral_url('my_associate_id')
You can get a list of popular or bestselling products:
Bol.top_products
Bol.top_products_overall
Bol.top_products_last_week
Bol.top_products_last_two_months
Bol.new_products
Bol.preorder_products
Or, you can apply a scope to limit results to a category:
Bol::Scope.new(params[:category_id]).top_producs
You can search globally for keywords or ISBN and use a Arel-like syntax for setting options:
Bol.search(params[:query]).limit(10).offset(10).order('sales_ranking ASC')
Bol.search(params[:query]).page(params[:page])
You can scope your search to a specific category:
Bol::Scope.new(params[:category_id]).search(params[:query])
Loading all top-level categories (e.g. DVDs
or English Book
) is simple
enough:
categories = Bol.categories
categories.first.name # => 'Books'
You can load subsequent subcategories:
Bol::Scope.new(categories.first.id).categories
Refinements (e.g. 'under 10 euros') work much the same way as categories, but are grouped under a shared name, such as group 'Price' with refinements 'up to 10 euros', '10 to 20 euros', etc.:
groups = Bol.refinements
group = groups.first
group.name # => 'Price'
group.refinements.first.name # => 'under 10 euros'
The Bol::Scope
object limits results to given categories and/or refinements.
You can create a scope using explicit IDs, and you can do basic combinations:
books = Bol::Scope.new(some_category_id)
cheap = Bol::Scope.new(some_refinement_id)
(books + cheap).top_products
Here's an overview of all the operations that should still be implemented:
The available operations map almost directly to operations provided by the API to search, load lists of products or load a single product by ID. I do aim to a add a little sugar to make working with Ruby objects a little easier:
page
helper method to combine limit
and offset
I do not need this stuff myself, but I will gladly take pull requests for such features.
For a full list of changes, please see CHANGELOG.md
Copyright (C) 2011 by Arjan van der Gaag. Published under the MIT license. See LICENSE.md for details.