Endpoint

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

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

The values for the field names keyword and sort must be URL encoded in UTF-8 style.
(The whole request does not need to be encoded, only the individual value portions of it)
For example, a keyword search for "福袋" that has been ordered with the cheapest item first (sort=+itemPrice) will look like the URL below. (Don't add line breaks when actually making the request. Instead the pieces of the request should be connected together.)

Input parameters

Rakuten Ichiba Item Search 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	Search keywords	keyword	String	(*1)	-	UTF-8 URL encoded string The keyword parameter can have a maximum length of 128 single byte characters The keyword parameter is delimited with single byte space characters. This defaults to an AND operation including all the keywords. To use OR instead set the orFlag to 1. Each search keyword must be at least two single byte characters or one double byte character. An exception is a minimum of two characters if the search keywords are using hiragana, katakana, or symbols. (*1) One of the following is required: search keyword, genre ID, item code, or shop code.
2	Shop code	shopCode	String	(*1)	-	The portion of the shop URL listed as "xyz": http://www.rakuten.co.jp/[xyz] (*1) One of the following is required: search keyword, genre ID, item code, or shop code.
3	Item code	itemCode	String	(*1)	-	Included in the output parameters of the Item Search, Item Ranking APIs. A value in the form of "shop:1234" (*1) A search request must contain either a keyword, a genre ID, or an item code.
4	Genre ID	genreId	long	(*1)	0	ID to specify a genre in Rakuten Ichiba Please use the Rakuten Ichiba Genre Search API 2 to look up genre names and genre relations. (*1) One of the following is required: search keyword, genre ID, item code, or shop code.
5	Tag ID	tagId	long	-	-	Comma separated (maximum 10 IDs) ID to specify a tag in Rakuten Ichiba.
6	How many results to display on each page	hits	int	-	30	An integer between 1 and 30
7	Result page	page	int	-	1	An integer between 1 and 100
8	Sort	sort	String	-	standard	+affiliateRate： Affiliate Rate ( Ascending order ) -affiliateRate： Affiliate Rate ( Descending order ) +reviewCount： Number of reviews ( Ascending order ) -reviewCount： Number of reviews ( Descending order ) +reviewAverage： Average review rating ( Ascending order ) -reviewAverage： Average review rating ( Descending order ) +itemPrice： Price ( Ascending order ) -itemPrice： Price ( Descending order ) +updateTimestamp： Time of item update ( Ascending order ) -updateTimestamp： Time of item update ( Descending order ) standard： Rakuten standard sort *UTF-8 URL encoding is required.
9	Minimum price	minPrice	long	-	-	An integer greater than 0 and less than 999,999,999
10	Maximum price	maxPrice	long	-	-	An integer greater than 0 and less than 999,999,999 maxPrice must be larger than minPrice.
11	Availability	availability	int(1)	-	1	0: All products 1: Only available products
12	Search field	field	int(1)	-	1	0: Broad search (prefer more matches with the same keyword) 1: Restricted search (prefer fewer matches with the same keyword)
13	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
14	Has image flag	imageFlag	int(1)	-	0	0: Search all products 1: Search only products with images
15	OR search flag	orFlag	int(1)	-	0	Choose between AND searches and OR searches when there are multiple keywords. 0: AND 1: OR *It isn't possible to use a complex search condition like "(A and B) or C".
16	Excluded keywords	NGKeyword	String	-	-	Words to exclude from search results Strings encoded with UTF-8 URL encoding Same format as keyword
17	Purchase type	purchaseType	int(1)	-	0	Narrow search by purchase type 0: Normal purchase 1: Periodic purchase (a service that allows customers to buy goods they choose on a cycle they specify). 2: Distribution group purchase (a service that allows the shop to choose items and also choose the number of times they are delivered).
18	Overseas shipping flag	shipOverseasFlag	int(1)	-	0	0: All products 1: Only products that can be shipped overseas
19	Overseas shipping area	shipOverseasArea	String	-	ALL	It is possible to restrict searches based on delivery areas. Check the overseas delivery area codes *shipOverseasFlag must be 1
20	Asuraku flag	asurakuFlag	int(1)	-	0	0: All products 1: Only items that can use the Asuraku service
21	Asuraku area	asurakuArea	int	-	0	It is possible to restrict searches based on delivery areas. Check the Asuraku delivery area codes *asurakuFlag must be 1
22	Point multiplier flag	pointRateFlag	int(1)	-	0	0: All products 1: Only items with point multipliers
23	Point multiplier	pointRate	int	-	-	An integer from 2 to 10 (e.g. 5 means points will be multiplied by five) Read about point multipliers. *pointRateFlag must be 1
24	Postage flag	postageFlag	int(1)	-	0	0: All products 1: Only items with postage included/free shipping
25	Credit card flag	creditCardFlag	int(1)	-	0	0: All products 1: Only products purchaseable with credit cards
26	Giftwrap flag	giftFlag	int(1)	-	0	0: All products 1: Only products with giftwrapping available
27	Has review flag	hasReviewFlag	int(1)	-	0	0: All products 1: Only products with reviews
28	Maximum affiliate rate	maxAffiliateRate	float	-	-	A number from 1.0 to 99.9 (e.g. 5.0 for products with an affiliate rate up to 5%). Don't show if the affiliate rate is higher than specified. Up to one decimal place can be specified.
29	Minimum affiliate rate	minAffiliateRate	float	-	-	A number from 1.0 to 99.9 (e.g. 5.0 for products with an affiliate rate above 5%). Don't show if the affiliate rate is lower than specified. Up to one decimal place can be specified. Specify an affiliate rate lower than the maximum rate.
30	Has movie flag	hasMovieFlag	int(1)	-	0	0: All products 1: Only products with movies (the link to the movies will be returned)
31	Pamphlet flag	pamphletFlag	int(1)	-	0	0: All products 1: Only products with pamphlets
32	Specify delivery date flag	appointDeliveryDateFlag	int(1)	-	0	0: All products 1: Only products for which the delivery date can be specified.
33	Output elements	elements	String	-	ALL	Comma separated. When required output parameters are specified, only those parameters will be returned. (e.g elements=reviewCount,reviewAverage)
34	Genre information flag	genreInformationFlag	int(1)	-	0	0: Do not get number of item in each genre. 1: Get number of item in each genre.
35	Tag information flag	tagInformationFlag	int(1)	-	0	0: Do not get number of item in each tag. 1: Get number of item in each tag.

Output Parameters

Rakuten Ichiba Item Search API version:2022-06-01

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 the Item Search 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.

When the affiliateId input parameter is included in the request the response from the API will include the affiliate URL.

Error

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

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

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

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

{
    "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 Search API specify 'IchibaItemSearch'.
// Here 'udon' is used as an example keyword.
$response = $client->execute('IchibaItemSearch', array(
  'keyword' => 'udon'
));

// You can use the isOk() method to check the validity of the response.
if ($response->isOk()) {
    // It is possible to access the returned information through arrays.
    echo "Found ".$response['count']." matches\n";

    // A foreach loop can be used to iterate through the results.
    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

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

Old Versions

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

• Version : 2017-07-06