### Example Rakuten Books Book Search Request

Source: https://webservice.rakuten.co.jp/documentation/books-book-search

An example of a GET request to the Rakuten Books Book Search API. This specific example searches for books with the title '太陽' (Sun) in the 'Japanese novel' genre, sorted by the cheapest item price first. Note that parameter values like 'title' and 'booksGenreId' are URL-encoded.

```http
https://openapi.rakuten.co.jp/services/api/BooksBook/Search/20170404?
        applicationId=[APPLICATION ID]
        &title=%E5%A4%AA%E9%99%BD
        &booksGenreId=001004008
        &sort=%2BitemPrice
```

--------------------------------

### Rakuten Books Total Search API Endpoint Example

Source: https://webservice.rakuten.co.jp/documentation/books-total-search

Example of constructing a URL for the Rakuten Books Total Search API. Demonstrates how to include parameters like application ID, keyword, sorting, and negative keywords. Note that keywords and other values may need UTF-8 URL encoding.

```http
https://openapi.rakuten.co.jp/services/api/BooksTotal/Search/20170404?
        applicationId=[APPLICATION ID]
        &keyword=%E6%9C%AC
        &NGKeyword=%E4%BA%88%E7%B4%84
        &sort=%2BitemPrice
```

--------------------------------

### GET /engine/api/Travel/GetHotelChainList/20131024

Source: https://webservice.rakuten.co.jp/documentation/get-hotel-chain-list

このエンドポイントは、楽天トラベルのホテルチェーン情報を取得するために使用されます。アプリケーションIDとアクセスキーが必要です。

```APIDOC
## GET /engine/api/Travel/GetHotelChainList/20131024

### Description
Retrieves hotel chain information from Rakuten Travel.

### Method
GET

### Endpoint
`https://openapi.rakuten.co.jp/engine/api/Travel/GetHotelChainList/20131024`

### Parameters
#### Query Parameters
- **applicationId** (String) - Required - Your Rakuten Developer Application ID.
- **accessKey** (String) - Required - Your Rakuten Developer Access Key.
- **affiliateId** (String) - Optional - Your Rakuten Affiliate ID.
- **format** (String) - Optional - Response format. Defaults to `json`. Can be `xml` or `json`.
- **callback** (String) - Optional - Callback function name for JSONP requests.
- **elements** (String) - Optional - Comma-separated list of fields to include in the response. By default, all fields are returned.
- **formatVersion** (int) - Optional - Response format version. Defaults to `1`. `2` provides an improved JSON format.

### Request Example
```
https://openapi.rakuten.co.jp/engine/api/Travel/GetHotelChainList/20131024?applicationId=YOUR_APP_ID&accessKey=YOUR_ACCESS_KEY&format=json
```

### Response
#### Success Response (200)
- **largeClasses** (Object) - Contains hotel chain data.
  - **largeClass** (Array) - List of hotel chain categories.
    - **largeClassCode** (String) - Code for the large class.
- **hotelChains** (Object) - Contains hotel chain details.
  - **hotelChain** (Array) - List of individual hotel chains.
    - **hotelChainCode** (String) - Code for the hotel chain.
    - **hotelChainName** (String) - Name of the hotel chain.
    - **hotelChainNameKana** (String) - Kana name of the hotel chain.
    - **hotelChainComment** (String) - Description of the hotel chain.

#### Response Example (JSON)
```json
{
    "items": [
        {
            "item": {
                "itemName": "Example Hotel Chain",
                "itemPrice": 10000
            }
        }
    ]
}
```

### Error Handling
- **400 Bad Request**: Parameter error or insufficient required parameters.
- **404 Not Found**: Data not found.
- **429 Too Many Requests**: Rate limit exceeded.
- **500 Internal Server Error**: Rakuten Web Service internal error.
```

--------------------------------

### JSON Response Format Version 2 Example

Source: https://webservice.rakuten.co.jp/documentation/books-book-search

Demonstrates the JSON response structure when `formatVersion=2` is used. This improved format places book item fields directly within the 'items' array, simplifying access. For example, `itemName` can be accessed via `items[0].itemName`.

```json
{
"items": [
    {
        "itemName": "a",
        "itemPrice": 10
    },
    {
        "itemName": "b",
        "itemPrice": 20
    }
]
}
```

--------------------------------

### GET /item-details

Source: https://webservice.rakuten.co.jp/documentation/ichiba-item-ranking

Retrieves comprehensive item information including flags for availability, tax, shipping, and promotional details like point multipliers.

```APIDOC
## GET /item-details

