# Ktown4u Scraper — K-Pop Albums, Goods & Bestsellers (USD) (`kdatafactory/ktown4u-scraper`) Actor

Scrape ktown4u, the global K-pop album & merch store serving 241 countries. Best-seller rankings, keyword search and category listings as clean JSON: English names, artist/group, USD prices, discounts, stock and images. For K-pop research, price monitoring and AI agents.

- **URL**: https://apify.com/kdatafactory/ktown4u-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

## Ktown4u K-Pop Album & Goods Scraper 🎤

Scrape **best-seller rankings, keyword search results, and category listings** from
[ktown4u](https://www.ktown4u.com) — the de-facto **global K-pop album & merchandise store**
(self-reported 1.8M+ customers across 241 countries). Get clean, structured product data
(name, artist/group, USD price, discount, stock status, image, product URL) in JSON, CSV,
Excel, or via API.

Built for **K-pop sellers, dropshippers, and market researchers** who need to track what's
actually selling on the world's biggest K-pop storefront — priced in **USD** and named in
**English**, ready to use.

> **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 **mode** and a list of **queries** and it returns a structured product feed:

| Mode | What you get | Example input |
|------|--------------|---------------|
| `bestsellers` | The storefront **best-seller ranking** (top ~20, with `rank`) | `{ "mode": "bestsellers" }` |
| `search` | Products matching each **keyword** | `{ "mode": "search", "queries": ["SEVENTEEN", "aespa"] }` |
| `category` | Products in a store **category** (by number, or a friendly name) | `{ "mode": "category", "queries": ["k-pop"] }` |

Data comes straight from ktown4u's **public Next.js page data** (the same JSON the website's
own front-end hydrates from) — so it's fast and reliable, no brittle HTML scraping and no
login.

**Friendly category names** you can pass in `category` mode: `k-pop` (1723449),
`k-contents` (1723490), `k-style` (1723524). Any other **category number** works too — grab
it from a `ktown4u.com/goodsList?grp_no=…` URL.

***

### 📥 Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `mode` | string | `bestsellers` | `bestsellers`, `search`, or `category`. |
| `queries` | string\[] | `[]` | Keywords (search) or category numbers/names (category/bestsellers). Empty in `bestsellers` = the overall best-seller list. |
| `maxItems` | integer | `200` | Max total products across all queries. |
| `proxyConfiguration` | object | Apify proxy | Optional. The storefront serves its public product JSON directly; a proxy just adds IP rotation for large runs. |

**Input example — search several artists at once:**

```json
{
  "mode": "search",
  "queries": ["SEVENTEEN", "BTS", "aespa"],
  "maxItems": 200
}
```

***

### 📤 Output

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

```json
{
  "source": "ktown4u",
  "product_id": "166051",
  "name": "Stray Kids - 10th Mini Album [THIS & THAT] (TRUCK Ver.) (Limited Edition)",
  "artist": "Stray Kids",
  "category": "bestsellers",
  "price_usd": 31.14,
  "sale_price_usd": 25.24,
  "currency": "USD",
  "in_stock": true,
  "rank": 6,
  "url": "https://www.ktown4u.com/iteminfo?goods_no=166051",
  "image_url": "https://media.ktown4u.com/products/resize/thumbnail/2026/07/08/MqKJ2Q.jpg",
  "scraped_at": "2026-07-09T13:35:03.606+09:00"
}
```

**Field notes**

- `price_usd` / `sale_price_usd` — the storefront's **USD display prices**. When a product is
  not discounted, `sale_price_usd` is `null`.
- `artist` — the artist/group name (a product attribute, e.g. "Stray Kids", "aespa").
- `category` — the product context: `bestsellers`, `search/<keyword>`, or
  `category/<number>`. (The raw product kind, e.g. "Albums", "Photobooks", "Plush Toys", is
  used as a fallback.)
- `rank` — 1-based position, **populated in `bestsellers` mode** (`null` in search/category).
- `in_stock` — whether the item is currently on sale/available.
- A full 25-record sample lives in [`samples/sample-output.json`](samples/sample-output.json).

***

### ⚠️ How many results per query

