# Yes24 Book Bestseller & Category Scraper (Korea) (`signaldatatools/yes24-book-scraper`) Actor

Scrape Korean bestseller book listings from Yes24: titles, authors, publishers, KRW prices and discounts, ratings, review counts and sales index, ranked by category.

- **URL**: https://apify.com/signaldatatools/yes24-book-scraper.md
- **Developed by:** [Signal Data Tools](https://apify.com/signaldatatools) (community)
- **Categories:** E-commerce, Business, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Yes24 Book Bestseller & Category Scraper (Korea)

Pull ranked bestseller and category data from **Yes24** (yes24.com), Korea's largest online
bookstore. Give it one or more category codes and it returns the ranked title list with
author, publisher, publication month, discounted and list price in KRW, the discount rate,
the customer rating, the review count and Yes24's own sales index.

Korean publishing data is close to unobtainable from outside Korea. There is no public API,
rights and catalogue information sits behind Korean-language listings, and the ranking
that actually drives Korean bookstore buying — the sales index — is not published anywhere
else. Yes24's `robots.txt` permits the server-rendered bestseller listing, and this Actor
stays strictly inside what it permits.

Verified on a live run: **60 books in 4.4 seconds**, and **200 books across 2 categories in
8.3 seconds**. No blocking encountered.

### What you get

One dataset row per book:

| Field | Type | Description |
|---|---|---|
| `bookId` | string | Yes24 goods number |
| `title` | string | Title as listed |
| `url` | string | Canonical product page URL (emitted as a string, never fetched) |
| `author` | string | Author / translator / editor credit line |
| `publisher` | string | Publisher name |
| `publishDate` | string | Publication month as displayed |
| `priceKrw` | integer | Selling price after discount, Korean won |
| `originalPriceKrw` | integer | List price before discount, Korean won |
| `discountRate` | integer | Discount percentage |
| `rating` | number | Average customer rating |
| `reviewCount` | integer | Number of customer reviews |
| `salesIndex` | integer | Yes24 sales index — the store's own demand score |
| `imageUrl` | string | Cover image URL (emitted as a string, never fetched) |
| `categoryNumber` | string | Which input category produced this row |
| `rank` | integer | Position within that category's bestseller list |
| `scrapedAt` | string | ISO-8601 UTC timestamp |

### Input

```json
{
  "categoryNumbers": ["001001025", "001001046"],
  "maxItems": 200,
  "maxPages": 5,
  "pageSize": 100,
  "requestDelaySeconds": 2,
  "respectRobotsTxt": true,
  "includeContactInfo": false,
  "proxyConfiguration": { "useApifyProxy": true, "apifyProxyCountry": "KR" }
}
```

| Option | Default | Notes |
|---|---|---|
| `categoryNumbers` | `["001"]` | Required. Verified codes listed below |
| `maxItems` | 100 | Hard stop across all categories (max 5000) |
| `maxPages` | 5 | Pages per category (max 50) |
| `pageSize` | 48 | 10, 24, 48, 60, 100 and 120 all verified as honoured |
| `requestDelaySeconds` | 2 | Politeness pause between requests |
| `respectRobotsTxt` | `true` | Re-checks robots.txt at runtime, skips disallowed URLs |
| `includeContactInfo` | `false` | Off by default; keeps personal contact data out of your dataset |
| `proxyConfiguration` | Apify Proxy, KR | A Korean IP gives the most consistent results |

**Verified category codes:** `001` all Korean books, `001001019` humanities,
`001001022` society & politics, `001001025` business & economics,
`001001046` fiction & poetry, `001001047` essays, `002` foreign books, `003` CD/LP,
`004` DVD/Blu-ray, `017` eBooks.

**Hard cap:** each bestseller list ends at **rank 1000**. Pages beyond that come back empty
and the run moves on to the next category, so 1000 rows per category is the ceiling
regardless of `maxPages`.

### Sample output

```json
{
  "bookId": "192474512",
  "title": "세네카, 오늘을 빼앗기고 있는 당신에게",
  "url": "https://www.yes24.com/product/goods/192474512",
  "author": "루키우스 안나이우스 세네카 저/ 하와이 대저택 편역",
  "publisher": "논픽션",
  "publishDate": "2026년 07월",
  "priceKrw": 16200,
  "originalPriceKrw": 18000,
  "discountRate": 10,
  "rating": 8.4,
  "reviewCount": 176,
  "salesIndex": 520308,
  "imageUrl": "https://image.yes24.com/goods/192474512/L",
  "categoryNumber": "001",
  "rank": 1,
  "scrapedAt": "2026-09-13T08:58:54Z"
}
```

### Typical uses

- **Publishing market intelligence** — track which titles, publishers and genres are selling in Korea
- **Translation-rights scouting** — spot rising Korean titles and K-content source material early
- **Competitive title and price tracking** — monitor your own catalogue's rank, discount and reviews
- **Cultural trend research** — build time series of category demand from the sales index

### Responsible use

- Reads **the public bestseller listing only** — `GET /product/category/bestseller`.
  `robots.txt` permits that path. The Actor never calls `/Product/Goods/JsonGoodsList`,
  the ajax list endpoint `robots.txt` disallows, and it never opens a product detail page:
  `url` and `imageUrl` are emitted as plain strings for you to follow yourself.
- `respectRobotsTxt` is on by default and enforced before every single request.
- Requests are paced (default 2s) with retries on transient failures.
- **Personal data is excluded by default.** With `includeContactInfo: false`, phone and
  e-mail fields are dropped and any phone/e-mail pattern inside a free-text field is
  replaced with `[removed]`.
- Titles, cover images, prices and review data belong to their respective owners. You are
  responsible for how you use the output.

### Pricing

Pay per result. You are charged only for rows actually delivered to your dataset.

***

### 한국어 요약

**예스24 베스트셀러·카테고리 크롤러.** 카테고리 코드를 넣으면 예스24 베스트셀러 목록을
그대로 표로 뽑아 줍니다. 제목·저자·출판사·출간월·판매가/정가(원)·할인율·평점·리뷰 수·
판매지수·표지 이미지 주소가 한 줄씩 나옵니다.

- **검증된 카테고리**: `001` 국내도서 전체, `001001019` 인문, `001001022` 사회정치,
  `001001025` 경제경영, `001001046` 소설/시, `001001047` 에세이, `002` 외국도서,
  `003` CD/LP, `004` DVD, `017` eBook
- **페이지 크기**: 10·24·48·60·100·120 모두 실측 확인(기본 48)
- **한계**: 베스트셀러 목록은 카테고리마다 **1000위에서 끝납니다**. 그 뒤 페이지는
  비어서 돌아오고 다음 카테고리로 넘어갑니다
- **속도**: 60건 4.4초, 2개 카테고리 200건 8.3초 실측(차단 없음)
- **안전장치**: robots.txt 준수가 기본값(켜짐), 요청 간 2초 지연
- 예스24가 robots.txt로 막아둔 `/Product/Goods/JsonGoodsList` 는 절대 호출하지 않고,
  상품 상세 페이지도 열지 않습니다. 주소는 문자열로만 담아 드립니다

**요금**: 결과 1건당 과금(pay-per-result). 실제로 받은 줄 수만큼만 냅니다.

# Actor input Schema

## `categoryNumbers` (type: `array`):

Yes24 category codes to walk. Verified codes: "001" all Korean books (default), "001001019" humanities, "001001022" society & politics, "001001025" business & economics, "001001046" fiction & poetry, "001001047" essays, "002" foreign books, "003" CD/LP, "004" DVD/Blu-ray, "017" eBooks. Each category list tops out at rank 1000.

## `maxItems` (type: `integer`):

Stop after this many books in total across all categories.

## `maxPages` (type: `integer`):

Listing pages to walk per category. The bestseller list ends at rank 1000, so pages beyond that come back empty and the run moves on.

## `pageSize` (type: `integer`):

Books requested per listing page. Verified working values run from 10 up to 120; larger pages mean fewer requests.

## `requestDelaySeconds` (type: `integer`):

Politeness pause between HTTP requests.

## `respectRobotsTxt` (type: `boolean`):

Check the target's robots.txt before every request and skip disallowed URLs. The actor only reads the rendered bestseller listing and never calls the site's disallowed ajax list endpoint.

## `includeContactInfo` (type: `boolean`):

Off by default. When off, phone numbers and e-mail addresses are stripped from any free-text field in the output.

## `proxyConfiguration` (type: `object`):

Apify Proxy settings. A Korean residential or datacenter IP is recommended.

## Actor input object example

```json
{
  "categoryNumbers": [
    "001"
  ],
  "maxItems": 100,
  "maxPages": 5,
  "pageSize": 48,
  "requestDelaySeconds": 2,
  "respectRobotsTxt": true,
  "includeContactInfo": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyCountry": "KR"
  }
}
```

# Actor output Schema

## `books` (type: `string`):

Books scraped in this run, as a dataset (JSON/CSV/Excel via the Apify API).

## `datasetView` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "categoryNumbers": [
        "001"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("signaldatatools/yes24-book-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "categoryNumbers": ["001"] }

# Run the Actor and wait for it to finish
run = client.actor("signaldatatools/yes24-book-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "categoryNumbers": [
    "001"
  ]
}' |
apify call signaldatatools/yes24-book-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,signaldatatools/yes24-book-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/4heuaS58OHnyEH2D0/builds/4prhOoMR9xx1Nsb00/openapi.json