### Description
Returns detailed metadata for a Rakuten item, including flags for stock status, tax, shipping, and affiliate-related information.

### Method
GET

### Endpoint
/item-details

### Response
#### Success Response (200)
- **mediumImageUrls** (array) - Array of up to three 128x128 image URLs.
- **availability** (integer) - 0: Out of stock, 1: Available.
- **taxFlag** (integer) - 0: Tax included, 1: Tax not included.
- **postageFlag** (integer) - 0: Postage included, 1: Postage not included.
- **creditCardFlag** (integer) - 0: Not accepted, 1: Accepted.
- **shopOfTheYearFlag** (integer) - 0: No, 1: Yes.
- **shipOverseasFlag** (integer) - 0: No, 1: Yes.
- **asurakuFlag** (integer) - 0: No, 1: Yes.
- **affiliateRate** (float) - Current affiliate commission rate.
- **reviewCount** (integer) - Total number of reviews.
- **reviewAverage** (float) - Average review score.
- **pointRate** (integer) - Point multiplier value.
- **shopName** (string) - Name of the merchant.
- **shopCode** (string) - Unique identifier for the shop.

### Response Example
{
	"availability": 1,
	"taxFlag": 0,
	"shopName": "Rakuten Store",
	"reviewAverage": 4.5
}
```

--------------------------------

### Rakuten API Error Response Examples (JSON)

Source: https://webservice.rakuten.co.jp/documentation/ichiba-item-search

Examples of JSON error responses from the Rakuten Web Service API for various error conditions like invalid parameters, not found, and system errors.

```json
{
    "error": "wrong_parameter",
    "error_description": "keyword parameter is not valid"
}
```

```json
{
    "error": "not_found",
    "error_description": "not found"
}
```

```json
{
    "error": "too_many_requests",
    "error_description": "number of allowed requests has been exceeded for this API. please try again soon."
}
```

```json
{
    "error": "system_error",
    "error_description": "api logic error"
}
```

```json
{
    "error": "service_unavailable",
    "error_description": "XXX/XXX is under maintenance"
}
```

```json
{
    "error": "wrong_parameter",
    "error_description": "page must be a number"
}
```

--------------------------------

### Retrieve Data using Rakuten Web Service SDK (Ruby)

Source: https://webservice.rakuten.co.jp/documentation/ichiba-item-search

Shows how to use the Rakuten Web Service SDK in Ruby to search for Ichiba items. This example includes configuring the application and affiliate IDs, performing a search, and iterating through the results to display item names and prices.

```ruby
require 'rakuten_web_service'

RakutenWebService.configuration do |c|
  c.application_id = YOUR_APPLICATION_ID
  c.affiliate_id = YOUR_AFFILIATE_ID
end

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

```

--------------------------------

### Constructing a Rakuten Ichiba Item Search URL

Source: https://webservice.rakuten.co.jp/documentation/ichiba-item-search

This example demonstrates how to construct a URL for the Rakuten Ichiba Item Search API, including URL encoding for parameters like 'keyword' and 'sort'. It shows how to combine multiple parameters for a specific search query.

```url
https://openapi.rakuten.co.jp/ichibams/api/IchibaItem/Search/20220601?applicationId=[APPLICATION ID]&keyword=%E7%A6%8F%E8%A8%BC&sort=%2BitemPrice
```

--------------------------------

### Maintenance Error Description Example

Source: https://webservice.rakuten.co.jp/documentation/keyword-hotel-search

This example shows a specific error description indicating that a service or endpoint is under maintenance. This message helps users understand temporary unavailability and plan accordingly.

```json
{
    "error_description": "XXX/XXX is under maintenance"
}
```

--------------------------------

### Rakuten Ichiba Ranking API - GET Request

Source: https://webservice.rakuten.co.jp/documentation/ichiba-item-ranking

This section details the parameters available for the Rakuten Ichiba Ranking API GET request. You can filter rankings by genre, age group, gender, platform, and page number. The `formatVersion` parameter controls the response structure.

```APIDOC
## GET /ranking

