datawebotRakuten Ichiba API: item fields, variants and ranking
A source-attributed guide to Rakuten Ichiba Item Search and Ranking API scope, identifiers, price fields, variant limits and search differences.
Rakuten Ichiba Item Search covers a defined set of listings
Source review: 2026-10-07 (Singapore). This page covers product listings represented by Rakuten Web Service for Rakuten Ichiba, the Japanese marketplace associated with rakuten.co.jp. The currently displayed Item Search specification is version 2026-07-01. Its coverage and exclusions belong to this API, not to every Rakuten Group property.
Scroll to compare →
| Scope | Rakuten Web Service documentation | Keep the boundary clear |
|---|---|---|
| Marketplace | Rakuten Ichiba item listings returned by its Item Search API. | Do not treat this endpoint as a catalog for every Rakuten service or merchant tool. |
| Excluded listing types | The documentation excludes co-listed items, auctions, flea-market listings and customer-to-customer auctions. | A missing API result does not establish that an item is absent across Rakuten properties. |
| Separate Rakuten services | The API catalog lists distinct Ichiba, Books, Travel, Recipe, Kobo and GORA APIs, and separately describes product search. | Keep this page scoped to Ichiba Item Search and its related Ichiba endpoints. |
| Version context | The reviewed Item Search page displays version 2026-07-01. | Recheck the official version page before relying on version-specific fields or parameters. |
A listing joins to its shop and genre through source IDs
The API distinguishes a shop-scoped listing from its merchant and catalog context. Rakuten defines shopCode from the shop URL and itemCode in a shop:item-id form. Genre and attribute identifiers describe Ichiba taxonomy; they do not create a universal manufacturer SKU or a complete option tree.
Scroll to compare →
| Field or identifier | What Rakuten documents | Modeling boundary |
|---|---|---|
| shopCode | The shop-name portion of a Rakuten shop URL. | Keep it with the listing; it is not a product identifier or seller-account key. |
| itemCode | An item code in a shop-scoped form such as shop:1234. | Treat it as a marketplace listing key, not a cross-merchant manufacturer SKU. |
| genreId | An identifier for a Rakuten Ichiba genre; Genre Search documents names and relationships. | Preserve genre context rather than flattening it into a universal category. |
| attributeIds and attributes | The item response can include attribute IDs; the documented attributes array is returned when requested, and Attribute Search provides attribute references. | Do not infer missing option values, size/color variants or per-option prices from taxonomy fields. |
| itemName and catchcopy | The Item Search page recommends combining these separate fields for a usual displayed name. | Keep the source fields distinct when retaining provenance. |
| hits and page | The current specification allows 1–30 results per page and page numbers 1–100. | A bounded response page is not a complete merchant catalog. |
The documented item response has no SKU option-price matrix
Rakuten Help updated its size/color and per-SKU price answers on March 25, 2024. It says Item Search output does not provide color or size, and does not provide a separate price for each SKU. The legacy tagId example on the size/color help page uses a 2017 endpoint; tagId is not listed in the Item Search parameter table reviewed for version 2026-07-01.
Scroll to compare →
| Question | First-party answer | What the evidence supports |
|---|---|---|
| Does Item Search return size or color? | Rakuten Help says these are not available in Item Search output. | Do not synthesize a complete option set from item names, descriptions or attributes. |
| Does it return price for each SKU? | Rakuten Help says the API can return minimum and maximum prices but not prices by SKU. | Keep the documented item-level ranges separate from selected-option prices. |
| Can tagId be treated as a current filter? | The 2024 Help example uses tagId with the legacy 20170706 endpoint; the reviewed 2026-07-01 parameter list does not include tagId. | Do not present the legacy request example as a verified current parameter. |
| Do attribute IDs fill the gap? | The current docs describe genre/attribute identifiers and a separate Attribute Search API. | Taxonomy references do not establish an item-level variant or SKU-price matrix. |
Price, availability, shipping and points are separate signals
The Item Search response exposes several listing-level price ranges and flags, but those fields are not a completed checkout calculation. The API separates price basis, availability, tax, postage, overseas-shipping and item-based point information; their meaning depends on the response and observation context.
Scroll to compare →
| Signal | Documented meaning | Do not interpret it as |
|---|---|---|
| itemPriceMin/Max fields | The API labels ranges as all prices (1), searchable prices (2) and purchasable prices (3), alongside the item price and price-base field. | A selected SKU price, final order amount or price history. |
| availability | A binary response flag: 0 means out of stock and 1 means available. Search defaults to available items only. | A numeric inventory count or a guarantee that an order will be accepted later. |
| taxFlag and postageFlag | Separate flags indicate whether tax and postage are included in the listing price. | A destination-specific landed price or delivery estimate. |
| shipOverseasFlag and area | The response can indicate overseas-shipping support and documented areas. | A promise of delivery to every address or a quote for a particular buyer. |
| pointRate | Item-based point-multiplier information is documented separately; the page notes that multipliers ending within 24 hours are not shown. | All shop-level multipliers, promotions, or a guaranteed cash discount. |
Item Search and Ranking API results are different series
Rakuten says Web Service API search and Rakuten Ichiba website search use different systems, so their results and order do not completely match. Item Search exposes its own documented sorting options. The separately versioned Ichiba Ranking API represents the Rakuten ranking service, not keyword search or a universal search-engine position.
Scroll to compare →
| Result series | First-party scope | Keep separate from |
|---|---|---|
| Item Search API | Version 2026-07-01 supports its own keyword/shop/item/genre search and sort parameters, including price, review count, review average and item update time. | The exact Rakuten Ichiba website search set or ordering. |
| Ichiba website search | Rakuten Help says the website and API search systems differ; API defaults favor available items and restricted matching. | A guaranteed one-to-one mirror of API results. |
| Ranking API | The displayed Ranking API version is 2022-06-01; it supports genre or age/gender contexts and describes results up to 1,000 ranks. Genre cannot be combined with age/gender; age and gender can be used together. | Organic keyword position, units sold or an all-time demand series. |
| Ranking comparison | Rakuten notes that the returned ranking count/order may differ when a ranked item's page has been deleted. | A discrepancy-free copy of every item shown in the consumer ranking. |
Credentials and terms set the API-use boundary
The current Item Search specification requires an applicationId and accessKey; its documentation allows the access key in a header or query parameter. Rakuten's API catalog identifies App ID approval, and its Web Service Terms describe registered developers and use limits. Source review: 2026-10-07. The reviewed English Terms page displays no effective date and says the Japanese original governs.
Scroll to compare →
| Evidence point | What the official pages say | Reader boundary |
|---|---|---|
| Credentials | The current Item Search API requires applicationId and accessKey; the API catalog labels the Ichiba API as requiring App ID approval. | Treat this as credentialed developer access, not anonymous access. |
| Terms language | Rakuten labels its English Web Service Terms translation reference-only and says the Japanese original has legal force. | Read the governing current terms and API notices; this summary is not legal advice. |
| Use and sharing | The English reference describes purpose limits, restrictions on competing services and broad sharing, and possible limits on scope, access frequency, update timing and display. | Do not infer that public documentation grants permission for a particular commercial use. |
| Crawler files | The documentation-host robots.txt and sitemap contents were not verified during this review. | Their contents and any crawler directive remain unknown; they do not establish API credentials or reuse rights. |
Content reviewed 2026-10-07.