# Kyobo Book Bestseller Scraper — Korean Bookstore Charts (`kdatafactory/kyobo-bestseller-scraper`) Actor Scrape the bestseller chart from Kyobo Book (교보문고), Korea's #1 bookstore chain: rank, title, author, publisher, KRW price, ISBN, genre and cover image as clean JSON. Weekly / monthly / annual charts, genre filters. Pairs with yes24-bestseller-scraper for full Korean book-market coverage. - **URL**: https://apify.com/kdatafactory/kyobo-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.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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use 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 ## Kyobo Book Bestseller Scraper — Korean Bookstore Charts 📕 Scrape the **bestseller chart** from [Kyobo Book (교보문고)](https://store.kyobobook.co.kr) — **Korea's #1 bookstore chain** — as clean, structured JSON. Get rank, title, author, publisher, price (KRW), ISBN, genre, and cover image for every book on the chart in one run. The perfect feed for **publishing intelligence, translation-rights scouting, and Korean book-market research**. Pair it with [yes24-bestseller-scraper](https://apify.com/kdatafactory/yes24-bestseller-scraper) to cover Korea's two largest bookstores in one pipeline. > **Try it free.** Apify's free plan includes $5 of monthly platform credit — at **$2.00 / 1,000 results** that's roughly **2,500 book records** from this actor, no credit card required. Set your input, click Start, and export JSON/CSV/Excel. --- ### What it does This actor reads the bestseller list straight from Kyobo Book's own public JSON API (the same endpoint the website calls as you browse the chart), so results are fast and complete — no fragile full-page scraping, no headless browser. You can scrape: - **The overall chart** (종합 베스트셀러, all genres), or - **A specific genre** (e.g. Fiction, Humanities, Business, Science). Charts are available for three periods: - **Weekly** (주간) — the default, - **Monthly** (월간), - **Annual** (연간). > **Why Kyobo Book?** Kyobo Book (교보문고) is Korea's largest and most influential bookstore chain, and its bestseller chart is a primary barometer of what Korea is reading. Publishers, literary agents, and rights scouts watch it to spot breakout titles, track category trends, and time translation-rights deals. This actor turns that chart into a structured dataset you can filter, join on ISBN, and pipe into your own tools. --- ### Input | Field | Type | Description | |-------|------|-------------| | `period` | string | Chart period: `weekly` (주간), `monthly` (월간), or `annual` (연간). Default `weekly`. | | `category` | string | Genre filter. `all` returns the overall chart (default). Presets include `fiction`, `essay`, `poetry`, `humanities`, `politics-society`, `business`, `science`, `health`, `children`, `parenting`, `foreign-language`, `korean-fiction`, `foreign-fiction` (Korean genre names and raw genre codes `A`–`N` are also accepted). | | `maxItems` | integer | Max books to collect. Default `100`. The chart ranks up to `200` books per period, so 200 is the effective maximum. | | `proxyConfiguration` | object | Proxy settings (see below). Defaults to a direct connection. | #### Input example ```json { "period": "weekly", "category": "all", "maxItems": 100 } ```` ```json { "period": "monthly", "category": "business", "maxItems": 50 } ``` *** ### Output Each book on the chart is one dataset record. `price_krw` is the list price in Korean won; `sale_price_krw` is Kyobo's discounted price. `isbn` is the ISBN-13, ideal for joining against other catalogues and rights databases. `category` is the book's own genre as Kyobo classifies it. ```json { "source": "kyobo", "rank": 1, "item_id": "S000000620195", "title": "싯다르타", "author": "헤르만 헤세", "publisher": "민음사", "price_krw": 8000, "sale_price_krw": 7200, "isbn": "9788937460586", "category": "소설", "url": "https://product.kyobobook.co.kr/detail/S000000620195", "image_url": "https://contents.kyobobook.co.kr/sih/fit-in/458x0/pdt/S000000620195.jpg", "scraped_at": "2026-07-14T15:04:34+09:00" } ``` A full 40-item sample from a real run is in [`samples/sample-output.json`](samples/sample-output.json). | Field | Meaning | |-------|---------| | `source` | Always `"kyobo"`. | | `rank` | 1-based bestseller rank as printed by Kyobo (ties can skip numbers). | | `item_id` | Kyobo product ID (`saleCmdtid`), used in the detail URL. | | `title` | Book title. | | `author` | Author / creator name (public commercial attribution). | | `publisher` | Publisher name. | | `price_krw` | List price in KRW. | | `sale_price_krw` | Kyobo's discounted price in KRW (equals `price_krw` when there is no discount). | | `isbn` | ISBN-13 (`cmdtCode`). | | `category` | The book's genre as Kyobo classifies it (소설, 인문, 경제/경영 …). | | `url` | Product detail page URL. | | `image_url` | Cover image URL (Kyobo's standard cover CDN path for the product). | | `scraped_at` | ISO-8601 timestamp (KST, UTC+9). | The core fields — `rank`, `title`, `author`, `publisher`, `price_krw`, `sale_price_krw`, `isbn`, `category`, `url`, `image_url` — were populated on **40/40** records in the live test. The critical fields **`rank`, `title`, `author`, `price_krw`** are always present. *** ### Use cases - **Publishing & translation-rights scouting** — watch what Korea is buying, spot breakout titles early, and pull ISBNs to check foreign-rights availability. Filter by genre (e.g. `fiction`, `humanities`) to track the categories you acquire in. - **Bestseller tracking** — schedule the actor for daily/weekly snapshots and build a time series of rank movements, new entries, and price changes across the weekly, monthly, and annual charts. - **Retail & book-market research** — measure genre mix, price bands, and publisher share across the chart; benchmark Kyobo against other Korean retailers. - **AI agents & datasets** — feed structured, ISBN-keyed bestseller data into pricing models, dashboards, or LLM agents. *** ### ❓ FAQ **Is it legal to scrape this data?** This actor collects only public, non-personal bestseller data — the same chart any visitor sees on store.kyobobook.co.kr without logging in. No personal data is collected (no reviews, reviewer names, or user IDs). You are responsible for how you use the data; see the legality note below. **What does it cost in practice?** $2.00 per 1,000 results (launch pricing) + a few cents of platform usage. A full 200-book chart costs about **$0.40**. Apify's free $5 monthly credit covers **~2,500 results** (5 ÷ 2 × 1,000). **Do I need to configure proxies?** No — the default settings work out of the box. Kyobo Book serves its bestseller API without a bot wall, so the actor runs fine on a **direct connection**. For very heavy pulls you can optionally enable Apify Proxy — see the proxy note below. **How fresh is the data?** Every run scrapes the live Kyobo chart at run time. Schedule the actor for recurring snapshots (e.g. weekly bestseller tracking). **Which chart is this?** The flagship **종합(overall) 베스트셀러** chart — Kyobo's headline bestseller list, combining sales across channels — for the weekly, monthly, and annual periods. *** ### 🤖 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/kyobo-bestseller-scraper", "headers": { "Authorization": "Bearer " } } } } ``` Your agent can then pull Korean bestseller data 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: - **[yes24-bestseller-scraper](https://apify.com/kdatafactory/yes24-bestseller-scraper) — bestseller & K-pop album charts from Yes24, Korea's largest online bookstore.** Run it together with this actor for two-store book-market coverage. - **[aladin-scraper](https://apify.com/kdatafactory/aladin-scraper) — new & used book data from Aladin (알라딘), Korea's big used-book marketplace.** Browse all: [apify.com/kdatafactory](https://apify.com/kdatafactory) *** ### Rate limiting & legality - The actor collects **only public, non-authenticated data**. It never logs in and never touches private endpoints. - **No personal data** is collected — no reviews, reviewer nicknames, or user IDs. Only the book's public catalogue attributes and its public bestseller rank are returned. - Requests are rate-limited: one page at a time with a ≥ 500 ms delay between requests, to stay gentle on Kyobo's servers. - You are responsible for using the data in line with Kyobo Book's terms of service and applicable law. #### Known limitations (honesty note) - **`publisher` and `category`** come straight from Kyobo's API and were populated on **40/40** records in the live test. The output schema still allows `null` defensively, for the occasional non-standard product (e.g. a boxed set) where Kyobo omits a field. - **`image_url`** is Kyobo's standard cover-CDN URL derived from the product ID (the chart API itself does not return a cover path). It resolves for normal books; a brand-new or unusual product could occasionally lack a cover at that path. - **`rank`** follows Kyobo's own numbering — tied books can share or skip a rank number, so a 120-item pull may span ranks 1–122. This mirrors the source chart exactly. - **Titles, author, publisher, and genre are Korean strings** — this actor returns them verbatim as Kyobo publishes them (no translation). `isbn` gives you a language-neutral key for joins. - **Daily charts are not covered.** This actor targets the flagship 종합(overall) chart, which Kyobo offers weekly, monthly, and annually. (Kyobo's separate online-only chart offers a daily view; it is a different chart and is out of scope here.) *** *If this actor saves you time, a rating on the [Store page](https://apify.com/kdatafactory/kyobo-bestseller-scraper) helps a solo maintainer a lot. Found an issue? Open it in the Issues tab — I respond fast.* # Actor input Schema ## `period` (type: `string`): Which Kyobo 종합(overall) bestseller chart to scrape: weekly (주간), monthly (월간), or annual (연간). ## `category` (type: `string`): Optional genre filter for the bestseller chart. 'all' returns the overall chart (default). Genre options map to Kyobo's own bestseller genre tabs. ## `maxItems` (type: `integer`): Maximum number of ranked books to collect. Default 100. The chart ranks up to 200 books per period, so 200 is the effective maximum. ## `proxyConfiguration` (type: `object`): Proxy settings. Kyobo Book serves its bestseller JSON API without a bot wall, so the actor runs fine on a direct connection (default). If you ever see blocks at high volume, enable Apify Proxy here. ## Actor input object example ```json { "period": "weekly", "category": "all", "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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("kdatafactory/kyobo-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("kdatafactory/kyobo-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 '{}' | apify call kdatafactory/kyobo-bestseller-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=kdatafactory/kyobo-bestseller-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Kyobo Book Bestseller Scraper — Korean Bookstore Charts", "description": "Scrape the bestseller chart from Kyobo Book (교보문고), Korea's #1 bookstore chain: rank, title, author, publisher, KRW price, ISBN, genre and cover image as clean JSON. Weekly / monthly / annual charts, genre filters. Pairs with yes24-bestseller-scraper for full Korean book-market coverage.", "version": "0.1", "x-build-id": "EYxOmQEI2K9bSLKvz" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/kdatafactory~kyobo-bestseller-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-kdatafactory-kyobo-bestseller-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/kdatafactory~kyobo-bestseller-scraper/runs": { "post": { "operationId": "runs-sync-kdatafactory-kyobo-bestseller-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/kdatafactory~kyobo-bestseller-scraper/run-sync": { "post": { "operationId": "run-sync-kdatafactory-kyobo-bestseller-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "period": { "title": "Chart period", "enum": [ "weekly", "monthly", "annual" ], "type": "string", "description": "Which Kyobo 종합(overall) bestseller chart to scrape: weekly (주간), monthly (월간), or annual (연간).", "default": "weekly" }, "category": { "title": "Genre / category", "enum": [ "all", "fiction", "essay", "korean-fiction", "foreign-fiction", "poetry", "humanities", "politics-society", "business", "science", "health", "children", "parenting", "foreign-language" ], "type": "string", "description": "Optional genre filter for the bestseller chart. 'all' returns the overall chart (default). Genre options map to Kyobo's own bestseller genre tabs.", "default": "all" }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 200, "type": "integer", "description": "Maximum number of ranked books to collect. Default 100. The chart ranks up to 200 books per period, so 200 is the effective maximum.", "default": 100 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy settings. Kyobo Book serves its bestseller JSON API without a bot wall, so the actor runs fine on a direct connection (default). If you ever see blocks at high volume, enable Apify Proxy here.", "default": { "useApifyProxy": false } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```