### Description
Retrieves product ranking information from Rakuten Ichiba based on specified criteria.

### Method
GET

### Endpoint
/ranking

### Parameters
#### Query Parameters
- **formatVersion** (int) - Optional - Response format version. `2` provides an improved JSON structure compared to `1`.
- **genreId** (long) - Optional - The ID for specifying genres. If not provided along with `age` or `sex`, all ranking information is shown.
- **age** (int) - Optional - Age group for filtering: `10` (10-19), `20` (20-29), `30` (30-39), `40` (40-49), `50` (50 and up). Can be used with `sex`.
- **sex** (int) - Optional - Gender for filtering: `0` (Male), `1` (Female). Can be used with `age`.
- **carrier** (int) - Optional - Platform for the information: `0` (PC), `1` (mobile).
- **page** (int) - Optional - Page number for the results, between 1 and 34.
- **period** (string) - Optional - Period for ranking data: `realtime`.

### Response
#### Success Response (200)
- **title** (string) - Ranking title.
- **lastBuildDate** (string) - Time of last update.
- **items** (array) - Array of item ranking information.
  - **rank** (int) - Rank of the item.
  - **carrier** (int) - Platform (0: PC, 1: mobile).
  - **itemName** (string) - Item name. Use `_catchcopy_` + `_itemname_` for the usual name.
  - **catchcopy** (string) - Sales message.
  - **itemCode** (string) - Item code.
  - **itemPrice** (string) - Item price.
  - **itemPriceBaseField** (string) - Indicates the price range field used (e.g., "item_price_min1").
  - **itemPriceMax1** (string) - Maximum price for all items.
  - **itemPriceMax2** (string) - Maximum searchable item price.
  - **itemPriceMax3** (string) - Maximum purchasable item price.
  - **itemPriceMin1** (string) - Minimum price for all items.
  - **itemPriceMin2** (string) - Minimum searchable item price.
  - **itemPriceMin3** (string) - Minimum purchasable item price.
  - **hasPriceRange** (int) - Indicates if there is a price range (0: No, 1: Yes).
  - **itemCaption** (string) - Item description or caption.
  - **itemUrl** (string) - URL for the item.
  - **affiliateUrl** (string) - Affiliate URL (only if `affiliateId` is provided).
  - **imageFlag** (int) - Indicates if the item has an image (0: No, 1: Yes).
  - **smallImageUrls** (array) - Array of up to three 64x64 pixel image URLs.

#### Response Example (formatVersion=1)
```json
{
  "items": [
    {
      "item": {
        "itemName": "a",
        "itemPrice": 10
      }
    },
    {
      "item": {
        "itemName": "b",
        "itemPrice": 20
      }
    }
  ]
}
```

#### Response Example (formatVersion=2)
```json
{
  "items": [
    {
      "itemName": "a",
      "itemPrice": 10
    },
    {
      "itemName": "b",
      "itemPrice": 20
    }
  ]
}
```
```

--------------------------------

### JSON Response Format Version 1 Example

Source: https://webservice.rakuten.co.jp/documentation/books-book-search

Illustrates the JSON response structure when `formatVersion=1` is used. In this format, book items are nested within an 'item' object inside the 'items' array. Accessing fields requires a path like `items[0].item.itemName`.

```json
{
"items": [
    {
    "item": {
        "itemName": "a",
        "itemPrice": 10
    }
    },
    {
    "item": {
        "itemName": "b",
        "itemPrice": 20
    }
    }
]
}
```

--------------------------------

### Retrieve Data using Rakuten SDK

Source: https://webservice.rakuten.co.jp/documentation/ichiba-item-ranking

Demonstrates how to initialize the Rakuten Web Service client and perform ranking queries using the official SDKs for PHP and Ruby.

```php
require_once '/path/to/sdk-dir/autoload.php';

$client = new RakutenRws_Client();
$client->setApplicationId('YOUR_APPLICATION_ID');

$response = $client->execute('IchibaItemRanking', array(
  'genreId' => '100227'
));

