Endpoint

https://app.rakuten.co.jp/services/api/IchibaItem/Ranking/20170628?[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.)

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:2017-06-28

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, mobile, or smartphone PC: 0 mobile: 1 (*Japan only) smartphone: 2
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:2017-06-28

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

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

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

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

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

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

{
    "error": "not_found",
    "error_description": "This genre data does not exist"
}

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

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

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

Response body format is display in format.

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

<?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();
}

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) # 30代男性 のランキングTOP 30
RakutenWebService::Ichiba::Genre[100316].ranking # "水・ソフトドリンク" ジャンルのTOP 30