# KREAM Scraper - Korea Sneaker Resale Price API (`kdatafactory/kream-ranking-scraper`) Actor

Scrape KREAM lowest-ask, highest-bid, premium & price history for sneakers, streetwear & luxury as clean English JSON. Spot Korea-vs-StockX/GOAT arbitrage. Pay-per-result resale-price API for resellers & market-intel teams.

- **URL**: https://apify.com/kdatafactory/kream-ranking-scraper.md
- **Developed by:** [Seok June Park](https://apify.com/kdatafactory) (community)
- **Categories:** E-commerce, Developer tools
- **Stats:** 1 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 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

## KREAM Ranking Scraper — Korea Resale Best-Sellers 👟

Scrape live **resale best-seller rankings** from [KREAM (크림)](https://kream.co.kr) — **Naver-owned, Korea's #1 resale marketplace** for sneakers, streetwear, and collectibles — as clean, structured JSON. Get the top-selling products with their rank, name, brand, price (KRW), trading volume, and category in one run. Built to power a **daily Korean shopping-trend dashboard**.

> **⚠️ Read this first — bot wall.** KREAM's data API sits behind **Naver's nfront WAF**. Every scripted HTTP client (curl, curl\_cffi/chrome impersonation, plain Node) gets a `403`. This actor drives a **real browser** to get through and reads KREAM's server-rendered ranking payload. From a datacenter or non-Korean IP the WAF blocks the request. To run this reliably on the Apify platform you almost certainly need a **Korean residential proxy** (Apify Proxy: `RESIDENTIAL`, `country=KR`). See [Requirements & honesty note](#-requirements--honesty-note) below.

***

### What it does

This actor opens KREAM's public ranking board in a real Chromium browser and reads every product on the board in **rank order** (top of the board = rank 1). KREAM is a Nuxt (Vue) server-rendered app, so the same ranking data its API returns is embedded in the page — this actor captures that payload and pulls:

- **The resale ranking** — rank position exactly as KREAM orders it.
- **Product & brand** — full product name and brand.
- **Market signal** — cumulative trading volume (e.g. `거래 12.4만`) and current price (KRW).
- **Category, link & image** — KREAM category path, product URL, and thumbnail.

You choose the board with the `period` input:

| `period` | Board | URL scraped |
|----------|-------|-------------|
| `realtime` (default) | Live top-50 right now | `kream.co.kr/?tab=home_ranking_v2` |
| `weekly` | 7-day best-sellers | `…&date_range_filter=weekly` |
| `monthly` | 30-day best-sellers | `…&date_range_filter=monthly` |

KREAM's ranking board is a **top-50** per period, so `maxItems` caps at 50.

> **Why KREAM?** KREAM is the dominant resale platform in Korea and a leading signal of what's hot in sneakers, streetwear, and collectibles. Its ranking — ordered by real trading activity — is a sharp pulse on Korean youth consumer demand. A daily snapshot feeds trend dashboards, demand forecasting, and drop/hype tracking.

***

### Input

| Field | Type | Description |
|-------|------|-------------|
| `period` | string | `realtime` (default), `weekly`, or `monthly`. Which ranking board to scrape. |
| `maxItems` | integer | Max products to collect, in rank order from the top. Default `50`, max `50` (the board is a top-50). |
| `proxyConfiguration` | object | Proxy settings. **Use a Korean residential proxy** to run on Apify (see below). |

#### Input example

```json
{
  "period": "weekly",
  "maxItems": 50,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "KR"
  }
}
```

***

### Output

Each ranked product is one dataset record. `price_krw` is the plain Korean-won price. `rank` is the product's position on the board (1 = top). `trading_volume` is KREAM's cumulative trade-count label as shown on the card (Korean units, e.g. `거래 12.4만` ≈ 124,000 trades). `category` is KREAM's category path.

```json
{
  "source": "kream",
  "rank": 1,
  "product_id": "748804",
  "name": "Nike Mind 001 Black Chrome",
  "brand": "Nike",
  "price_krw": 189000,
  "trading_volume": "거래 8,900",
  "category": "신발 > 스니커즈",
  "url": "https://kream.co.kr/products/748804",
  "image_url": "https://kream-phinf.pstatic.net/…/p_xxxxx.png",
  "scraped_at": "2026-07-15T11:03:22+09:00"
}
```

A full sample from a real run is in [`samples/sample-output.json`](samples/sample-output.json).

| Field | Meaning |
|-------|---------|
| `source` | Always `"kream"`. |
| `rank` | Position on the ranking board (1 = top), for the chosen `period`. |
| `product_id` | KREAM product id (from the `/products/{id}` link). |
| `name` | Product name. |
| `brand` | Brand name (e.g. `Nike`, `Apple`, `IAB Studio`), or `null`. |
| `price_krw` | Current price in KRW. |
| `trading_volume` | Cumulative trade-count label as shown on the card (Korean units), or `null`. |
| `category` | KREAM category path (Korean), or `null`. |
| `url` | Product detail page URL. |
| `image_url` | Thumbnail image URL. |
| `scraped_at` | ISO-8601 timestamp (KST, UTC+9). |

In the live test, the critical fields — `rank`, `name`, `brand` — populated on **50/50** records, along with `product_id`, `price_krw`, `trading_volume`, `category`, `url`, and `image_url`.

***

### Use cases

- **Daily shopping-trend dashboard** — snapshot the realtime/weekly/monthly board every morning to see what Korea is trading, and how ranks and prices move.
- **Hype & demand intelligence** — track `rank`, `price_krw`, and `trading_volume` over time to spot rising products and resale momentum.
- **Sneaker / streetwear / collectible research** — find fast-moving products and their brand and price profile for sourcing or market entry.
- **AI agents & datasets** — feed a structured, ranked resale feed into trend models, dashboards, or LLM agents.

***

### ⚠️ Requirements & honesty note

KREAM's data API sits behind **Naver's nfront WAF**. Here is exactly what does and doesn't work, verified from a Korean IP:

- ✅ **Real browser from a Korean IP** → passes. This actor launches Chromium and reads KREAM's server-rendered ranking payload straight out of the page. A **headless** browser is enough for KREAM (unlike some bot walls) — no virtual display needed.
- ❌ **Scripted HTTP clients** → `403`. curl, curl\_cffi/chrome impersonation, and Node's own request stack all get blocked by nfront on the API. That's why this actor uses a browser.
- ❌ **Datacenter / non-Korean IP** → blocked (WAF returns `500`/`403` with an empty body). **Apify's free plan runs on US datacenter IPs**, which nfront blocks. To run this on Apify you need a **Korean residential proxy** — configure Apify Proxy with `groups=RESIDENTIAL` and `country=KR` in `proxyConfiguration`.

**Bottom line:** locally, from a Korean consumer connection, this runs with no proxy. On Apify (US datacenter), budget for a **Korean residential proxy** — without one, expect nfront blocks. `likely_works_on_apify_us_datacenter = false` without a KR proxy; this is by design of KREAM's protection, not a bug in the actor. The actor retries transient WAF `500`s with backoff before giving up.

Advanced knobs (env vars, for local experimentation):

| Env var | Effect |
|---------|--------|
| `KREAM_RANKING_SCRAPER_LITE_TEST=1` | Cap to ~8 items for a quick smoke test. |
| `KREAM_RANKING_SCRAPER_HEADLESS=0` | Launch the browser headed (default is headless, which passes KREAM). |

***

### ❓ FAQ

**Is it legal to scrape this data?**
This actor collects only public, non-personal ranking data — the same board any visitor sees on kream.co.kr without logging in. No personal data is collected. You are responsible for how you use the data; see the legality note below.

**Why does it need a Korean residential proxy on Apify?**
KREAM's nfront WAF blocks datacenter and non-Korean IPs. Apify's default/free datacenter IPs (US) get denied. A Korean residential proxy makes the request look like an ordinary Korean visitor. See [Requirements](#-requirements--honesty-note).

**How fresh is the data?**
Every run scrapes the live board at run time. The `realtime` board changes continuously; schedule the actor (e.g. daily) for a rolling resale-trend history.

**What is NOT included?**
No seller/buyer PII, no bid/ask order book, no per-product deep detail — only what's on the public ranking board. `brand`, `trading_volume`, or `category` can be `null` for the occasional item that doesn't expose them.

***

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

Your agent can then pull KREAM resale rankings and Korean shopping-trend 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:

- [coupang-bestseller-scraper](https://apify.com/kdatafactory/coupang-bestseller-scraper) — best-seller rankings from Coupang, Korea's #1 e-commerce site. Pair it with this actor for a fuller Korean shopping-trend dashboard.
- [naver-shopping-best-scraper](https://apify.com/kdatafactory/naver-shopping-best-scraper) — best-seller rankings from Naver Shopping.
- [musinsa-scraper](https://apify.com/kdatafactory/musinsa-scraper) — fashion product data from Musinsa, Korea's top fashion platform.
- [zigzag-scraper](https://apify.com/kdatafactory/zigzag-scraper) — women's-fashion product listings from Zigzag.

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 or account endpoints.
- **No personal data** is collected — only public ranking product attributes.
- Requests are paced: one board load at a time, with backoff retries between attempts, to stay gentle on KREAM's servers.
- You are responsible for using the data in line with KREAM's terms of service and applicable law.

#### Known limitations (honesty note)

- **Bot wall.** KREAM is behind Naver's nfront WAF. This actor needs a **real browser** and, on Apify, a **Korean residential proxy**. Without those, runs will be blocked. `likely_works_on_apify_us_datacenter = false` without a KR proxy — this is by design of KREAM's protection, not a bug in the actor.
- **Board size.** The ranking board is a **top-50** per period; `maxItems` above 50 simply returns the 50 available.
- **Fallback path.** If KREAM changes its page and the ranking payload can't be parsed, the actor falls back to reading the rendered ranking cards — on that path `brand` and `category` come back `null` (they aren't exposed in the rendered card), while `rank`, `name`, `price_krw`, `trading_volume`, and `image_url` are still returned.
- **Korean strings.** `category` and `trading_volume` are Korean-language labels as KREAM shows them.

***

*If this actor saves you time, a rating on the [Store page](https://apify.com/kdatafactory/kream-ranking-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 KREAM best-seller board to scrape. 'realtime' = the live top-50 right now (default), 'weekly' = the 7-day board, 'monthly' = the 30-day board.

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

Maximum number of ranked products to collect, in rank order from the top. KREAM's ranking board is a top-50, so 50 is the effective maximum per period.

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

Proxy settings. KREAM sits behind Naver's nfront WAF, which blocks non-Korean and datacenter IPs, so this defaults to Apify Proxy with the RESIDENTIAL group and country=KR — verified to return the live ranking. Keep this default unless you run from your own Korean residential connection.

## Actor input object example

```json
{
  "period": "realtime",
  "maxItems": 50,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "KR"
  }
}
```

# 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/kream-ranking-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/kream-ranking-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/kream-ranking-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/8kAWdn5BfYJjckZ8W/builds/NFeaXw7ZdmOjx7ILn/openapi.json