# Rakuten Ranking API Documentation

<p><strong>Rakuten Ranking API Documentation</strong> Read the Rakuten Ichiba sales ranking. Choose the period (daily, weekly, monthly or realtime), a genre, and optionally the female or male buyer ranking. Each row has the rank, the change since the last period (up, down, same or new), the price as a number in JPY, the review count, the shop and an id, shop_code and manage_number that the item and reviews endpoints accept unchanged. Rakuten shortens long titles on the ranking page: use the item endpoint for the full title. Some genres have no ranking for a period. The list is then empty and the request is not billed. updated_on is the day of the ranking. Cost: 1 credit per request. Empty lists and failed requests are not billed.</p>

- **Documentation:** [https://scrappa.co/docs/rakuten-api/rakuten_ranking](https://scrappa.co/docs/rakuten-api/rakuten_ranking)
- **API group:** Rakuten API
- **Endpoint:** `GET https://scrappa.co/api/rakuten/ranking`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `period` | string | No | Ranking period: daily (default), weekly, monthly or realtime. |
| `genre_id` | integer | No | Rakuten genre id, e.g. 100227 for food. Leave it out for the overall ranking. Take the ids from the genre path of an item. |
| `gender` | string | No | Ranking of items that sell well to female or male buyers: female or male. |
| `page` | integer | No | Page number from 1. Each page has up to 80 rows. A page beyond the end answers 422. |

## Example response

```json
{
    "data": {
        "page": 1,
        "items": [
            {
                "id": "310201_10004562",
                "url": "https://item.rakuten.co.jp/zoff/lucky_bag_ec/",
                "rank": 1,
                "shop": {
                    "id": 310201,
                    "url": "https://www.rakuten.co.jp/zoff/",
                    "code": "zoff",
                    "name": "Zoff \uff08\u30be\u30d5\uff09\u3000\u697d\u5929\u5e02\u5834\u5e97"
                },
                "image": "https://tshop.r10s.jp/zoff/cabinet/mail/2027fuku_1006.jpg",
                "price": 6600,
                "title": "|\u3010Zoff \u798f\u888b2027 \u3011\u3010\u30dd\u30a4\u30f3\u30c810\u500d\u3011\u300812\u6708\u4e0a\u65ec\u9803\u304b\u3089\u9806\u6b21\u767a\u9001\u3009\u30be\u30d5\u5e97\u8217\u3067\u4f7f\u3048\u308b10,0",
                "rating": {
                    "count": 1051,
                    "stars": 4
                },
                "item_id": 10004562,
                "shop_id": 310201,
                "currency": "JPY",
                "shop_code": "zoff",
                "rank_change": "up",
                "manage_number": "lucky_bag_ec",
                "price_is_from": false
            },
            {
                "id": "213310_22159108",
                "url": "https://item.rakuten.co.jp/book/18877285/",
                "rank": 2,
                "shop": {
                    "id": 213310,
                    "url": "https://www.rakuten.co.jp/book/",
                    "code": "book",
                    "name": "\u697d\u5929\u30d6\u30c3\u30af\u30b9"
                },
                "image": "https://tshop.r10s.jp/book/cabinet/4074/4988031934074_1_2.jpg",
                "price": 6042,
                "title": "Fujii Kaze \u201cPre: Prema Tour\u201d\u3010Blu-ray\u3011 [ \u85e4\u4e95 \u98a8 ]",
                "rating": {
                    "count": 0,
                    "stars": null
                },
                "item_id": 22159108,
                "shop_id": 213310,
                "currency": "JPY",
                "shop_code": "book",
                "rank_change": "down",
                "manage_number": "18877285",
                "price_is_from": false
            }
        ],
        "gender": null,
        "period": "daily",
        "currency": "JPY",
        "genre_id": null,
        "fetched_at": "2026-11-08T19:30:00+00:00",
        "genre_name": "\u7dcf\u5408",
        "updated_on": "2026-11-08"
    },
    "meta": {
        "credits": 1,
        "billable": true,
        "endpoint_family": "ranking"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A query parameter is missing or invalid. This response is not billable. |
| 422 | Invalid Request | The page is beyond the end of the ranking. This response is not billable. |
| 503 | Upstream Unavailable | Rakuten did not answer after the internal retries. This response is not billable. Retry after a few seconds. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)