if ($response->isOk()) {
    echo $response['title']."ranking title\n";
    foreach ($response as $item) {
        echo $item['itemName']."\n";
    }
} else {
    echo 'Error:'.$response->getMessage();
}
```

```ruby
require 'rakuten_web_service'

RakutenWebService.configuration do |c|
  c.application_id = YOUR_APPLICATION_ID
  c.affiliate_id = YOUR_AFFILIATE_ID
end

RakutenWebService::Ichiba::Item.ranking(:age => 30, :sex => 0)
RakutenWebService::Ichiba::Genre[100316].ranking
```

--------------------------------

### Configure Rakuten Web Service Client

Source: https://webservice.rakuten.co.jp/documentation/ichiba-genre-search

Initializes the Rakuten Web Service client by setting the required application and affiliate IDs. This configuration is a prerequisite for making any API calls.

```ruby
RakutenWebService.configuration do |c|
  c.application_id = YOUR_APPLICATION_ID
  c.affiliate_id = YOUR_AFFILIATE_ID
end
```

--------------------------------

### Retrieve Genre Data via SDK

Source: https://webservice.rakuten.co.jp/documentation/ichiba-genre-search

Demonstrates how to initialize the Rakuten Web Service client and execute a genre search request using the provided SDK.

```php
<?php
require_once '/path/to/sdk-dir/autoload.php';

$client = new RakutenRws_Client();
$client->setApplicationId('YOUR_APPLICATION_ID');

$response = $client->execute('IchibaGenreSearch', array(
    'genreId' => 0
));

if ($response->isOk()) {
    foreach ($response['children'] as $childGenre) {
        $genre = $childGenre['child'];
        echo $genre['genreName']."\n";
    }
} else {
    echo 'Error:'.$response->getMessage();
}
```

```ruby
require 'rakuten_web_service'
```

--------------------------------

### XML Error Response Example

Source: https://webservice.rakuten.co.jp/documentation/books-software-search

This snippet illustrates an XML formatted error response from the Rakuten Ichiba API, similar to the JSON example for wrong parameters. This format is provided for systems that prefer or require XML.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <error>wrong_parameter</error>
    <error_description>page must be a number</error_description>
</root>
```

--------------------------------

### Affiliate Link Generation

Source: https://webservice.rakuten.co.jp/documentation/ichiba-item-ranking

Guidelines for constructing affiliate URLs using the item URL and affiliate ID.

```APIDOC
## Affiliate Link Construction

### Description
Developers can generate affiliate links by combining the item URL and their Affiliate ID. The Item URL must be URL-encoded.

### Construction Rule
`http://hb.afl.rakuten.co.jp/hgc/[Affiliate ID]/?pc=[Item URL(PC)]&m=[Item URL(mobile)]`

### Notes
- If an Affiliate ID is provided in the input, the API returns a pre-generated `shopAffiliateUrl`.
- Manual construction is supported for custom integration.
```

--------------------------------

### GET /engine/api/Gora/GoraGolfCourseDetail/20170623

Source: https://webservice.rakuten.co.jp/documentation/gora-golf-course-detail

Retrieves detailed information for a specific golf course by its ID.

```APIDOC
## GET /engine/api/Gora/GoraGolfCourseDetail/20170623

### Description
Fetches detailed information for a specific golf course. Requires an application ID and access key.

### Method
GET

### Endpoint
https://openapi.rakuten.co.jp/engine/api/Gora/GoraGolfCourseDetail/20170623

### Parameters
#### Query Parameters
- **applicationId** (String) - Required - Your application ID
- **accessKey** (String) - Required - Your access key (can also be passed via Authorization header)
- **golfCourseId** (long) - Required - The ID of the golf course
- **format** (String) - Optional - Response format (json or xml, default: json)
- **formatVersion** (int) - Optional - Response structure version (1 or 2, default: 1)
- **carrier** (int) - Optional - 0 for PC, 1 for mobile (default: 0)

### Request Example
https://openapi.rakuten.co.jp/engine/api/Gora/GoraGolfCourseDetail/20170623?format=json&applicationId=[YourAppId]&golfCourseId=12345

### Response
#### Success Response (200)
- **golfCourseName** (String) - Name of the golf course
- **address** (String) - Physical address
- **telephoneNo** (String) - Contact phone number
- **weekdayMinPrice** (int) - Minimum weekday plan price
- **holidayMinPrice** (int) - Minimum holiday plan price

