RakutenWebService

This gem provides a client for easily accessing Rakuten Web Service APIs.

日本語のドキュメントはこちら。

Table of Contents

• Prerequisite
• Installation
• Usage
  • Prerequisite: Getting Application ID
  • Configuration
  • Search Ichiba Items
  • Pagerizing
  • Genre
  • Ichiba Item Ranking
• Supported APIs
  • Rakuten Ichiba APIs
  • Rakuten Books APIs
  • Rakuten Kobo APIs
  • Rakuten Recipe APIs
  • Rakuten GORA APIs
  • Rakuten Travel APIs
• Contributing

Prerequisite

• Ruby 2.7 or later

Installation

Add this line to your application's Gemfile:

gem 'rakuten_web_service'

And then execute:

bundle

Or install it yourself as:

gem install rakuten_web_service

Usage

Prerequisite: Getting Application ID

You need to get Application ID for your application to access to Rakuten Web Service APIs. If you have not got it, register your application here.

Configuration

At first, you have to specify your application's key. And you can tell the client your afiiliate id with RakutenWebService.configure.

In Your Code

  RakutenWebService.configure do |c|
    # (Required) Appliction ID for your application.
    c.application_id = 'YOUR_APPLICATION_ID'

    # (Optional) Affiliate ID for your Rakuten account.
    c.affiliate_id = 'YOUR_AFFILIATE_ID' # default: nil

    # (Optional) # of retries to send requests when the client receives
    # When the number of requests in some period overcomes the limit, the endpoints will return
    # too many requests error. Then the client tries to retry to send the same request after a
    # while.
    c.max_retries = 3 # default: 5

    # (Optional) Enable debug mode. When set true, the client streams out all HTTP requests and
    # responses to the standard error.
    c.debug = true # default: false
  end

Please note that you need to replace 'YOUR_APPLICATION_ID' and 'YOUR_AFFILIATE_ID' with actual ones you have.

Environment Variables

You can configure application_id and affiliate_id by defining environment variables RWS_APPLICATION_ID and RWS_AFFILIATE_ID.

Search Ichiba Items

  items = RakutenWebService::Ichiba::Item.search(keyword: 'Ruby') # This returns Enumerable object
  items.first(10).each do |item|
    puts "#{item['itemName']}, #{item.price} yen" # You can refer to values as well as Hash.
  end

Pagerizing

Responses of resources' search such as RakutenWebService::Ichiba::Item.search have methods for paginating fetched resources.

  items = RakutenWebService::Ichiba::Item.search(keyword: 'Ruby')
  items.count #=> 30. In default, the API returns up to 30 items matched with given keywords.

  last_items = items.page(3) # Skips first 2 pages.

  # Go to the last page
  while last_items.next_page?
    last_items = last_items.next_page
  end

  # Shows the title of the last 30 items
  last_items.each do |item|
    puts item.name
  end

  # Easier way to fetch all resources page 3 and latter
  items.page(3).all do |item|
    puts item.name
  end

Genre

Genre class provides an interface to traverse sub genres.

  root = RakutenWebService::Ichiba::Genre.root # root genre
  # children returns sub genres
  root.children.each do |child|
    puts "[#{child.id}] #{child.name}"
  end

  # Use genre id to fetch genre object
  RakutenWebService::Ichiba::Genre[100316].name # => "水・ソフトドリンク"

Ichiba Item Ranking

  ranking_by_age = RakutenWebService::Ichiba::Item.ranking(age: 30, sex: 1) # returns the TOP 30 items for Male in 30s
  # For attributes other than 'itemName', see: https://webservice.rakuten.co.jp/documentation/ichibaitemsearch/#outputParameter
  ranking_by_age.each do |ranking|
    puts item.name
  end

  ranking_by_genre = RakutenWebService::Ichiba::Genre[200162].ranking # the TOP 30 items in "水・ソフトドリンク" genre
  ranking_by_genre.each do |ranking|
    puts item.name
  end

Recipe

  categories = RakutenWebService::Recipe.small_categories

  # Search all small recipe categories.
  categories.each do |category|
    category.name
  end

  recipes = categories.first.ranking

  # Search category recipes.
  recipes.each do |recipe|
    recipe.title
  end

Supported APIs

Now rakuten_web_service is supporting the following APIs:

Rakuten Ichiba APIs

• Rakuten Ichiba Item Search API
• Rakuten Ichiba Genre Search API
• Rakuten Ichiba Ranking API
• Rakuten Product API
• Rakuten Ichiba Tag Search API

Rakuten Books APIs

• Rakuten Books Total Search API
• Rakuten Books Book Search API
• Rakuten Books CD Search API
• Rakuten Books DVD/Blu-ray Search API
• Rakuten Books ForeignBook Search API
• Rakuten Books Magazine Search API
• Rakuten Books Game Search API
• Rakuten Books Software Search API
• Rakuten Books Genre Search API

Rakuten Kobo APIs

• Rakuten Kobo Ebook Search API
• Rakuten Kobo Genre Search API

Rakuten Recipe APIs

• Rakuten Recipe Category List API
• Rakuten Recipe Category Ranking API

Rakuten GORA APIs

• Rakuten GORA Golf Course Search API
• Rakuten GORA Golf Course Detail Search API
• Rakuten GORA Plan Search API

Rakuten Travel APIs

• Rakuten Travel Simple Hotel API
• Rakuten Travel Get Area Class API

Contributing

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