Home API Ichiba Item Search API

The Rakuten Item Search API can retrieve data from items listed on Rakuten Ichiba. Excluded items include those co-listed, listed in auctions, listed in flea markets, or listed in customer to customer auctions (C2C). Developers can begin searching by keyword and then limit the results by shop or genre information.
This API improves on the old Rakuten Item Search API by allowing specification of output parameters, searching by item code, searching by existance of reviews, searching by whether delivery times can be specified, and other options.

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

https://app.rakuten.co.jp/services/api/IchibaItem/Search/20220601?
applicationId=[APPLICATION ID]
&keyword=%E7%A6%8F%E8%A2%8B
&sort=%2BitemPrice

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

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
*Starting July 1st onwards, the parameter "asurakuFlag" will always be set to the value of "0".
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

ID General description Specific description Item name Parameter Comment
Division : service specific parameters
1 Overall information Search count count Total number of items in the search results
2 Page number page Current page number
3 First page first Result number to display from
4 Last page last Result number to display until
5 Search hits hits Number of results to return
6 Platform carrier PC: 0
mobile: 1 (*Japan only)
smartphone: 2
7 Total page count pageCount Maximum of 100
8 Item information
(Overall:
... Individual item:
... )
Item detail Item name itemName To display the usual name please use catchcopy+itemname.
*Depending on the setting for carrier the results may vary.
9 Sales message catchcopy
10 Item code itemCode
11 Item price itemPrice
12 Item caption itemCaption *Depending on the setting for carrier the results may vary.
13 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.
14 Item price basefield【NEW】 itemPriceBaseField Contains one of the following strings
"item_price_min1", "item_price_min2" or "item_price_min3"
15 Item price max1【NEW】 itemPriceMax1 All item price max
16 Item price max2【NEW】 itemPriceMax2 Searchable item price max
17 Item price max3【NEW】 itemPriceMax3 Purchasable item price max
18 Item price min1【NEW】 itemPriceMin1 All item price min
19 Item price min2【NEW】 itemPriceMin2 Searchable item price min
20 Item price min3【NEW】 itemPriceMin3 Purchasable item price min
21 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
22 Has image flag imageFlag 0: Items without images
1: Items with images
23 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.
24 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.
25 Availability flag availability 0: Out of stock
1: Available
26 Tax flag taxFlag 0: Tax included
1: Tax not included
27 Postage flag postageFlag 0: Postage included
1: Postage not included
28 Credit card flag creditCardFlag 0: Credit cards not accepted
1: Credit cards accepted
29 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
30 Overseas shipping flag shipOverseasFlag 0: Products that cannot be shipped overseas
1: Products that can be shipped overseas
31 Overseas shipping area shipOverseasArea Supported countries are shown, separated by slashes. (/)
32 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
33 Asaraku closing time asurakuClosingTime Returned value takes this form: "HH:MM"
*Is only returned when asarakuFlag is set to 1
34 Asuraku delivery area asurakuArea Supported areas are shown, separated by slashes. (/)
*asurakuFlag must be 1 for this to be returned.
35 Affiliate rate affiliateRate
36 Sale start time startTime Only when a time limited sale has been set.
(format is "YYYY-MM-DD HH:MM")
37 Sale end time endTime Only when a time limited sale has been set.
(format is "YYYY-MM-DD HH:MM")
38 Review count reviewCount
39 Average review reviewAverage
40 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.
41 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.
42 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.
43 Gift wrap flag giftFlag 0: Gift wrap service unavailable
1: Gift wrap service available
44 Shop info Shop name shopName
45 Shop code shopCode The portion marked "xyz" in each shop's URL: http://
www.rakuten.co.jp/[xyz]
46 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)
47 Shop Affiliate URL shopAffiliateUrl (Only when the Affiliate ID has been included as an input parameter)
*Returns a URL regardless of the value of carrier
Shop Affiliate URL, starting with https
48 Genre information Genre information Genre ID genreId
49 Tag information Tag information Tag ID tagIds Multiple tag IDs are returned as an array
50 Number of items in each genre.

Parent Genre - parent
51 Genre ID genreId
52 Genre name genreName
53 Genre level genreLevel
54 Current genre - current Genre ID from the input parameter
55 Genre ID genreId
56 Genre name genreName
57 Item count itemCount Number of item in this genre
58 Genre Level genreLevel
59 Child genre - child Inputted genre Id's child genres
Child genres are displayed as " ~ " and are listed inside " ~ " tag
If genreId=0 is set, all genres that have genreLevel=1 will be listed as " ~ "
60 Genre ID genreId
61 Genre name genreName
62 Item count itemCount Number of item in this genre
63 Genre level genreLevel
64 Number of items in each tag.
( <TagInformation>
~ </TagInformation> 、
<tagGroupt> ~ </tagGroup>
<tagst> ~ </tags>
Tag group information - tagGroup Tag group information display tag group information that is binded with genre ID.
This information would not be returned if the genre ID is 0 or not specified.
65 Tag group name tagGroupName
66 Tag group ID tagGroupId
67 Tag group information - tags are listed inside
68 Tag ID tagId
69 Tag name tagName
70 Parent tag ID parentTagId
71 Number of items in each tag. itemCount

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

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>

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

Old Versions


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