ktown4u's storefront returns **one page (~20 products) of results per query**. The actor is
built around this: pass **many queries in one run** (a list of artists, keywords, or category
numbers) to collect a large, targeted catalog. `bestsellers` returns the top ~20 ranked
products; `search`/`category` return the first ~20 matches for each entry. Deeper pagination
past the first page is **not** offered (the storefront loads it via an internal client-side
call we deliberately do not replicate) — so this actor is priced and documented on the first
page only, which is exactly the high-signal "what's ranking / what matches" slice most buyers
want.

***

### 💡 Use cases

- **Price monitoring** — track USD prices and discounts on hero albums/goods over time.
- **K-pop market research** — see what's topping the best-seller ranking and what's launching
  by artist.
- **Dropshipping / sourcing** — pull high-selling products with images and URLs ready to
  import into Shopify/Amazon listings.
- **AI agents & LLM pipelines** — feed a clean JSON product catalog into RAG or a shopping
  assistant.
- **Fandom & release tracking** — monitor new album/merch drops per group.

***

### 🌐 Data source & proxy

This actor targets the **global ktown4u storefront** (`www.ktown4u.com`) — chosen because it
serves **English product names and USD prices**, exactly what global K-pop sellers need. Data
is read from the storefront's **public** Next.js page-data endpoints.

> **Proxy is optional.** In our testing the storefront serves its public product JSON without
> a proxy. For large runs you can enable an Apify proxy for IP rotation; the actor falls back
> to a direct connection automatically if no proxy is configured or the tunnel fails. If the
> site's edge ever returns `HTTP 403/429`, enable a proxy and retry.

***

### ⚖️ Rate & legality note

- Only **public, non-personal** catalog data is collected — product listings anyone can see
  without logging in. **No customer, reviewer, or seller personal data** (no nicknames,
  profiles, or IDs) is ever scraped. `artist` is a product attribute, not personal data.
- Requests are **sequential** with a **≥500 ms delay** between queries to stay light on the
  site.
- You are responsible for complying with ktown4u's Terms of Service and applicable law in your
  jurisdiction. Use the data for research, monitoring, and analytics — not to replicate the
  storefront.

***

### ❓ FAQ

**Is it legal to scrape this data?**
This actor collects only public, non-personal catalog data — the same product listings any visitor sees on ktown4u without logging in. No personal data is collected. 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: a 500-result daily pull 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; the storefront serves its public product JSON directly. For large runs you can optionally enable an Apify proxy for IP rotation, and if the site's edge ever returns HTTP 403/429, enable a proxy and retry.

**How fresh is the data?**
Every run scrapes the live site at run time. Schedule the actor for recurring snapshots (e.g. daily best-seller tracking).

**What is NOT included?**
Only the first page (~20 products) per query — deeper pagination is deliberately not offered, so pass many queries to build a large catalog. No customer, reviewer, or seller personal data is ever scraped.

***

### 🤖 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/ktown4u-scraper",
      "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" }
    }
  }
}
```

Your agent can then pull Ktown4u K-pop album & goods prices 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:

- [pocamarket-scraper](https://apify.com/kdatafactory/pocamarket-scraper) — K-pop photocard marketplace listings and prices.
- [bunjang-scraper](https://apify.com/kdatafactory/bunjang-scraper) — Korea's top secondhand marketplace search results.

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/ktown4u-scraper) helps a solo maintainer a lot. Found an issue? Open it in the Issues tab — I respond fast.*

# Actor input Schema

## `mode` (type: `string`):

What to scrape. 'bestsellers' = the best-seller ranking (top ~20, with rank). 'search' = keyword search results. 'category' = products in a store category (by category number).

## `queries` (type: `array`):

One or more inputs, processed in turn. For 'search': keywords (e.g. "SEVENTEEN", "BTS album"). For 'category': category numbers (e.g. "1723449" = K-Pop). For 'bestsellers': category numbers, or leave empty for the overall bestseller list. Each entry yields up to ~20 products (see README — the storefront returns one page per query).

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

Maximum total number of products to return across all queries.

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

Apify proxy settings. Optional — the storefront serves its public product JSON without a proxy, but a proxy adds IP rotation for large runs. If no proxy is set the actor connects directly.

## Actor input object example

```json
{
  "mode": "bestsellers",
  "queries": [
    "SEVENTEEN",
    "BTS",
    "aespa"
  ],
  "maxItems": 200,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# 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 = {};

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

# Run the Actor and wait for it to finish
run = client.actor("kdatafactory/ktown4u-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/ktown4u-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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