#### Response Example
{
  "golfCourseName": "Example Golf Club",
  "address": "1-2-3, Tokyo, Japan",
  "telephoneNo": "03-0000-0000",
  "weekdayMinPrice": 5000,
  "holidayMinPrice": 8000
}
```

--------------------------------

### 楽天トラベルホテルチェーンAPIリクエストURL例 (XML形式)

Source: https://webservice.rakuten.co.jp/documentation/get-hotel-chain-list

楽天トラベルホテルチェーンAPIを使用してホテルチェーンのリストをXML形式で取得するためのリクエストURLの例です。`applicationId`と`format=xml`を指定する必要があります。大量のアクセスは一時的な利用停止の原因となるため注意が必要です。

```url
https://openapi.rakuten.co.jp/engine/api/Travel/GetHotelChainList/20131024?applicationId=[アプリID]&format=xml
```

--------------------------------

### 楽天トラベルホテルチェーンAPIエラーレスポンス例 (404 Not Found)

Source: https://webservice.rakuten.co.jp/documentation/get-hotel-chain-list

楽天トラベルホテルチェーンAPIでデータが見つからなかった場合に返されるJSONレスポンス例です。HTTPステータスコード404と共に、`error`と`error_description`フィールドが含まれます。

```json
{
    "error": "not_found",
    "error_description": "not found"
}
```

--------------------------------

### GET /IchibaItem/Search

Source: https://webservice.rakuten.co.jp/documentation/ichiba-item-search

Search for items on Rakuten Ichiba with support for various filtering parameters and output customization.

```APIDOC
## GET /IchibaItem/Search

### Description
Search for items on Rakuten Ichiba. This endpoint supports filtering by affiliate rates, media availability, delivery options, and more.

### Method
GET

### Endpoint
/IchibaItem/Search

### Parameters
#### Query Parameters
- **minAffiliateRate** (float) - Optional - Minimum affiliate rate (1.0 to 99.9).
- **hasMovieFlag** (int) - Optional - 0: All, 1: Only products with movies.
- **pamphletFlag** (int) - Optional - 0: All, 1: Only products with pamphlets.
- **appointDeliveryDateFlag** (int) - Optional - 0: All, 1: Only products with specifiable delivery dates.
- **elements** (String) - Optional - Comma separated list of output fields to return.
- **genreInformationFlag** (int) - Optional - 0: Disable, 1: Enable genre item counts.
- **tagInformationFlag** (int) - Optional - 0: Disable, 1: Enable tag item counts.

### Response
#### Success Response (200)
- **count** (int) - Total number of items in search results.
- **page** (int) - Current page number.
- **hits** (int) - Number of results returned.
- **itemName** (string) - Name of the item.
- **itemPrice** (int) - Price of the item.
- **itemUrl** (string) - URL of the item.
- **affiliateUrl** (string) - Affiliate URL (if affiliateId provided).
- **smallImageUrls** (array) - Array of 64px square image URLs.
- **mediumImageUrls** (array) - Array of 128px square image URLs.

### Response Example
{
  "count": 150,
  "page": 1,
  "hits": 30,
  "Items": [
    {
      "itemName": "Example Product",
      "itemPrice": 2980,
      "itemUrl": "https://example.com/item",
      "availability": 1
    }
  ]
}
```

--------------------------------

### Error Handling

Source: https://webservice.rakuten.co.jp/documentation/books-book-search

Details the possible error responses from the API, including HTTP status codes and response body examples.

```APIDOC
## Error Handling

Error messages are displayed in the form of HTTP status code and its response body.

### Error Responses

- **400 Bad Request**: Parameter error or insufficient required parameters.
  - Example (missing `applicationId`):
    ```json
    {
        "error": "wrong_parameter",
        "error_description": "specify valid applicationId"
    }
    ```
  - Example (invalid `keyword`):
    ```json
    {
        "error": "wrong_parameter",
        "error_description": "keyword parameter is not valid"
    }
    ```
- **404 Not Found**: Data not found.
  - Example:
    ```json
    {
        "error": "not_found",
        "error_description": "not found"
    }
    ```
