# 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, 96.6% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# 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 **1,250 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?**
$4.00 per 1,000 results + 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 ~1,250 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
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Every record collected in this run.

# 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(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 '{
  "category": "books"
}' |
apify call kdatafactory/yes24-bestseller-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kdatafactory/yes24-bestseller-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/NOH0stVy810Bso5s4/builds/5cDJYrb16AmrZgCUf/openapi.json