# OliveYoung Global & Amore Mall Rankings + Reviews · $2/1k (`leoworks/kbeauty-ranking-review-monitor`) Actor

Track K-beauty bestseller rankings on Olive Young Global (OliveYoung, 올리브영) and Amorepacific's Amore Mall (아모레몰: Sulwhasoo, Laneige, Hera…) and collect cosmetics reviews with optional AI classification — complaint types, sentiment and purchase motive in Korean, English and Japanese. No login.

- **URL**: https://apify.com/leoworks/kbeauty-ranking-review-monitor.md
- **Developed by:** [Leoworks](https://apify.com/leoworks) (community)
- **Categories:** E-commerce, AI, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.70 / 1,000 ranking items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## OliveYoung Global & Amore Mall Rankings + Reviews

**For K-beauty brands, distributors, sourcing and FBA sellers** who need to know what sells every day on **Olive Young Global** (global.oliveyoung.com) and **Amore Mall** (Amorepacific's own store: Sulwhasoo, Laneige, Hera, IOPE, innisfree…) — bestseller rankings by category, with rank changes since the last run, plus the reviews of the ranked products and why buyers complain — for $2 per 1,000 ranking rows and $1 per 1,000 reviews. No login.

> Independent tool — not affiliated with, endorsed by or sponsored by CJ Olive Young or Amorepacific. Names are used only to describe the data sources.

- **Rankings** — rank, product, brand (English + Korean), price, discount, rating and review count, by category
- **Reviews** — text, rating, date, option bought, helpful votes; Amore Mall adds the reviewer's age group and skin type and survey answers (moisture, scent, mildness)
- **AI classification (optional)** — complaint types (delivery, quality/defect, packaging, no effect, skin trouble, price, …), sentiment and purchase motive for each review, with probabilities, in Korean, English and Japanese

**Use it to:** monitor K-beauty bestsellers on Olive Young Global (OliveYoung, 올리브영) and Amore Mall (아모레몰) · track your brand's rank by category · watch competitor launches climb the ranking · read why buyers complain about a product, at scale · K-beauty market research for global brands, distributors and agencies.

### Output sample

Real rows from run `WP5kfeCdkU4CH4fgf` (2026-10-04, Olive Young Global "All" bestsellers, 20 reviews per product, classification on). Reviews are shown as the Actor returns them (English or Japanese here; Korean on Amore Mall); the English in parentheses is added for readers.

Ranking rows (`type: "ranking"`):

| rank | rankChange | brand | productName | price | rating | reviewCount |
|---|---|---|---|---|---|---|
| 1 | 0 | MEDIHEAL | MEDIHEAL Essential Mask Sheet 10ea Set… | $13.50 | 4.9 | 7,761 |
| 2 | 0 | FOODOLOGY | FOODOLOGY Coleology Cutting Jelly 30 Sticks… | $45.21 | 4.7 | 2,145 |
| 3 | 0 | fwee | \[NEW Earl Grey Edition] fwee 3D Voluming… | $11.93 | 4.8 | 1,635 |

Review rows (`type: "review"`):

| brand | rating | date | language | text (first words) | complaint (probability) | sentiment | motive |
|---|---|---|---|---|---|---|---|
| AESTURA | 4 | 2026-09-18 | en | Feels heavy, I would only recommend it t… | skin_trouble (0.65), other (0.54) | negative | unknown |
| AESTURA | 4 | 2026-09-07 | en | Repurchase. Good to calm the skin. Cream… | other (0.80) | positive | repurchase |
| MEDIHEAL | 5 | 2026-10-04 | ja | 何回もリピートするくらい好きなパックです！… (A mask I love enough to repurchase again and again!) | none (0.98) | positive | repurchase |

Every ranking row also has `productId`, `productNameKo`, `brandKo`, `originalPrice`, `discountPercent`, `currency`, `inStock`, `productUrl`, `imageUrl`, `previousRank`, `isNew` and `checkedAtKst`; review rows add `option`, `helpfulVotes` and, on Amore Mall, `reviewer` and `survey` — see **Output** below.

### Input example

The form default — Olive Young Global, all categories, top 5 products with 5 newest reviews each, classified (about $0.05, 6 seconds):

```json
{
  "sources": ["oliveyoung_global"],
  "maxProductsPerRanking": 5,
  "reviewsPerProduct": 5
}
```

For daily monitoring of several rankings:

```json
{
  "sources": ["oliveyoung_global", "amoremall"],
  "oliveyoungCategories": ["skincare", "suncare"],
  "amoremallRankings": ["best_purchased"],
  "maxProductsPerRanking": 30,
  "reviewsPerProduct": 50,
  "reviewSort": "newest",
  "classifyReviews": true
}
```

### Pricing

Pay only for what you collect — no subscription.

| Event | Price | When |
|---|---|---|
| `ranking-item` | $0.002 | One product row of a bestseller ranking (rank, product, price, rating, review count). |
| `review` | $0.001 | One customer review collected (text, rating, date, option and more). |
| `review-judged` | $0.0005 | Complaint types, sentiment and purchase motive for one review (only when classification is on). |

That is **$2 per 1,000 ranking rows**, **$1 per 1,000 reviews** and **$0.50 per 1,000 review classifications** ($1.50 per 1,000 classified reviews). **First run with the form defaults: about $0.05** (5 products, 25 reviews classified, 6 seconds).

**Cost examples**

| Run | Cost |
|---|---|
| Top 100 of one ranking, no reviews | $0.20 |
| Top 20 + 20 reviews each, classified | $0.64 |
| Top 20 + 50 reviews each, not classified | $1.04 |
| Daily top 50 of 3 categories for 30 days, no reviews | $9.00 |

With the free $5 monthly Apify credit you can collect about **3,333 classified reviews** or **2,500 ranking items**.

Failed requests are reported with an `error` row and **not charged**. If you set a maximum cost per run, the Actor stops cleanly when it is reached (classification is switched off first when the budget only covers collection).

### Works with

- **Apify API, JavaScript and Python clients** — start a run and read the dataset like any Actor (`leoworks/kbeauty-ranking-review-monitor`). The **Rankings** and **Reviews** dataset views separate the two row types.
- **Apify Schedules** — a daily schedule gives `previousRank`, `rankChange` and `isNew` for every ranking row; our own monitoring runs this Actor every morning.
- **Claude, Cursor and Claude Code through the Apify MCP server** — see the next section (verified 2026-10-06).
- **Korean Review Classifier** — the same labels for Olive Young Korea or any other review dataset: [leoworks/korean-review-classifier](https://apify.com/leoworks/korean-review-classifier).

### Use with Claude, Cursor or Claude Code (MCP)

Add the Apify MCP server with this Actor as a tool and ask your agent in plain language — for example *"Get today's top 10 skincare bestsellers on Olive Young Global with their newest 5 reviews and tell me which products have skin-trouble complaints."* The agent calls the tool `leoworks--kbeauty-ranking-review-monitor` and reads the rows with `get-dataset-items`.

Claude Desktop or Cursor (`mcp.json`):

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=leoworks/kbeauty-ranking-review-monitor",
      "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" }
    }
  }
}
```

Claude Code: `claude mcp add --transport http apify "https://mcp.apify.com?tools=leoworks/kbeauty-ranking-review-monitor" --header "Authorization: Bearer YOUR_APIFY_TOKEN"`. Leave out the header to sign in with OAuth in the browser instead. Your Apify token is in Console → Settings → API & Integrations. We verified this setup with the Apify MCP server (v0.17.2) on 2026-10-06.

### How to use

1. Pick the rankings: Olive Young Global categories (Skincare, Makeup, Suncare, Face Masks, …) and/or Amore Mall (most purchased or most clicked; daily, weekly or monthly; by category and age group).
2. Set **Products per ranking** and **Reviews per product** (0 = rankings only).
3. Optional: **Only these brands** to keep just your brand and competitors (the whole top 100 is searched, ranks are kept), or **Extra product pages** to collect reviews of specific products.
4. Run it once, or schedule it daily. From the second run on, ranking rows show the change since the previous run (`rankChange`, `isNew`).

### Output

Each row has a `type`: `ranking` or `review`. The **Rankings** and **Reviews** tabs show them separately.

```json
{
  "type": "ranking",
  "surface": "oliveyoung_global",
  "ranking": "bestsellers",
  "category": "Skincare",
  "rank": 1,
  "previousRank": 3,
  "rankChange": 2,
  "isNew": false,
  "productId": "GA260136559",
  "productName": "…",
  "brand": "Anua",
  "brandKo": "아누아",
  "price": 21.9,
  "originalPrice": 32,
  "discountPercent": 31.56,
  "currency": "USD",
  "rating": 4.8,
  "reviewCount": 1305,
  "productUrl": "https://global.oliveyoung.com/product/detail?prdtNo=GA260136559",
  "checkedAtKst": "2026-10-03 18:13:14 KST"
}
```

```json
{
  "type": "review",
  "surface": "amoremall",
  "productId": "63917",
  "brand": "설화수",
  "rating": 2,
  "date": "2026-10-01",
  "text": "…",
  "language": "ko",
  "reviewer": { "ageGroup": "50대 이상", "gender": "여성", "skinType": "건성", "skinConcern": "건조함" },
  "survey": [{ "question": "보습감", "answer": "촉촉해요" }],
  "labels": {
    "complaint": [{ "label": "packaging", "labelKo": "포장", "probability": 0.91 }],
    "sentiment": { "label": "negative", "labelKo": "부정", "probability": 0.88, "confidence": 0.8 },
    "motive": { "label": "repurchase", "labelKo": "재구매", "probability": 0.7, "confidence": 0.6 }
  }
}
```

Prices are in USD on Olive Young Global and in KRW on Amore Mall. Reviews in other languages (Chinese, Spanish, …) are collected but not classified (`classifySkipped`), and not charged for classification.

#### Product details (optional, Olive Young Global)

Turn on **Product details** to add each Olive Young Global ranking product's information sheet as `productDetails` — no extra charge:

```json
"productDetails": {
  "ingredients": "Water, Melaleuca Alternifolia (Tea Tree) Leaf Water, Propanediol, Glycerin, …",
  "volume": "50mL(+10ml*2ea+Tube Ringer)",
  "idealFor": "For all skin types",
  "countryOfManufacture": "South Korea",
  "manufacturer": "Kolmar Korea Co., Ltd. / …",
  "allFields": { "Expiration date (or expiration date after opening)": "36 months from the date of manufacture", "…": "…" }
}
```

Supplements use their own sheet (raw materials, nutrition facts); the same keys are filled where they exist. Amore Mall rows are not covered.

#### Review summary by product (REPORT)

When reviews are collected, the run also saves a **REPORT** record (Output tab → *Review summary by product*) at no extra charge: per product, the average rating, complaint rate and complaint mix, sentiment shares, purchase motives and the 3 strongest complaint reviews — plus the same for all products together. Shares are computed over classified reviews; unclassified reviews count for the average rating only.

```json
{
  "group": "oliveyoung_global:GA260136559",
  "brand": "Anua",
  "productName": "…",
  "reviews": 50,
  "classified": 48,
  "averageRating": 4.6,
  "complaintRate": 0.125,
  "complaints": [{ "label": "skin_trouble", "count": 3, "share": 0.063 }],
  "sentiment": { "positive": 0.833, "neutral": 0.104, "negative": 0.063 },
  "exampleComplaints": [{ "complaint": "skin_trouble", "rating": 2, "text": "…" }]
}
```

### Classification accuracy

Measured on hand-labelled Olive Young Global reviews (about half with 1–3 stars): complaint type **87%** on English reviews it had not seen before, **93%** on Japanese reviews. Korean reviews use the same model as our [Korean Review Classifier](https://apify.com/leoworks/korean-review-classifier). Automated labels can be wrong; check samples before making big decisions.

### Limits

| Item | Limit |
|---|---|
| Ranking depth | Top 100 per ranking |
| Reviews per product | Up to 1,000 per run (newest first by default) |
| Review orders | Olive Young: newest, most helpful, lowest/highest rating, oldest · Amore Mall: newest, most helpful |
| Classification languages | Korean, English, Japanese |
| Speed | 1,000 reviews with classification on (867 classified) in about 1 min (measured 2026-10-03); rankings take seconds |
| Personal data | No account names or IDs are output; Amore Mall reviewer age group and skin type only |

### FAQ

**Which AI makes the judgments?** Jev, TypeSafe's decision model (version `jev-1.13.0`, pinned). Jev answers each label with a calibrated probability instead of generated text, so the same input gets the same answer from run to run. We re-measure accuracy on our labelled test set before we change the model version. Only the review text and its rating are sent to Jev; reviewer profiles and account data are not.

**Does it cover Olive Young Korea (oliveyoung.co.kr)?** No. The Korean store blocks automated access. For Olive Young Korea reviews, run a dedicated review scraper and classify its dataset with our [Korean Review Classifier](https://apify.com/leoworks/korean-review-classifier).

**Why does Amore Mall only show Amorepacific brands?** Amore Mall is Amorepacific's own store, so its ranking covers its own brands (Sulwhasoo, Laneige, Hera, IOPE, Primera, …).

**How is the change since the last run calculated?** Each run saves the whole fetched ranking (top 100) in a key-value store in your own Apify account (default name `kbeauty-ranking-history`). The next run compares against it: `rankChange` = previous rank − current rank (positive = moved up), `isNew` = not in the previous ranking. Use a different store name per project, or leave the field empty to turn this off. No extra charge.

**How often do the rankings change?** Olive Young Global bestsellers update during the day; Amore Mall shows the update time in `rankingUpdatedAt`. A daily schedule is enough for most tracking.

**Does it need an account?** No. Both stores are read without logging in.

### Reviews and support

If this Actor saved you time, a short review on Apify Store helps others find it. Questions or a category that does not work? Open an issue in the **Issues** tab — we answer within a day.

### Changelog

See the Changelog tab.

# Changelog

This Actor's version history is a separate document: https://apify.com/leoworks/kbeauty-ranking-review-monitor/changelog.md

# Actor input Schema

## `sources` (type: `array`):

Which bestseller rankings to collect. Leave empty to only collect reviews for the product pages below.

## `oliveyoungCategories` (type: `array`):

Bestseller tabs to collect (one ranking per category).

## `amoremallRankings` (type: `array`):

Amore Mall ranking tabs to collect.

## `amoremallCategories` (type: `array`):

Amore Mall categories (one ranking per category and ranking type).

## `amoremallPeriod` (type: `string`):

Ranking period on Amore Mall.

## `amoremallAgeGroup` (type: `string`):

Buyer age group for the Amore Mall ranking.

## `maxProductsPerRanking` (type: `integer`):

Top N products of each ranking (rankings have up to 100 products). Each product row is charged as ranking-item. The form starts at 5 for a quick first run; raise it up to 100 (default when omitted via API: 20).

## `brands` (type: `array`):

Optional. Keep only products of these brands (English or Korean name, e.g. COSRX, 설화수). The whole ranking (up to 100) is searched and the original rank is kept.

## `productUrls` (type: `array`):

Optional. Olive Young Global or Amore Mall product pages to collect reviews for, in addition to the ranked products.

## `reviewsPerProduct` (type: `integer`):

Reviews to collect for each product (0 = rankings only). Charged per review. The form starts at 5 for a quick first run; raise it up to 1,000 (default when omitted via API: 20).

## `reviewSort` (type: `string`):

Amore Mall supports Newest and Most helpful; other orders fall back to Newest there.

## `classifyReviews` (type: `boolean`):

Add complaint types, sentiment and purchase motive to each Korean, English or Japanese review (charged per review as review-judged).

## `complaintThreshold` (type: `number`):

Minimum probability (0–1) for a complaint type to be reported.

## `includeProductDetails` (type: `boolean`):

Add each Olive Young Global ranking product's information sheet as `productDetails`: full ingredient list, volume, skin type it is made for, country of manufacture, manufacturer, plus all other sheet fields. One extra request per product; no extra charge. Amore Mall rows are not covered.

## `rankHistoryStore` (type: `string`):

Name of a key-value store in your Apify account that keeps the last snapshot of each ranking. Ranking rows then show `previousRank`, `rankChange` (positive = moved up) and `isNew` (not in the previous ranking). Run on a schedule to track movement. Use a different name per project; leave empty to turn this off. No extra charge.

## `maxConcurrency` (type: `integer`):

Rankings and products processed in parallel.

## `residentialFallback` (type: `boolean`):

Retry failing requests through Korean residential proxy.

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

Default Apify datacenter proxy works for both sites.

## `healthCheck` (type: `boolean`):

Internal: fail the run when results look degraded (used by the developer's scheduled checks).

## Actor input object example

```json
{
  "sources": [
    "oliveyoung_global"
  ],
  "oliveyoungCategories": [
    "all"
  ],
  "amoremallRankings": [
    "best_purchased"
  ],
  "amoremallCategories": [
    "all"
  ],
  "amoremallPeriod": "daily",
  "amoremallAgeGroup": "all",
  "maxProductsPerRanking": 5,
  "brands": [],
  "productUrls": [],
  "reviewsPerProduct": 5,
  "reviewSort": "newest",
  "classifyReviews": true,
  "complaintThreshold": 0.5,
  "includeProductDetails": false,
  "rankHistoryStore": "kbeauty-ranking-history",
  "maxConcurrency": 5,
  "residentialFallback": true,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "healthCheck": false
}
```

# Actor output Schema

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

No description

## `summary` (type: `string`):

No description

## `report` (type: `string`):

No description

# 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 = {
    "sources": [
        "oliveyoung_global"
    ],
    "maxProductsPerRanking": 5,
    "reviewsPerProduct": 5,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("leoworks/kbeauty-ranking-review-monitor").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 = {
    "sources": ["oliveyoung_global"],
    "maxProductsPerRanking": 5,
    "reviewsPerProduct": 5,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("leoworks/kbeauty-ranking-review-monitor").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 '{
  "sources": [
    "oliveyoung_global"
  ],
  "maxProductsPerRanking": 5,
  "reviewsPerProduct": 5,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call leoworks/kbeauty-ranking-review-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,leoworks/kbeauty-ranking-review-monitor"
        }
    }
}
```

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/txQ8OSYukXLq9QjL4/builds/sJZp42pIgYUcaItTq/openapi.json