- **429 Too Many Requests**: The number of API requests has been exceeded.
  - Description: Please try accessing again after some time.
  - Example:
    ```json
    {
        "error": "too_many_requests",
        "error_description": "number of allowed requests has been exceeded for this API. please try again soon."
    }
    ```
- **500 Internal Server Error**: Internal error in Rakuten Web Service.
  - Description: An internal system error occurred. If the issue persists, please inquire via the provided link.
```

--------------------------------

### GET /books/search

Source: https://webservice.rakuten.co.jp/documentation/books-total-search

Searches for items within the Rakuten Books catalog based on keywords, ISBN/JAN codes, or genre IDs.

```APIDOC
## GET /books/search

### Description
Search for books, CDs, DVDs, and other media items. One of the following is required: search keyword, Rakuten Books genre ID, or ISBN/JAN code.

### Method
GET

### Endpoint
/books/search

### Parameters
#### Query Parameters
- **hits** (int) - Optional - Number of results per page (1-30, default: 30)
- **page** (int) - Optional - Result page number (1-100, default: 1)
- **availability** (int) - Optional - Availability filter (0-6)
- **outOfStockFlag** (int) - Optional - Include unavailable items (0: Exclude, 1: Include)
- **sort** (string) - Optional - Sort order (standard, sales, +releaseDate, -releaseDate, +itemPrice, -itemPrice, reviewCount, reviewAverage)
- **orFlag** (int) - Optional - AND/OR search flag (0: AND, 1: OR)
- **NGKeyword** (string) - Optional - Keywords to exclude from search results

### Request Example
GET /books/search?keyword=programming&hits=30&page=1

### Response
#### Success Response (200)
- **count** (int) - Total number of items found
- **page** (int) - Current page number
- **Items** (array) - List of item objects
- **title** (string) - Item title
- **isbn** (string) - ISBN code
- **itemPrice** (int) - Tax included price
- **itemUrl** (string) - URL to the item page

#### Response Example
{
  "count": 150,
  "page": 1,
  "Items": [
    {
      "title": "Example Book Title",
      "isbn": "9784000000000",
      "itemPrice": 2500,
      "itemUrl": "https://books.rakuten.co.jp/rk/example"
    }
  ]
}
```

--------------------------------

### 楽天トラベルホテルチェーンAPIリクエストURL例 (JSONP形式)

Source: https://webservice.rakuten.co.jp/documentation/get-hotel-chain-list

楽天トラベルホテルチェーンAPIを使用してホテルチェーンのリストをJSONP形式で取得するためのリクエストURLの例です。`applicationId`と`callback`パラメータを指定することでJSONP形式での出力が可能です。JSONPは、JSON形式で`callback`パラメータを指定することで出力されます。

```url
https://openapi.rakuten.co.jp/engine/api/Travel/GetHotelChainList/20131024?applicationId=[アプリID]&callback=functionName
```

--------------------------------

### Handle API Error Responses

Source: https://webservice.rakuten.co.jp/documentation/ichiba-item-ranking

Examples of JSON error responses returned by the API when parameters are invalid or missing. These responses include an error code and a descriptive message to assist in debugging.

```json
{
	"error": "wrong_parameter",
	"error_description": "keyword parameter is not valid"
}
```

```json
{
	"error": "wrong_parameter",
	"error_description": "must set age parameter in 20,30,40 when set period parameter"
}
```

--------------------------------

### 楽天トラベルホテルチェーンAPIレスポンス形式 (formatVersion=2)

Source: https://webservice.rakuten.co.jp/documentation/get-hotel-chain-list

楽天トラベルホテルチェーンAPIで`formatVersion=2`を指定した場合のJSONレスポンス形式の例です。`items`は配列で、各要素が直接`itemName`や`itemPrice`などのパラメータを含みます。`itemName`にアクセスするには`items[0].itemName`のような記法を使用します。この形式は`formatVersion=1`よりも改善されています。

```json
{
    "items": [
        {
            "itemName": "a",
            "itemPrice": 10
        },
        {
            "itemName": "b",
            "itemPrice": 20
        }
    ]
}
```

--------------------------------

### GET /Ichiba/Genre

Source: https://webservice.rakuten.co.jp/documentation/ichiba-genre-search

Retrieves genre information from the Rakuten Ichiba catalog, including root genres and specific genre details by ID.

```APIDOC
## GET /Ichiba/Genre

