# RakutenWebService

[![CI](https://github.com/rakuten-ws/rws-ruby-sdk/workflows/CI/badge.svg)](https://github.com/rakuten-ws/rws-ruby-sdk/actions?query=workflow%3ACI+branch%3Amaster)
[![Gem Version](https://badge.fury.io/rb/rakuten_web_service.svg)](https://badge.fury.io/rb/rakuten_web_service)
[![Test Coverage](https://codeclimate.com/github/rakuten-ws/rws-ruby-sdk/badges/coverage.svg)](https://codeclimate.com/github/rakuten-ws/rws-ruby-sdk/coverage)
[![Code Climate](https://codeclimate.com/github/rakuten-ws/rws-ruby-sdk/badges/gpa.svg)](https://codeclimate.com/github/rakuten-ws/rws-ruby-sdk)
[![Gitter](https://badges.gitter.im/rakuten-ws/rws-ruby-sdk.svg)](https://gitter.im/rakuten-ws/rws-ruby-sdk?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)

This gem provides a client for easily accessing [Rakuten Web Service APIs](https://webservice.rakuten.co.jp/).

日本語のドキュメントは[こちら](https://github.com/rakuten-ws/rws-ruby-sdk/blob/master/README.ja.md)。

## Table of Contents

* [Prerequisite](#prerequisite)
* [Installation](#installation)
* [Usage](#usage)
  * [Prerequisite: Getting Application ID](#prerequisite-getting-application-id)
  * [Configuration](#configuration)
  * [Search Ichiba Items](#search-ichiba-items)
  * [Pagerizing](#pagerizing)
  * [Genre](#genre)
  * [Ichiba Item Ranking](#ichiba-item-ranking)
* [Supported APIs](#supported-apis)
  * [Rakuten Ichiba APIs](#rakuten-ichiba-apis)
  * [Rakuten Books APIs](#rakuten-books-apis)
  * [Rakuten Kobo APIs](#rakuten-kobo-apis)
  * [Rakuten Recipe APIs](#rakuten-recipe-apis)
  * [Rakuten GORA APIs](#rakuten-gora-apis)
  * [Rakuten Travel APIs](#rakuten-travel-apis)
* [Contributing](#contributing)

## Prerequisite

* Ruby 2.7 or later

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'rakuten_web_service'
```

And then execute:

```sh
bundle
```

Or install it yourself as:

```sh
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](https://webservice.rakuten.co.jp/app/create).

### 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

```ruby
  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

```ruby
  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.

```ruby
  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.

```ruby
  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

```ruby
  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

```ruby
  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](https://webservice.rakuten.co.jp/documentation/ichiba-item-search/)
* [Rakuten Ichiba Genre Search API](https://webservice.rakuten.co.jp/documentation/ichiba-genre-search/)
* [Rakuten Ichiba Ranking API](https://webservice.rakuten.co.jp/documentation/ichiba-item-ranking/)
* [Rakuten Product API](https://webservice.rakuten.co.jp/documentation/ichiba-product-search/)
* [Rakuten Ichiba Tag Search API](https://webservice.rakuten.co.jp/documentation/ichiba-tag-search/)

### Rakuten Books APIs

* [Rakuten Books Total Search API](https://webservice.rakuten.co.jp/documentation/books-total-search/)
* [Rakuten Books Book Search API](https://webservice.rakuten.co.jp/documentation/books-book-search/)
* [Rakuten Books CD Search API](https://webservice.rakuten.co.jp/documentation/books-cd-search/)
* [Rakuten Books DVD/Blu-ray Search API](https://webservice.rakuten.co.jp/documentation/books-dvd-search/)
* [Rakuten Books ForeignBook Search API](https://webservice.rakuten.co.jp/documentation/books-foreign-search/)
* [Rakuten Books Magazine Search API](https://webservice.rakuten.co.jp/documentation/books-magazine-search/)
* [Rakuten Books Game Search API](https://webservice.rakuten.co.jp/documentation/books-game-search/)
* [Rakuten Books Software Search API](https://webservice.rakuten.co.jp/documentation/books-software-search/)
* [Rakuten Books Genre Search API](https://webservice.rakuten.co.jp/documentation/books-genre-search/)

### Rakuten Kobo APIs

* [Rakuten Kobo Ebook Search API](https://webservice.rakuten.co.jp/documentation/kobo-ebook-search/)
* [Rakuten Kobo Genre Search API](https://webservice.rakuten.co.jp/documentation/kobo-genre-search/)

### Rakuten Recipe APIs

* [Rakuten Recipe Category List API](https://webservice.rakuten.co.jp/documentation/recipe-category-list/)
* [Rakuten Recipe Category Ranking API](https://webservice.rakuten.co.jp/documentation/recipe-category-ranking/)

### Rakuten GORA APIs

* [Rakuten GORA Golf Course Search API](https://webservice.rakuten.co.jp/documentation/gora-golf-course-search/)
* [Rakuten GORA Golf Course Detail Search API](https://webservice.rakuten.co.jp/documentation/gora-golf-course-detail/)
* [Rakuten GORA Plan Search API](https://webservice.rakuten.co.jp/documentation/gora-plan-search/)

### Rakuten Travel APIs

* [Rakuten Travel Simple Hotel API](https://webservice.rakuten.co.jp/documentation/simple-hotel-search/)
* [Rakuten Travel Get Area Class API](https://webservice.rakuten.co.jp/documentation/get-area-class/)

## 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