Home     API      Rakuten Ichiba Item Ranking API 2

Version: 2022-06-01 is the latest version with specification changes on February 16, 2023.
Changes: The output parameters marked with【NEW】were added.

The Rakuten Item Ranking API can acquire data from the "Ichiba Ranking" section within Rakuten Ichiba.
Developers can acquire sales data divided by genre, gender, or age category.
This new version of the Rakuten Item Ranking API adds the ability to retrieve three item images as well as data on up to a maximum 1000 ranks.

Endpoint


https://app.rakuten.co.jp/services/api/IchibaItem/Ranking/20220601?[parameter]=[value]…

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

Three request examples are given below. (Don't add line breaks when actually making the request. Instead the pieces of the request should be connected together.)

(1) To get all the ranking information. (no service specific parameters used)
https://app.rakuten.co.jp/services/api/IchibaItem/Ranking/20220601?
applicationId=[application ID]

(2) To get the ranking information for "western sweets (genreId=100283)." (uses a genre specific parameter)
https://app.rakuten.co.jp/services/api/IchibaItem/Ranking/20220601?
applicationId=[application ID]
&genreId=100283

(3) To get the ranking information for "women in their 20s." (uses age and gender parameters)
https://app.rakuten.co.jp/services/api/IchibaItem/Ranking/20220601?
applicationId=[application ID]
&age=20
&sex=1

*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.

Important points to remember


*Items to be aware of regarding input parameters (as of October, 2012)
When retrieving ranking data, service specific parameters such as genre ID, gender, and age group can be specified.

(1) "Genre ID"
When the genre ID is the only parameter specified, the ranking information for that genre will be shown.
Genre ID cannot be used together with the age group or gender parameters.

(2) "Age group" When the age group is the only specified parameter, all the ranking information from each age group will be shown.
The age group parameter can be used together with the gender parameter. When they are both specified, the ranking information for the relevant age group of the given gender will be shown.

(3) "Gender"
When the gender is the only specified parameter, all the ranking information from each gender will be shown.
The age group parameter can be used together with the gender parameter. When they are both specified, the ranking information for the relevant age group of the given gender will be shown.

(4) All ranking data is shown when no parameters are specified.

*The ranking information shown may partly differ from the "Ranking Ichiba" in the order and total count.
The data retrieved is the same as on "Ranking Ichiba" but if an item listed in the ranking has for some reason had its item page deleted then this API will skip over that number in the ranking results returned. Therefore please be aware that sometimes the total numbers may differ from the "Ranking Ichiba."

Input parameters


Rakuten Ichiba Ranking API 2 Input parameters version:2022-06-01

ID Parameter 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 long (*1)(*2) - The ID for specifying the genres used in Rakuten Ichiba
If it is necessary to lookup genre names and genre relationships, please use the Rakuten Genre search API (GenreSearch).
(*1) If no value for genre ID, gender, or age group is specified, all ranking information will be shown.
(*2) For other input parameter settings, please check the section on this page labeled "Items to be aware of regarding input parameters."
2 Age group based age int (*1)(*2)(*3) - 10: 10-19
20: 20-29
30: 30-39
40: 40-49
50: 50 and up
(*1) If no value for genre ID, gender, or age group is specified, all ranking information will be shown.
(*2) Age grouping and gender specifications can be used simultenously.
(*3) For other input parameter settings, please check the section on this page labeled "Items to be aware of regarding input parameters."
3 Gender based sex int (*1)(*2)(*3) 0 0: Male
1: Female
(*1) If no value for genre ID, gender, or age group is specified, all ranking information will be shown.
(*2) Age grouping and gender specifications can be used simultenously.
(*3) For other input parameter settings, please check the section on this page labeled "Items to be aware of regarding input parameters."
4 Platform carrier int(1) - 0 Choose the target platform for type of information to return: PC or mobile
PC: 0
mobile: 1
5 Page number page int - 1 An integer between 1 and 34
*It is possible to specify rankings below 30th place.
6 Period for ranking period string - - realtime: retrieve data in real time

Output Parameters


Rakuten Ichiba Ranking API 2 Output parameters version:2022-06-01

ID General description Specific description Item name Parameter Comment
Division : service specific parameters
1 Overall information Ranking title title  
2 Time of last update lastBuildDate  
3 Item information
(Overall:
<Items>...</Items> Individual item:
<Item>...</Item>)
Item detail Rank rank  
4 Platform carrier PC: 0
mobile: 1
5 Item name itemName To display the usual name please use catchcopy+itemname.
*Depending on the setting for carrier the results may vary.
6 Sales message catchcopy
7 Item code itemCode  
8 Item price itemPrice  
9 Item price basefield【NEW】 itemPriceBaseField Contains one of the following strings
"item_price_min1", "item_price_min2" or "item_price_min3"
10 Item price max1【NEW】 itemPriceMax1 All item price max
11 Item price max2【NEW】 itemPriceMax2 Searchable item price max
12 Item price max3【NEW】 itemPriceMax3 Purchasable item price max
13 Item price min1【NEW】 itemPriceMin1 All item price min
14 Item price min2【NEW】 itemPriceMin2 Searchable item price min
15 Item price min3【NEW】 itemPriceMin3 Purchasable item price min
16 Has price range【NEW】 hasPriceRange 0-No price range
1-Display price range
17 Item caption itemCaption *Depending on the setting for carrier the results may vary.
18 Item URL itemUrl *Depending on the setting for carrier the results may vary.

*Depending on the setting for carrier the results may vary. If you include affiliateId in the input parameter, itemUrl will be same as that of affiliateUrl.(From 2015/7/1)
URL for each item, starting with https.
19 Affiliate URL affiliateUrl (Only when the Affiliate ID has been included as an input parameter)
*Returns a URL regardless of the value of carrier
Affiliate URL, starting with https.
20 Has image flag imageFlag 0: Items without images
1: Items with images
21 64 pixel square item image URL smallImageUrls Returns an array of up to three image URLs. Images size is 64 pixels square.
Small Image URL (64x64), starting with https.
22 128 pixel square item image URL mediumImageUrls Returns an array of up to three image URLs. Images size is 128 pixels square.
Medium Image URL (128x128), starting with https.
23 Availability flag availability 0: Out of stock
1: Available
24 Tax flag taxFlag 0: Tax included
1: Tax not included
25 Postage flag postageFlag 0: Postage included
1: Postage not included
26 Credit card flag creditCardFlag 0: Credit cards not accepted
1: Credit cards accepted
27 Shop of the Year flag shopOfTheYearFlag 0: Shops that have not won Shop of the Year
1: Shops that have won Shop of the Year
28 Overseas shipping flag shipOverseasFlag 0: Products that cannot be shipped overseas
1: Products that can be shipped overseas
29 Overseas shipping area shipOverseasArea Supported countries are shown, separated by slashes. (/)
30 Asuraku flag asurakuFlag 0: No next day delivery
1: Next day delivery possible
*Starting July 1st onwards, the parameter "asurakuFlag" will always be set to the value of "0".
*Read more about Asaraku
31 Asaraku closing time asurakuClosingTime Returned value takes this form: "HH:MM"
*Is only returned when asarakuFlag is set to 1
32 Asuraku delivery area asurakuArea Supported areas are shown, separated by slashes. (/)
*asurakuFlag must be 1 for this to be returned.
33 Affiliate rate affiliateRate  
34 Sale start time startTime Only when a time limited sale has been set.
(format is "YYYY-MM-DD HH:MM")
35 Sale end time endTime Only when a time limited sale has been set.
(format is "YYYY-MM-DD HH:MM")
36 Review count reviewCount  
37 Average review reviewAverage  
38 Item point multiplier pointRate (e.g. 5 for a point multiplier of "5 times points."
Read more about item-based point multipliers. *Only shows information for point multipliers that will not end within 24 hours.
39 Start of item point multiplier pointRateStartTime Date and time of the start of the item-based point multiplier.
*Only shows information for point multipliers that will not end within 24 hours.
40 End of item point multiplier pointRateEndTime Date and time of the end of the item-based point multiplier.
*Only shows information for point multipliers that will not end within 24 hours.
41 Shop info Shop name shopName  
42 Shop code shopCode The portion marked "xyz" in each shop's URL: http://
www.rakuten.co.jp/[xyz]
43 Shop URL shopUrl URL for each shop, starting with https.

*If you include affiliateId in the input parameter, shopUrl will be same as that of shopAffiliateUrl.(From 2015/7/1)
44 Genre information Genre information Genre ID genreId  

About Item Based Point Multipliers


With a regular purchase, 1% of the total cost will be credited as Rakuten Points. However "point multipliers" can be set for individual items for a limited period of time, multiplying the amount of Points credited with each purchase. Read more about point multipliers.

There are currently two different ways for point multipliers to be used by the shops. Item based point multipliers apply only to specially selected items in a given shop. Shop based multipliers apply to every item in a specially selected shop. Currently this API only supports item based point multipliers.

About Affiliate Commissions


Developers can use Rakuten Item Ranking API to make affiliate links from the returned item information. It's possible to receive affiliate commission from Rakuten Affiliate when the affiliate URL is used as the link. The steps for making the affiliate link are the same whether the carrier input parameter is PC or mobile.

(1) If [Affiliate ID] is given in the API input parameters, [Affiliate URL] will be included in the API output parameters.

(2) Developers may use the following rule to manually create [Affiliate URL] by using [Item URL] and [Affiliate ID (Beta version)] retrieve from the API. The [Item URL] needs to be encoded.

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

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 keyword is not valid (only 1 character given, etc.)

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

If genreId is not set, and both sex and period are set, and age is out of the range[20,30,40]

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

If both genreId and sex are set

{
	"error": "wrong_parameter",
	"error_description": "no permit setting genreId and sex parameter at the same time"
}

If both genreId and age are set

{
	"error": "wrong_parameter",
	"error_description": "no permit setting genreId and age parameter at the same time"
}
404 Data not found

If no data found

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

If the item's count of Ranking information is less than 3

{
    "error": "not_found",
    "error_description": "This genre data does not exist"
}
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>

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 Item Ranking API specify 'IchibaItemRanking'.
// Here 'udon' is used as an example keyword.
$response = $client->execute('IchibaItemRanking', array(
  'genreId' => '100227'
));

// You can use the isOk() method to check the validity of the response.
if ($response->isOk()) {
    // access information in the response array
    echo $response['title']."ranking title\n";

    // use foreach loop to get item's information
    foreach ($response as $item) {
        echo $item['itemName']."\n";
    }
} else {
    // You can retrieve response messages by using getMessage()
    echo 'Error:'.$response->getMessage();
}

Old Versions


For old versions of this API, please refer to the list below.