### Description
Fetches genre data from the Rakuten Ichiba service. This can be used to retrieve the root genre or specific genre details using a genre ID.

### Method
GET

### Endpoint
/Ichiba/Genre

### Parameters
#### Path Parameters
- **genre_id** (Integer) - Optional - The unique identifier for a specific genre.

### Request Example
```ruby
# Fetch root genre
root = RakutenWebService::Ichiba::Genre.root

# Fetch specific genre by ID
genre = RakutenWebService::Ichiba::Genre[100316]
```

### Response
#### Success Response (200)
- **id** (Integer) - The unique genre ID.
- **name** (String) - The display name of the genre.
- **children** (Array) - A list of sub-genre objects.

#### Response Example
{
  "id": 100316,
  "name": "水・ソフトドリンク"
}
```

--------------------------------

### GET /items/search

Source: https://webservice.rakuten.co.jp/documentation/ichiba-item-search

Retrieves a list of items from Rakuten Ichiba based on specified search parameters. At least one of keyword, genreId, itemCode, or shopCode is required.

```APIDOC
## GET /items/search

### Description
Search for items on Rakuten Ichiba. Requires at least one of the primary search identifiers (keyword, genreId, itemCode, or shopCode).

### Method
GET

### Endpoint
/items/search

### Parameters
#### Query Parameters
- **keyword** (String) - Optional - Search keyword (UTF-8 URL encoded)
- **itemCode** (String) - Optional - Unique item identifier (format: "shop:1234")
- **genreId** (long) - Optional - ID to specify a genre
- **tagId** (long) - Optional - Comma separated tag IDs (max 10)
- **hits** (int) - Optional - Results per page (1-30, default 30)
- **page** (int) - Optional - Result page (1-100, default 1)
- **sort** (String) - Optional - Sort order (e.g., +itemPrice, -reviewCount, standard)
- **minPrice** (long) - Optional - Minimum price
- **maxPrice** (long) - Optional - Maximum price
- **availability** (int) - Optional - 0: All, 1: Available only (default 1)
- **carrier** (int) - Optional - 0: PC, 1: Mobile, 2: Smartphone (default 0)
- **imageFlag** (int) - Optional - 0: All, 1: With images (default 0)
- **orFlag** (int) - Optional - 0: AND, 1: OR (default 0)
- **postageFlag** (int) - Optional - 0: All, 1: Free shipping (default 0)

### Request Example
{
  "keyword": "camera",
  "hits": 30,
  "page": 1,
  "sort": "-itemPrice"
}

### Response
#### Success Response (200)
- **items** (Array) - List of product objects
- **count** (int) - Total number of results

#### Response Example
{
  "items": [
    {
      "itemName": "Example Camera",
      "itemPrice": 50000,
      "itemCode": "shop:1234"
    }
  ]
}
```

--------------------------------

### Rakuten Books Total Search API - Error Handling

Source: https://webservice.rakuten.co.jp/documentation/books-total-search

Information on potential errors returned by the API, including HTTP status codes and response body examples.

```APIDOC
## Error Handling

### Description
Details on error responses from the Rakuten Books Total Search API, including status codes and example error messages.

### Method
N/A (Applies to all requests)

### Endpoint
N/A

### Error Responses
#### 400 Bad Request
- **Description**: Parameter error or insufficient required parameters.
- **Response Body Example**: 
```json
{
    "error": "wrong_parameter",
    "error_description": "specify valid applicationId"
}
```

#### 404 Not Found
- **Description**: Data not found.
- **Response Body Example**: 
```json
{
    "error": "not_found",
    "error_description": "not found"
}
```

#### 429 Too Many Requests
- **Description**: Exceeded the API request limit.
- **Response Body Example**: 
```json
{
    "error": "too_many_requests",
    "error_description": "number of allowed requests has been exceeded for this API. please try again soon."
}
```

#### 500 Internal Server Error
- **Description**: Internal system error within Rakuten Web Service.
- **Response Body Example**: 
```json
{
    "error": "system_error",
    "error_description": "api logic error"
}
```

