# Olive Young Scraper - Korean Beauty Rankings API (`kdatafactory/oliveyoung-scraper`) Actor

Scrape Olive Young bestseller rankings, prices & product data as clean English JSON. Track trending Korean skincare & K-beauty before it hits Amazon. Pay-per-result API for FBA sellers, brands & sourcing teams.

- **URL**: https://apify.com/kdatafactory/oliveyoung-scraper.md
- **Developed by:** [Seok June Park](https://apify.com/kdatafactory) (community)
- **Categories:** E-commerce, Developer tools
- **Stats:** 4 total users, 2 monthly users, 100.0% runs succeeded, 1 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

## OLIVE YOUNG Global K-Beauty Scraper 🧴

Scrape **best-seller rankings, keyword search results, and category listings** from
[OLIVE YOUNG Global](https://global.oliveyoung.com) — Korea's #1 health & beauty retailer
and the single most important storefront for K-beauty. Get clean, structured product data
(name, brand, USD price, discount, rating, review count, image, product URL) in JSON, CSV,
Excel, or via API.

Built for **global K-beauty sellers, dropshippers, and market researchers** who need to
track what's actually selling in Korea — priced and named in English, ready to use.

> **Try it free.** Apify's free plan includes $5 of monthly platform credit — roughly **2,500 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 it returns a structured product feed:

| Mode | What you get | Example input |
|------|--------------|---------------|
| `ranking` | The live **Best Sellers** sales ranking (up to ~100 products, with `rank`) | `{ "mode": "ranking" }` |
| `search` | Products matching a **keyword**, paginated & sortable | `{ "mode": "search", "query": "vitamin c serum" }` |
| `category` | Products in a **top-level category** | `{ "mode": "category", "query": "Skincare" }` |

Data comes straight from OLIVE YOUNG Global's own **public JSON APIs** (the same endpoints
the website's front-end calls) — so it's fast and reliable, no brittle HTML scraping.

**Available categories:** `Skincare`, `Makeup`, `Bath & Body`, `Hair`, `Face Masks`,
`Suncare`, `K-Pop`, `Makeup Brush & Tools`, `Accessories`, `Wellness`, `Men's Care`,
`Supplements`, `Food & Drink`, `Special Value Sets`.

***

### 📥 Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `mode` | string | `ranking` | `ranking`, `search`, or `category`. |
| `query` | string | — | Keyword (search) or category name (category). Optional for ranking. |
| `maxItems` | integer | `100` | Max products to return. Ranking returns up to ~100 in one request. |
| `sort` | string | `MOST_POPULAR` | `MOST_POPULAR`, `MOST_RELEVANT`, `MOST_REVIEWS`, `LATEST_REGISTRATION`, `LOWEST_PRICE`, `HIGHEST_PRICE` (search & category only). |
| `proxyConfiguration` | object | RESIDENTIAL | Apify proxy. **Keep RESIDENTIAL enabled** (see note below). |

**Input example — top skincare products by review count:**

```json
{
  "mode": "category",
  "query": "Skincare",
  "maxItems": 100,
  "sort": "MOST_REVIEWS"
}
```

***

### 📤 Output

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

```json
{
  "source": "oliveyoung",
  "product_id": "GA230518746",
  "name": "SKIN1004 Madagascar Centella Hyalu-Cica Water-Fit Sun Serum 50mL*2ea (Twin pack)",
  "brand": "SKIN1004",
  "price_usd": 28,
  "sale_price_usd": 22.4,
  "currency": "USD",
  "rating": 4.9,
  "review_count": 9958,
  "category": "search/serum",
  "rank": 1,
  "is_sold_out": false,
  "url": "https://global.oliveyoung.com/product/detail?prdtNo=GA230518746",
  "image_url": "https://cdn-image.oliveyoung.com/prdtImg/1595/430be104-fda8-4dfd-a3a4-34f7df3cfa46.jpg",
  "scraped_at": "2026-07-07T09:32:24.927+09:00"
}
```

**Field notes**

- `price_usd` / `sale_price_usd` — displayed in **USD** (the global storefront shows
  post-margin USD prices). When a product is not discounted, `sale_price_usd` is `null`.
- `rating` / `review_count` — populated in `search` and `category` modes. The ranking feed
  does not expose a per-product review count, so those fields may be `null` in `ranking`
  mode.
- `rank` — 1-based position within the returned list/ordering.
- A full 25-record sample lives in [`samples/sample-output.json`](samples/sample-output.json).

***

### 💡 Use cases

- **Price monitoring** — track USD prices and discounts on hero SKUs across time.
- **K-beauty market research** — see what's trending in Korea by category and review volume.
- **Dropshipping / sourcing** — find high-rated, high-review 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. Pairs with the companion **K-Beauty API** on RapidAPI.
- **Competitive intelligence** — monitor best-seller ranking shifts for your brand vs rivals.

***

### 🌐 Data source & proxy

This actor targets **OLIVE YOUNG Global** (`global.oliveyoung.com`), the international
storefront — chosen deliberately because it serves **English product names and USD prices**,
which is exactly what global K-beauty sellers need (the Korean-domestic site returns Korean
text and KRW). Data is read from the storefront's **public** ranking and search JSON APIs.

> **⚠️ Use Apify RESIDENTIAL proxy.** OLIVE YOUNG's WAF geo-filters datacenter and
> non-Korean IP ranges. The default input keeps `RESIDENTIAL` proxy enabled — leave it on.
> Without a suitable proxy you may receive `HTTP 403`/`429` or a challenge page instead of
> JSON, and the run will fail with a clear "Blocked by anti-bot" error.

***

### ⚖️ Rate & legality note

- Only **public, non-personal** catalog data is collected — product listings that anyone can
  see without logging in. **No customer or reviewer personal data** (no nicknames, profiles,
  or IDs) is ever scraped.
- Requests are **rate-limited** (sequential pages, ≥500 ms delay) to stay light on the site.
- You are responsible for complying with OLIVE YOUNG'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 to OLIVE YOUNG Global sees without logging in. No personal data is collected. You are responsible for how you use the data; see the legality note above.

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

**Do I need to configure proxies?**
No — the default settings work out of the box. The default input keeps Apify RESIDENTIAL proxy enabled, which is what OLIVE YOUNG's WAF requires; just leave it on.

**How fresh is the data?**
Every run scrapes the live site at run time. Schedule the actor for recurring snapshots.

**What is NOT included?**
No customer or reviewer personal data (no nicknames, profiles, or IDs) is ever scraped. In `ranking` mode the feed does not expose per-product review counts, so `rating`/`review_count` may be `null` there.

***

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

Your agent can then pull the current Olive Young best-seller ranking with USD 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:

- [hwahae-scraper](https://apify.com/kdatafactory/hwahae-scraper) — Korean cosmetics ratings and ingredient analysis data
- [glowpick-scraper](https://apify.com/kdatafactory/glowpick-scraper) — Korean beauty product rankings and reviews
- [musinsa-scraper](https://apify.com/kdatafactory/musinsa-scraper) — Korea's top fashion platform product data
- [kurly-scraper](https://apify.com/kdatafactory/kurly-scraper) — Korean premium grocery and fresh-food listings

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/oliveyoung-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. 'ranking' = the best-seller sales ranking. 'search' = keyword search results. 'category' = products in a top-level category.

## `query` (type: `string`):

For 'search': the keyword (e.g. "vitamin c serum"). For 'category': a category name (e.g. "Skincare", "Makeup", "Suncare", "Hair"). For 'ranking': optional category-id filter, leave empty for the overall best-seller list.

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

Maximum number of products to return. Ranking mode returns up to ~100 in a single request.

## `sort` (type: `string`):

Result ordering for search/category modes.

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

Apify proxy settings. RESIDENTIAL is strongly recommended — the storefront's WAF geo-filters datacenter IPs.

## Actor input object example

```json
{
  "mode": "ranking",
  "query": "vitamin c serum",
  "maxItems": 100,
  "sort": "MOST_POPULAR",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

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

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/7cnOAdIUtlnncl0OG/builds/9hMazVJqOoTPTuneq/openapi.json