# Yes24 Bestseller Scraper — Korean Book & K-pop Album Charts (`kdatafactory/yes24-bestseller-scraper`) Actor

Scrape Yes24 (yes24.com) bestseller charts — Korea's largest bookstore and top K-pop album retailer. Books or albums as clean JSON: rank, title, author/artist, publisher/label, KRW prices, rating, review count, sales index. For K-lit rights scouting, K-pop demand signals, market research.

- **URL**: https://apify.com/kdatafactory/yes24-bestseller-scraper.md
- **Developed by:** [Seok June Park](https://apify.com/kdatafactory) (community)
- **Categories:** E-commerce, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## 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 Bestseller Scraper 📚

Scrape the **bestseller charts** from [Yes24](https://www.yes24.com) (예스24) —
**Korea's largest online bookstore and a top physical K-pop album retailer**. Get clean,
structured chart data (rank, title, author/artist, publisher/label, list & sale price in
KRW, rating, review count, **Yes24 sales index**, publication date, image, product URL)
in JSON, CSV, or Excel.

Yes24 is where Korean reading demand and K-pop album demand become **measurable**: its
book chart tracks the K-lit wave (post-Han-Kang-Nobel), and its CD/LP chart is
effectively a **K-pop album sales chart** — Yes24's physical album sales feed Korea's
Hanteo/Circle charts.

> **Try it free.** Apify's free plan includes $5 of monthly platform credit — roughly **2,000 results** from this actor, no credit card required. Set your input, click Start, and export JSON/CSV/Excel.

***

### 🚀 What it does

Give it a **chart** and it returns the ranked bestseller list:

| Chart | What you get | Example input |
|-------|--------------|---------------|
| `books` | The overall **Korean book** bestseller chart (~1,000 ranked titles) | `{ "category": "books" }` |
| `music` | The **CD/LP** chart — K-pop albums, ranked by sales | `{ "category": "music" }` |

Power users can pass any raw Yes24 `categoryNumber` (e.g. `002` foreign books, or a
deep book sub-genre code) to chart any category in the site's tree, and set how many
chart rows to pull (`maxItems`).

***

### 📥 Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `category` | string | `books` | `books` (Korean book chart) or `music` (CD/LP — K-pop album chart). |
| `categoryNumber` | string | — | Advanced: raw Yes24 category code that overrides `category` (any code from the bestseller page's category tree). |
| `maxItems` | integer | `100` | Max chart rows to return (paginated at 24 per request, chart runs ~1,000 deep). |
| `proxyConfiguration` | object | off | Optional Apify proxy. Not required — enable for IP diversity at scale. |

**Input example — top 100 K-pop albums by sales:**

```json
{
  "category": "music",
  "maxItems": 100
}
```

***

### 📤 Output

Each chart row is one dataset record in this shape (real sample from a live run):

```json
{
  "source": "yes24",
  "product_id": "193401355",
  "rank": 1,
  "title": "박효신 - A & E",
  "author": "박효신",
  "publisher": "지니(genie)뮤직",
  "price_krw": 166700,
  "sale_price_krw": 135000,
  "rating": 8.4,
  "review_count": 20,
  "sales_point": 154440,
  "published_date": "2026-08",
  "category": "music",
  "category_number": "003",
  "url": "https://www.yes24.com/product/goods/193401355",
  "image_url": "https://image.yes24.com/goods/193401355/L",
  "scraped_at": "2026-07-10T15:19:58.256+09:00"
}
```

**Field notes**

- `rank` — 1-based chart position as printed by Yes24.
- `author` — the **public commercial attribution** printed on the chart card: author
  (plus credited translator/illustrator) for books, **artist/group name** for albums.
  No personal contact details, profiles, or user IDs are collected.
- `publisher` — publisher (books) or **label/distributor** (albums).
- `price_krw` / `sale_price_krw` — list price and current selling price, integer **KRW**
  (equal when there is no discount).
- `sales_point` — **Yes24's own sales index (판매지수)**, a demand metric that lets you
  compare sales momentum between titles and across snapshots — more informative than
  rank alone.
- `rating` — Yes24 member review score on a **0–10** scale; `review_count` — number of
  member reviews. Both are `null` when a title has no reviews yet (common for
  pre-order albums — see limitations).
- `published_date` — publication/release date normalized to ISO (`2026-08`), including
  future dates for pre-orders.
- A 25-record real sample (15 books + 10 albums) lives in
  [`samples/sample-output.json`](samples/sample-output.json).

***

### 💡 Use cases

- **K-lit rights scouting** — Korean fiction is the hottest rights market since Han
  Kang's Nobel. See what Korea is actually reading *now*, with author, publisher and a
  real sales index — before it surfaces in English-language trade press.
- **K-pop album sales signals** — the CD/LP chart ranks physical album demand
  (including pre-orders with future release dates), the same physical sales that drive
  Hanteo/Circle chart outcomes. Track versions, box sets and label activity per group.
- **Publishing market research** — genre trends, price points, discount depth, and
  publisher share of the top 1,000, snapshot by snapshot.
- **Price monitoring** — list vs. sale price across the chart, per publisher or label.
- **AI agents & LLM pipelines** — feed a clean, ranked JSON catalog of what Korea reads
  and listens to into RAG or a trend-analysis assistant.

***

### 🌐 Data source

This actor reads Yes24's **public** bestseller chart pages — the same server-rendered
HTML any visitor sees at `yes24.com/product/category/bestseller`. No login, no private
API. The pages are served without a bot challenge, so **no proxy is required**; you can
enable an Apify proxy for IP diversity when running at scale.

***

### ⚠️ Known limitations (honest notes)

- **`rating` / `review_count` depend on reviews existing.** On the book chart nearly
  every item has them (39/40 in live tests). On the music chart most entries are
  **new or pre-order albums** that have no reviews yet, so those two fields are often
  `null` there (9/40 populated in live tests). All other fields populate on both charts.
- **`rating` is on a 0–10 scale** (Yes24's review score), not the 5-star scale most
  platforms use.
- **`sales_point` is Yes24's proprietary index**, not a unit-sales figure. It is
  comparable between titles and across time, but not convertible to absolute copies sold.
- **Chart depth is ~1,000 items** per category — this is a bestseller chart scraper,
  not a full catalog crawler.

***

### ⚖️ Rate & legality note

- Only **public, non-personal** chart data is collected — listings anyone can see
  without logging in. **No personal data** (no reader reviews, reviewer nicknames,
  profiles, or user IDs). `author` and `publisher` are public commercial attribution —
  author/artist and publisher/label names, like a shop name.
- Requests are **rate-limited** (sequential pages, ≥500 ms delay) to stay light on the
  site.
- You are responsible for complying with Yes24's Terms of Service and applicable law in
  your jurisdiction. Use the data for research, monitoring, and analytics — not to
  replicate the platform.

***

### ❓ FAQ

**Is it legal to scrape this data?**
This actor collects only public, non-personal chart data — the same bestseller lists any visitor sees on Yes24 without logging in. No personal data is collected (reader reviews, nicknames, and profiles are never parsed; author/artist names are public commercial attribution). You are responsible for how you use the data; see the rate & legality note above.

**What does it cost in practice?**
$2.50 per 1,000 results (launch pricing) + a few cents of platform usage. Example: snapshotting the top 500 books daily costs about $1.25/day. Apify's free $5 monthly credit covers ~2,000 results.

**Do I need to configure proxies?**
No — the default settings work out of the box. Optionally, enable an Apify proxy for IP diversity when running at scale.

**How fresh is the data?**
Every run scrapes the live Yes24 chart at run time (Yes24 recomputes its bestseller ranking on a rolling basis). Schedule the actor for daily/weekly time series.

**Can I scrape a specific genre instead of the overall chart?**
Yes — pass the genre's raw code in `categoryNumber` (any code from the bestseller page's category tree, e.g. a Korean-fiction sub-genre). The `books`/`music` presets cover the two headline charts.

**What is NOT included?**
Reader reviews and any reviewer identity (never collected), unit sales figures (`sales_point` is Yes24's own index), and products outside the bestseller charts (~1,000 items deep per category).

***

### 🤖 Use with AI agents (MCP)

Call this Actor as a tool from Claude or any MCP-compatible AI agent — no glue code. Point your MCP client at Apify's server, scoped to this Actor:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=kdatafactory/yes24-bestseller-scraper",
      "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" }
    }
  }
}
```

Your agent can then pull Yes24 book & K-pop album bestsellers on demand — no scraping code in your app. Grab a free token from [Apify → Integrations](https://console.apify.com/settings/integrations).

### 🇰🇷 More Korean data actors

This actor is part of a suite of Korean-platform scrapers by the same maintainer:

- [ktown4u-scraper](https://apify.com/kdatafactory/ktown4u-scraper) — global K-pop album & goods store, product and price data.
- [pocamarket-scraper](https://apify.com/kdatafactory/pocamarket-scraper) — K-pop photocard marketplace, listing & price data.
- [wadiz-scraper](https://apify.com/kdatafactory/wadiz-scraper) — Korea's largest reward crowdfunding platform, campaign & funding data.

Browse all: [apify.com/kdatafactory](https://apify.com/kdatafactory)

***

### 🏃 Run it

On Apify: set your input and click **Start**. Locally:

```bash
npm install
## put your input in storage/key_value_stores/default/INPUT.json
npm start
```

Results land in the default dataset (Apify) or `./storage/datasets/default` (local).

***

*If this actor saves you time, a rating on the [Store page](https://apify.com/kdatafactory/yes24-bestseller-scraper) helps a solo maintainer a lot. Found an issue? Open it in the Issues tab — I respond fast.*

# Actor input Schema

## `category` (type: `string`):

'books' = the overall Korean book bestseller chart. 'music' = the CD/LP chart (Yes24 is a top K-pop album retailer, so this is effectively a K-pop album sales chart).

## `categoryNumber` (type: `string`):

Advanced: a raw Yes24 category code that overrides the Chart preset — any code from the bestseller page's category tree (e.g. '002' foreign books, '001001046' a book sub-genre). Leave empty to use the Chart preset.

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

Maximum number of chart items to return (paginated at 24 per request; the overall book chart runs ~1,000 items deep).

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

Optional Apify proxy. The chart page is not IP-blocked, so a proxy is not required; enable one for IP diversity at scale.

## Actor input object example

```json
{
  "category": "books",
  "maxItems": 100,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "category": "books"
};

// Run the Actor and wait for it to finish
const run = await client.actor("kdatafactory/yes24-bestseller-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 = { "category": "books" }

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

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

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

```

## CLI example

```bash
echo '{
  "category": "books"
}' |
apify call kdatafactory/yes24-bestseller-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=kdatafactory/yes24-bestseller-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/NOH0stVy810Bso5s4/builds/wZcEI0S9fW8x3HOx9/openapi.json