Home      API     Ichiba Genre Search API 2

The Rakuten Genre Search API can retrieve genre names and their structure that are used in Rakuten Ichiba. Developers can retrieve the genre information using Genre ID.

Endpoint (REST/JSON format)


https://app.rakuten.co.jp/services/api/IchibaGenre/Search/20120723?[parameter]=[value]…

*The JSONP format allows a JavaScript callback function to be specified as an input parameter.

The request URL below can be used, in order to retrieve the first level in a genre list. (In a real use, please combine the request URL into one line.) 

https://app.rakuten.co.jp/services/api/IchibaGenre/Search/20120723?
applicationId=[APPLICATION ID]&
genreId=0

*If many accesses to an identical URL are made in a short time, the URL may be become unresponsive for a fixed period of time. Please take care during testing.

To the top of the page

Input Parameters


Rakuten Ichiba Genre Search API 2 Input parameters version:2012-07-23

ID Item name Parameter Type (maximum bytes in parentheses) Required Default Comment
Division: Shared parameters
1 App ID applicationId String 必須 - Check here
2 Affiliate ID affiliateId String - - Check here
3 Response format format String - json Either JSON or XML
When JSON is specified the callback parameter can also be set in order to use JSONP.
4 Callback function name callback String - - Function name to be used with the JSONP output
(UTF-8 URL encoded string)
Alphanumeric characters, periods, or underscores
5 Choosing output fields elements String - - By default, API response all of the fields. You can change response fields by this parameter.
This parameter's data is separated by comma(,).
For example, following request will response only itemName, itemPrice and itemUrl.
elements=itemName,itemPrice,itemUrl
6 Format version formatVersion int - 1

Response format version.

If formatVersion=2 is set, the response format (JSON) will be improved.

In case of formatVersion=1 :
Our API response will be returned in Array format as the followings.
You would need to use notation items[0].item.itemName To access itemName parameter. 

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

In case of formatVersion=2 :
Our API response will be returned in Array format as the followings.
You can use notation items[0].itemName To access itemName parameter. 

{"items": [
    {
        "itemName": "a",
        "itemPrice": 10
    },
    {
        "itemName": "b",
        "itemPrice": 20
    }
]}
Division : service specific parameters
1 Genre ID genreId int 必須
 - Use genreId=0 to search from the genre root
2 Genre path genrePath int(1) - 1 0: Exclude ancester genres
1: Display ancester genres
Ancestor genres are a set of genres in the upper levels (parent, grandparent, etc.)
To the top of the page

Output parameters


Rakuten Ichiba Genre Search API 2 Output Parameters version:2012-07-23

Division : service specific parameters
1 Parent genre Parent genre parents Inputted genre Id's parent genres
When genrePath=1 is set, the output will include ancestor genres. Ancester genres are displayed as "<parent>~ </parent>" and are listed inside "<parents>~ </parents>" tag.
2 Genre ID genreId Genre ID
3 Genre name genreName Genre name
4 Genre level genreLevel Genre level , use 0 to search at the genre root
5 Current genre Current genre current Genre ID from the input paramter
6 Current ID genreId Current ID
7 Current name genreName Current name
8 Current level genreLevel Current level
9 Child genre Child genre children Inputted genre Id's child genres
Child genres are displayed as "<child>~ </child>" and are listed inside "<children>~ </children>" tag
If genreId=0 is set, all genres that have genreLevel=1 will be listed as "<children>~ </children>"
10 Current ID genreId Current ID
11 Current name genreName Current name
12 Current level genreLevel Current level
To the top of the page

Error

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

HTTP Status Code Description Response body example (JSON)
400 Parameter error (or required parameters were insufficient)

If applicationId is not set

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

If keyword is not valid (only 1 character given, etc.)

{
    "error": "wrong_parameter",
    "error_description": "keyword parameter is not valid"
}
404 If data not found. 
{
    "error": "not_found",
    "error_description": "not found"
}
429 Too many requests

This error will be displayed if the number of API requests has been exceeded.
Please try access again after an amount of time.

{
    "error": "too_many_requests",
    "error_description": "number of allowed requests has been exceeded for this API. please try again soon."
}
500 Internal error in Rakuten Web Service

An internal system error occured. If you continue seeing this message for a long period, please give your inquiry via this link

{
    "error": "system_error",
    "error_description": "api logic error"
}
503 Unavailable due to maintenance or overloaded

Maintenance (the API name will be displayed in XXX/XXX)

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

Response body format is display in format.

format Error output example
json 
{
    "error": "wrong_parameter",
    "error_description": "page must be a number"
}
xml 
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <error>wrong_parameter</error>
    <error_description>page must be a number</error_description>
</root>
To the top of the page

Using the SDK to retrieve data

You can use the SDK publicly released by Rakuten Web Services to retrieve data as follows. 

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

$client = new RakutenRws_Client();
// Set the application ID (developer ID)
$client->setApplicationId('YOUR_APPLICATION_ID');

// To use Rakuten Ichiba Genre Search API specify 'IchibaGenreSearch'.
// Here genreId is set to 0 as an example.
$response = $client->execute('IchibaGenreSearch', array(
    'genreId => 0
));

// You can use the isOk() method to check the validity of the response.
if ($response->isOk()) {
    foreach ($response['children'] as $childGenre) {
        $genre = $childGenre['child'];

        // print out the genre name
        echo $genre['genreName']."\n";
    }
} else {
    // You can retrieve response messages by using getMessage()
    echo 'Error:'.$response->getMessage();
}
To the top of the page
> How to develop