README.md in rakuten_web_service-0.6.3 vs README.md in rakuten_web_service-1.0.0.rc1

- old
+ new

@@ -1,90 +1,124 @@ # RakutenWebService -[![Build Status](https://travis-ci.org/rakuten-ws/rws-ruby-sdk.png?branch=master)](https://travis-ci.org/rakuten-ws/rws-ruby-sdk) [![Gem Version](https://badge.fury.io/rb/rakuten_web_service.png)](http://badge.fury.io/rb/rakuten_web_service) +[![Build Status](https://travis-ci.org/rakuten-ws/rws-ruby-sdk.png?branch=master)](https://travis-ci.org/rakuten-ws/rws-ruby-sdk) +[![Gem Version](https://badge.fury.io/rb/rakuten_web_service.png)](http://badge.fury.io/rb/rakuten_web_service) +[![Coverage Status](https://coveralls.io/repos/github/rakuten-ws/rws-ruby-sdk/badge.svg?branch=master)](https://coveralls.io/github/rakuten-ws/rws-ruby-sdk?branch=master) -rakuten\_web\_serviceは、 Rubyから楽天が提供しているAPIに簡単にアクセスできるSDK(Software Development Kit)です。 +This gem provides a client for easily accessing [Rakuten Web Service APIs](https://webservice.rakuten.co.jp/). -English version is [here](http://github.com/rakuten-ws/rws-ruby-sdk/blob/master/README.en.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) +* [Contributing](#contributing) -bundlerを利用したアプリケーションの場合、Gemfileに以下の1行を追加します。 +## Prerequisite + +* Ruby 2.1.0 or later + +## Installation + +Add this line to your application's Gemfile: + ```ruby gem 'rakuten_web_service' ``` -そして`bundle`コマンドでインストール。 +And then execute: $ bundle -もしくは、`gem`コマンドにより +Or install it yourself as: $ gem install rakuten_web_service -とすることでインストールできます。 -現在rakuten\_web\_serviceは下記のAPIをサポートしています。 +## Usage -### 楽天市場API +### Prerequisite: Getting Application ID -* [Rakuten Ichiba Item Search API](http://webservice.rakuten.co.jp/api/ichibaitemsearch/) -* [Rakuten Ichiba Genre Search API](http://webservice.rakuten.co.jp/api/ichibagenresearch/) -* [Rakuten Ichiba Ranking API](http://webservice.rakuten.co.jp/api/ichibaitemranking/) -* [Rakuten Product API](http://webservice.rakuten.co.jp/api/productsearch/) +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 -### 楽天ブックス系API +At first, you have to specify your application's key. And you can tell the client your afiiliate id with `RakutenWebService.configuration`. -* [Rakuten Books Total Search API](http://webservice.rakuten.co.jp/api/bookstotalsearch/) -* [Rakuten Books Book Search API](http://webservice.rakuten.co.jp/api/booksbooksearch/) -* [Rakuten Books CD Search API](http://webservice.rakuten.co.jp/api/bookscdsearch/) -* [Rakuten Books DVD/Blu-ray Search API](http://webservice.rakuten.co.jp/api/booksdvdsearch/) -* [Rakuten Books ForeignBook Search API](http://webservice.rakuten.co.jp/api/booksforeignbooksearch/) -* [Rakuten Books Magazine Search API](http://webservice.rakuten.co.jp/api/booksmagazinesearch/) -* [Rakuten Books Game Search API](http://webservice.rakuten.co.jp/api/booksgamesearch/) -* [Rakuten Books Software Search API](http://webservice.rakuten.co.jp/api/bookssoftwaresearch/) -* [Rakuten Books Genre Search API](http://webservice.rakuten.co.jp/api/booksgenresearch/) +```ruby + RakutenWebService.configuration do |c| + # (Required) Appliction ID for your application. + c.application_id = 'YOUR_APPLICATION_ID' -### 楽天Kobo系API + # (Optional) Affiliate ID for your Rakuten account. + c.affiliate_id = 'YOUR_AFFILIATE_ID' # default: nil -* [楽天Kobo電子書籍検索API](http://webservice.rakuten.co.jp/api/koboebooksearch/) -* [楽天Koboジャンル検索API](http://webservice.rakuten.co.jp/api/kobogenresearch/) + # (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 +``` -### 事前準備: アプリケーションIDの取得 +Please note that you need to replace `'YOUR_APPLICATION_ID'` and `'YOUR_AFFILIATE_ID'` with actual ones you have. -楽天ウェブサービスAPIを利用の際に、アプリケーションIDが必要です。 -まだ取得していない場合は、楽天ウェブサービスAPIの[アプリケーション登録](https://webservice.rakuten.co.jp/app/create)を行い、アプリケーションIDを取得してください。 +### Search Ichiba Items -### 設定 - -`RakutenWebService.configuration` メソッドを使い、Application IDとAffiliate ID（オプション）を指定することができます。 - ```ruby - RakutenWebService.configuration do |c| - c.application_id = 'YOUR_APPLICATION_ID' - c.affiliate_id = 'YOUR_AFFILIATE_ID' + 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 ``` -`'YOUR_APPLICATION_ID'` と `'YOUR_AFFILIATE_ID'` は、実際のアプリケーションIDとアフィリエイトIDに置き換えてください。 +### 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') # 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. + 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.has_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 + + items.all do |item| + puts item.name + end ``` -### ジャンル +### Genre -Genreクラスは、`children`や`parent`といったジャンル階層を辿るインターフェースを持っています。 +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| @@ -94,15 +128,62 @@ # Use genre id to fetch genre object RakutenWebService::Ichiba::Genre[100316].name # => "水・ソフトドリンク" ``` -### 市場商品ランキング +### Ichiba Item Ranking ```ruby - RakutenWebService::Ichiba::Item.ranking(:age => 30, :sex => 0) # 30代男性 のランキングTOP 30 - RakutenWebService::Ichiba::Genre[100316].ranking # "水・ソフトドリンク" ジャンルのTOP 30 + 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: http://webservice.rakuten.co.jp/api/ichibaitemsearch/#outputParameter + ranking_by_age.each do |ranking| + puts ranking['itemName'] + end + + ranking_by_genre = RakutenWebService::Ichiba::Genre[200162].ranking # the TOP 30 items in "水・ソフトドリンク" genre + ranking_by_genre.each do |ranking| + puts ranking['itemName'] + end ``` + +## Supported APIs + +Now rakuten\_web\_service is supporting the following APIs: + +### Rakuten Ichiba APIs + +* [Rakuten Ichiba Item Search API](http://webservice.rakuten.co.jp/api/ichibaitemsearch/) +* [Rakuten Ichiba Genre Search API](http://webservice.rakuten.co.jp/api/ichibagenresearch/) +* [Rakuten Ichiba Ranking API](http://webservice.rakuten.co.jp/api/ichibaitemranking/) +* [Rakuten Product API](http://webservice.rakuten.co.jp/api/productsearch/) + +### Rakuten Books APIs + +* [Rakuten Books Total Search API](http://webservice.rakuten.co.jp/api/bookstotalsearch/) +* [Rakuten Books Book Search API](http://webservice.rakuten.co.jp/api/booksbooksearch/) +* [Rakuten Books CD Search API](http://webservice.rakuten.co.jp/api/bookscdsearch/) +* [Rakuten Books DVD/Blu-ray Search API](http://webservice.rakuten.co.jp/api/booksdvdsearch/) +* [Rakuten Books ForeignBook Search API](http://webservice.rakuten.co.jp/api/booksforeignbooksearch/) +* [Rakuten Books Magazine Search API](http://webservice.rakuten.co.jp/api/booksmagazinesearch/) +* [Rakuten Books Game Search API](http://webservice.rakuten.co.jp/api/booksgamesearch/) +* [Rakuten Books Software Search API](http://webservice.rakuten.co.jp/api/bookssoftwaresearch/) +* [Rakuten Books Genre Search API](http://webservice.rakuten.co.jp/api/booksgenresearch/) + +### Rakuten Kobo APIs + +* [Rakuten Kobo Ebook Search API](http://webservice.rakuten.co.jp/api/koboebooksearch/) +* [Rakuten Kobo Genre Search API](http://webservice.rakuten.co.jp/api/kobogenresearch/) + +### Rakuten Recipe APIs + +* [Rakuten Recipe Category List API](https://webservice.rakuten.co.jp/api/recipecategorylist/) +* [Rakuten Recipe Category Ranking API](https://webservice.rakuten.co.jp/api/recipecategoryranking/) + +### Rakuten GORA APIs + +* [Rakuten GORA Golf Course Search API](https://webservice.rakuten.co.jp/api/goragolfcoursesearch/) +* [Rakuten GORA Golf Course Detail Search API](https://webservice.rakuten.co.jp/api/goragolfcoursedetail/) +* [Rakuten GORA Plan Search API](https://webservice.rakuten.co.jp/api/goraplansearch/) ## Contributing 1. Fork it 2. Create your feature branch (`git checkout -b my-new-feature`)