LinkShare API

Ruby wrapper for LinkShare Publisher Web Services. Supported web services:

Deep Linking (previously Automated LinkGenerator)
Merchandiser Query Tool
Coupon Web Service

If you need services that are not yet supported, feel free to contribute. For questions or bugs please create an issue.

Requirements

Ruby 1.9 or above.

Installation

Add this line to your application's Gemfile:

gem 'linkshare_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install linkshare_api

Configuration

Before using LinkShare API you need to set up your publisher token first. If you use Ruby on Rails, the token can be set in a configuration file (i.e. app/config/initializers/linkshare_api.rb), otherwise just set it in your script. The token can be found on LinkShare's Web Services page under the Links tab.

LinkshareAPI.token = ENV["LINKSHARE_TOKEN"]

Affiliate ID is required for using Deep Linking.

LinkshareAPI.affiliate_id = ENV["LINKSHARE_AFFILIATE_ID"]

By default linkshare_api logs to STDOUT. To use your own logger implementation you have to specify it using LinkshareAPI.logger

Configuration example

Would apply for Ruby on Rails. Create app/config/initializers/linkshare_api.rb and add the following content:

LinkshareAPI.token = ENV["LINKSHARE_TOKEN"]
LinkshareAPI.affiliate_id = ENV["LINKSHARE_AFFILIATE_ID"]
LinkshareAPI.logger = Rails.logger

Usage

Deep Linking

Generate affiliate URLs using Deep Linking service. Below is an example of generating an affiliate URL for Walmart. Walmart merchant code is 2149.

require "linkshare_api" # No need for RoR

LinkshareAPI.affiliate_id = ENV["LINKSHARE_AFFILIATE_ID"] # must be set in order to use Deep Linking, otherwise will fall back to Automated Link Generator
url = "http://www.walmart.com/cp/Electronics/3944?povid=P1171-C1093.2766-L33"
affiliate_url = LinkshareAPI.link_generator(2149, url)
# http://click.linksynergy.com/deeplink?id=your_affiliate_id&mid=2149&murl=http%3A%2F%2Fwww.walmart.com%2Fcp%2FElectronics%2F3944%3Fpovid%3DP1171-C1093.2766-L33

Note: The link is generated manually, therefore you must ensure that the Affiliate ID provided is valid and that merchant supports deeplinking.

Automated Link Generator

Deprecation Notice

As of October 2014, Automated LinkGenerator is discontinued in favor of Deep Linking. To use Deep Linking instead, you only have to set LinkshareAPI.affiliate_id. Everything else remains the same.

Generate affiliate URLs using Automated LinkGenerator service. Below is an example of generating an affiliate URL for Walmart. Walmart merchant code is 2149.

url = "http://www.walmart.com/cp/Electronics/3944?povid=P1171-C1093.2766-L33"
affiliate_url = LinkshareAPI.link_generator(2149, url)
# http://linksynergy.walmart.com/fs-bin/click?id=your_affiliate_id&subid=0&offerid=223073.1&type=10&tmpid=273&RD_PARM1=http%3A%2F%2Fwww.walmart.com%2Fcp%2FElectronics%2F3944%3F&RD_PARM2=povid%3DP1171-C1093.2766-L33

Merchandiser Query Tool

Search for products using Merchandiser Query Tool service.

response = LinkshareAPI.product_search(keyword: "laptop")
# Return the number of total records that match the search criteria
puts response.total_matches # -1 means more than 4000 results (see doc)
# Return the number of pages
puts response.total_pages
# Return the number of current page
puts response.page_number
# See the actual API call to Linkshare
puts response.request.uri
# Return items
response.data.each do |item|
  puts "Title: #{item.productname}"
  puts "Price: #{item.price.__content__} #{item.price.currency}"
  puts "URL: #{item.linkurl}"
end

product_search accepts a hash as argument, and can include all available options. For a complete list of options please visit https://rakutenlinkshare.zendesk.com/hc/en-us/articles/201483905-Merchandiser-Query-Tool-API-Guidelines.

# Search "laptop" only for Wal-Mart, within Electronics category,
# sorted by price ascending, and limit to 10 items per page.
options = {
  keyword: "laptop",
  mid: 2149, # Wal-Mart
  cat: "Electronics",
  max: 10,
  sort: :retailprice,
  sorttype: :asc
}
response = LinkshareAPI.product_search(options)
response.data.each do |item|
  # Do stuff
end

If there are multiple pages, you can retrieve all pages by using the all method, as follows:

response.all.each do |item|
  # Do stuff
end

When using the all method, response object is updated with the data returned by the last API request (last page). response.all returns the data array.

Coupon Web Service

Easy access to coupons and promotional link data for your advertisers using Coupon Web Service

# Search for promotion types "Clearance" (id 3) and "Dollar Amount Off" (id 5)
# from Wal-Mart (id 2149) within category "Apparel - Babies & Kids" (id 3)
# in the US network (id 1)
options = {
  promotiontype: 3|5,
  mid: 2149,
  cat: 3,
  network: 1
}
response = LinkshareAPI.coupon_web_service(options)
response.data.each do |item|
  # Do stuff
end

Extra Configuration

LinkshareAPI.api_timeout - the timeout set when initiating requests to LinkShare Web Services (default value is 30 seconds)

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

License

MIT

linkshare_api

Development

Runtime