#### 503 Service Unavailable
- **Description**: Service unavailable due to maintenance or overload.
- **Response Body Example**: 
```json
{
    "error": "service_unavailable",
    "error_description": "XXX/XXX is under maintenance"
}
```

### Response Body Format
- **json**: 
```json
{
    "error": "wrong_parameter",
    "error_description": "page must be a number"
}
```
- **xml**: 
```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <error>wrong_parameter</error>
    <error_description>page must be a number</error_description>
</root>
```
```

--------------------------------

### Generate Affiliate URL

Source: https://webservice.rakuten.co.jp/documentation/ichiba-item-ranking

Constructs an affiliate link by combining the Affiliate ID with encoded PC and mobile item URLs. This allows developers to track referrals and earn commissions via the Rakuten Affiliate program.

```text
http://hb.afl.rakuten.co.jp/hgc/[Affiliate ID]/?pc=[Item URL(PC)]&m=[Item URL(mobile)]
```

--------------------------------

### Construct Rakuten Affiliate URL

Source: https://webservice.rakuten.co.jp/documentation/books-total-search

Manually construct an affiliate URL using the item URL and affiliate ID. The item URL must be URL encoded before being used in the construction. This method is useful when the affiliate ID is obtained separately.

```text
https://hb.afl.rakuten.co.jp/hgc/[Affiliate]/?pc=[Item URL(PC)]&m=[Item URL(mobile)]
```

--------------------------------

### Handle API Error Responses

Source: https://webservice.rakuten.co.jp/documentation/ichiba-genre-search

Examples of JSON error response bodies returned by the API for various HTTP status codes including 400, 404, 429, 500, and 503.

```json
{
    "error": "wrong_parameter",
    "error_description": "specify valid applicationId"
}
```

```json
{
    "error": "not_found",
    "error_description": "not found"
}
```

```json
{
    "error": "too_many_requests",
    "error_description": "number of allowed requests has been exceeded for this API. please try again soon."
}
```

```json
{
    "error": "system_error",
    "error_description": "api logic error"
}
```

```json
{
    "error": "service_unavailable",
    "error_description": "XXX/XXX is under maintenance"
}
```

--------------------------------

### Rakuten Books API Error: Parameter Error

Source: https://webservice.rakuten.co.jp/documentation/books-book-search

This error occurs when required parameters are missing or invalid. For example, if the 'applicationId' is not set or the 'keyword' parameter is not valid (e.g., only one character).

```json
{
    "error": "wrong_parameter",
    "error_description": "specify valid applicationId"
}
```

```json
{
    "error": "wrong_parameter",
    "error_description": "keyword parameter is not valid"
}
```

--------------------------------

### 楽天トラベルホテルチェーンAPIエラーレスポンス例 (400 Bad Request)

Source: https://webservice.rakuten.co.jp/documentation/get-hotel-chain-list

楽天トラベルホテルチェーンAPIでパラメータエラーが発生した場合のJSONレスポンス例です。`_applicationId`が設定されていない場合や、`keyword`パラメータが無効な場合に返されます。エラーメッセージには`error`と`error_description`が含まれます。

```json
{
    "error": "wrong_parameter",
    "error_description": "specify valid applicationId"
}
```

--------------------------------

### JSON Error Response Example

Source: https://webservice.rakuten.co.jp/documentation/books-software-search

This snippet shows a typical JSON error response from the Rakuten Ichiba API, indicating that a service is unavailable due to maintenance. This format is commonly used for API errors.

```json
{
    "error": "service_unavailable",
    "error_description": "XXX/XXX is under maintenance"
}
```

--------------------------------

### 楽天トラベルホテルチェーンAPIレスポンス形式 (formatVersion=1)

Source: https://webservice.rakuten.co.jp/documentation/get-hotel-chain-list

楽天トラベルホテルチェーンAPIで`formatVersion=1`を指定した場合のJSONレスポンス形式の例です。`items`は配列で、各要素は`item`オブジェクトを含み、その中に`itemName`や`itemPrice`などのパラメータが含まれます。`itemName`にアクセスするには`items[0].item.itemName`のような記法を使用します。

```json
{
    "items": [
        {
            "item": {
                "itemName": "a",
                "itemPrice": 10
            }
        },
        {
            "item": {
                "itemName": "b",
                "itemPrice": 20
            }
        }
    ]
}
```