# 일본 화장품 랭킹 앳코스메 @cosme Top 50 평점·가격 (`jpmarketdata/cosme-beauty-market-kr`) Actor

일본 최대 뷰티 리뷰 사이트 @cosme(앳코스메)의 카테고리 하나를 고르면 그 랭킹 Top 50 전체를 한 번에 요약해 줍니다. 평점 대표값과 범위(0~7점), 세금 포함 정가 대표값과 범위, 리뷰 수 중앙값과 최대값, 브랜드 수, 순위 상승/하락/신규 개수, 랭킹 갱신일과 집계 기간을 돌려줍니다. 카테고리당 $0.02, 결과 없으면 과금 없음. @cosme Japan top-50 ranking stats. Unofficial.

- **URL**: https://apify.com/jpmarketdata/cosme-beauty-market-kr.md
- **Developed by:** [h ichi](https://apify.com/jpmarketdata) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 96.6% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 category ranking summaries

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/actors/running/actors-in-store.md#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

## 일본 화장품 랭킹 앳코스메 @cosme Top 50 평점·가격

**하는 일:** 일본 최대 뷰티 리뷰 사이트 @cosme(앳코스메)의 랭킹 카테고리 하나를 고르면 그 Top 50 전체의 평점·리뷰 수·가격을 한 번에 요약해 줍니다.

**입력:** 랭킹 카테고리, 예: `item/1069`(리퀴드 클렌징), 또는 랭킹 페이지 URL을 붙여넣기.

**결과:** 랭킹에 오른 50개 전체 기준: 평점 대표값과 범위(0~7점); 세금 포함 정가(가장 싼 용량)의 대표값과 범위; 리뷰 수 중앙값과 최대값; 브랜드 수; 순위 상승 / 하락 / 신규 개수; 랭킹 갱신일과 집계 기간. 선택: 제품 1개당 1행. 리뷰 본문은 절대 수집하지 않음.

**가격:** 카테고리당 $0.02(입력한 카테고리마다 과금), 목록까지 원하면 제품당 +$0.002(기본값 꺼짐). 결과 없음 = 과금 없음.

**예시:** `item/1069` 입력 → 제품 50개 · 평점 대표값 5.1(범위 3.7–6.9) · 세금 포함 정가 대표값 ¥1,760(범위 ¥352–7,260, 가격이 표시된 42개 기준) · 브랜드 42개 · 상승 8, 하락 19, 신규 2.

**In English:** Pick a category on @cosme, Japan's biggest beauty review site, and get its whole top-50 ranking as one summary. You get typical rating and range, typical list price and range, review-count median and max, number of brands, rank movement counts and the ranking date with the period it covers.

> 비공식 도구 / Unofficial — @cosme와 무관하며 공개 페이지만 읽습니다. Not affiliated with @cosme; reads public pages only.

### 한국어

#### 누구를 위한 것인가 (Who this is for)

**한국 뷰티 바이어에게 J뷰티 랭킹은 두 가지를 동시에 뜻합니다 — 경쟁 신호이자 소싱 신호.** 일본에서 지금 무엇이 팔리는지는 K뷰티 브랜드에게는 경쟁 벤치마크이고, 구매대행·병행수입·역직구 셀러에게는 그대로 매입 리스트입니다. 그리고 그 질문의 일본 쪽 표준 답안은 하나로 정해져 있습니다: **@cosme(앳코스메)의 카테고리 랭킹**. 일본 뷰티 리뷰 시장을 압도적으로 점유한 플랫폼이고, 그 랭킹이 시장의 공개 수요 신호에 가장 가까운 것이지만 — 공개 API는 없습니다.

이 Actor는 랭킹 한 장을 바로 소싱 시트에 붙일 수 있는 한 줄의 시세 레코드로 바꿉니다:

- **`rating` — 최저값, 중간 50% 구간, 중앙값, 최고값 (@cosme의 0~7점 척도)**. 카테고리가 5.1점이 빽빽한 접전인지, 상위권에 진짜 품질 격차가 있는지 보입니다.
- **`priceJpy` — 같은 방식의 가격 구간, 제품별 최저 용량 가격 기준**. 달러 환산도 함께. 이 카테고리는 지금 어느 가격대가 이기고 있는가?
- **`reviewCount` — 리뷰 *수*의 중앙값과 최대값**. 리뷰 8,727개짜리 2002년 스테디셀러와 리뷰 17개짜리 2026년 신제품이 세 계단 차이로 나란히 있을 때, 그 차이를 말해 주는 건 리뷰 수뿐입니다.
- **`brandTop` / `brandCount` / `topBrandShare`** — 브랜드 집중도: 한 회사가 먹은 카테고리인가, 42개 브랜드가 붙는 판인가.
- **`rankMovement`** — 상승 / 유지 / 하락 / 신규 진입의 구성비. 카테고리가 물갈이 중인지 굳어 있는지가 여기서 나옵니다.
- **`bestCosmeCount`**(베스트코스메 수), **`variantsPerProductMedian`**, 그리고 랭킹 자체의 **`rankingUpdatedOn`**(갱신일)과 **`aggregationPeriod`**(집계 기간).
- 선택: 랭킹에 오른 제품 전부(순위, 등락, 브랜드, 평점, 리뷰 수, **모든 용량·가격 쌍**, 출시일, 베스트코스메 여부, 제품 URL).

로그인 불필요, API 키 불필요, 실행 사이에 아무것도 저장하지 않습니다.

이 리스팅은 영문판 [@cosme Japan Beauty Ranking — Top 50 Ratings & Prices](https://apify.com/jpmarketdata/cosme-beauty-market-checker)의 **한국어 언어 패키지**입니다. 읽는 페이지도 계산하는 숫자도 완전히 동일하고, 제목·스토어 설명·문서·입력 라벨만 한국어로 다시 썼습니다.

#### ⚠️ 이 Actor가 의도적으로 **수집하지 않는** 것

@cosme는 리뷰 사이트이므로 이 부분은 분명히 밝혀 둡니다:

> **리뷰 본문, 작성자 이름, 작성자 프로필, 리뷰 사진은 절대 수집하지 않습니다 — 설계상 그렇고, 영구적으로 그렇습니다.**

| 수집하지 않는 것 | 이유 |
|---|---|
| 리뷰 본문(사람이 쓴 글) | 사용자가 창작한 개인 콘텐츠입니다. 통계에는 필요 없습니다 |
| 작성자 이름, 나이, 피부 타입, 프로필 페이지 | 이 제품의 대상이 아닌 개인에 대한 개인정보입니다 |
| 리뷰 사진 | 마찬가지로 사용자가 올린 개인 콘텐츠입니다 |
| 리뷰 퍼머링크와 제품 페이지의 `/review/` 탭 URL | 링크를 내보내는 것은 포인터를 내보내는 것입니다. **어떤 레코드에도 `.../review/` URL은 들어가지 않습니다** — `url`은 언제나 제품 페이지입니다 |

**실제로 수집하는 것은 리뷰의 *개수* — 숫자 하나 —** 와 집계된 평점 값뿐입니다. 그것이 이 Actor의 리뷰 쪽 발자국 전부입니다.

이것은 문장으로 한 약속이 아니라 코드로 강제된 사항입니다. `src/main.py`에는 `DELIBERATE EXCLUSION` 블록과 실행 가능한 가드 `review_text_leaks(record)`가 있고, 이 함수는 내보내는 레코드의 모든 값을 훑어 리뷰 마커(`review-body`, `review-text`, `reviewer-desc`, `/reviewer/`, `/review/`, `/reviews/`)를 찾아냅니다. **테스트 스위트는 모든 레코드 형태에 대해 이 함수가 `[]`를 반환한다고 단언합니다.** 나중에 누군가 제품 블록을 통째로 태그만 벗겨 복사하거나 리뷰 탭 링크를 딸려 오게 만들면 마커도 함께 들어오고, 빌드가 실패합니다.

#### 개요 Overview

카테고리마다 **`category_summary` 요약 레코드 1건**을 반환합니다: 평점의 중앙값과 중간 50% 구간, 가격의 중앙값과 중간 50% 구간, 리뷰 수 중앙값·최대값, 브랜드 집중도, 순위 등락 구성, 베스트코스메 수, 랭킹 갱신일과 집계 기간, 환율. 개별 제품 출력을 켜면 랭킹에 오른 제품마다 레코드를 하나씩 더 반환합니다.

#### 입력 Input

| 필드 | 예시 | 설명 |
|---|---|---|
| `categories` | `["item/1069"]` | `<axis>/<id>`, axis ∈ `item` / `effect` / `skin` / `age` / `pickup` — 두 조각을 함께 주소에서 옮겨 오세요(id 는 axis 마다 따로 매겨집니다). 랭킹 URL 전체를 붙여 넣어도 정규화됩니다. 자주 쓰는 랭킹의 id 는 아래 표에 있습니다. 읽을 수 없는 카테고리는 이유와 함께 건너뛰고 나머지는 그대로 실행됩니다. 카테고리당 $0.02 |
| `pagesPerCategory` | `5` | 페이지당 10개. **랭킹은 50위까지뿐**이므로 5가 전체이자 최대값입니다. 상위 10개만 빠르게 보려면 낮추세요 |
| `includeIndividualItems` | `false` | 켜면 랭킹 제품마다 레코드를 출력합니다(기본값 꺼짐, 건당 +$0.002) |
| `convertToUsd` | `true` | 현재 환율로 달러 통계를 함께 붙입니다 |

```json
{
    "categories": ["item/1069"],
    "pagesPerCategory": 5,
    "includeIndividualItems": false,
    "convertToUsd": true
}
```

##### 카테고리 id 찾는 법

브라우저에서 아무 @cosme 랭킹이나 열고 주소를 복사하면 됩니다: `https://www.cosme.net/categories/item/1069/ranking/` → `item/1069`. `item` 축은 제품 유형별 랭킹(클렌징, 세럼, 립스틱…)이고 `effect`, `skin`, `age`, `pickup`은 @cosme의 다른 랭킹 축으로 사용법은 같습니다.

**axis 와 id 는 주소에서 함께 옮겨 오세요.** id 는 axis 마다 따로 매겨져 있어서, `effect/1069` 는 "같은 랭킹을 효과별로 본 것"이 아니라 실제로 존재하는 다른 랭킹(실측 2026-08-18: 향수 계열)이며 정상 행으로 돌아와 과금됩니다. `categoryName` 이 예상과 다르면 먼저 axis 를 확인하세요.

사이트가 일본어 전용이라, 가장 많이 찾는 랭킹의 id 를 적어 둡니다(2026-08-18 @cosme 자체 카테고리 링크에서 읽음):

| 랭킹 | 코드 | 랭킹 | 코드 |
|---|---|---|---|
| 클렌징 폼(洗顔料) | `item/900` | 파운데이션(ファンデーション) | `item/916` |
| 메이크업 리무버(クレンジング) | `item/901` | 메이크업 베이스(化粧下地) | `item/917` |
| 스킨·토너(化粧水) | `item/902` | 페이스 파우더(フェイスパウダー) | `item/918` |
| 로션·에멀전(乳液) | `item/1004` | 쿠션 파운데이션(クッションファンデ) | `item/1200` |
| 세럼(美容液) | `item/1006` | BB 크림(BBクリーム) | `item/1201` |
| 페이스 크림(フェイスクリーム) | `item/1005` | CC 크림(CCクリーム) | `item/1202` |
| 시트 마스크·팩(シートマスク) | `item/1007` | 립스틱(口紅) | `item/1015` |
| 눈·입가 케어(目元・口元ケア) | `item/905` | 리퀴드 루즈(リキッドルージュ) | `item/1221` |
| 오일 클렌징(オイルクレンジング) | `item/1002` | 마스카라(マスカラ) | `item/911` |
| 클렌징 밤(クレンジングバーム) | `item/1192` | 아이라이너(アイライナー) | `item/910` |
| 리퀴드 클렌징(リキッドクレンジング) | `item/1069` | 아이섀도(アイシャドウ) | `item/912` |
| 자외선 차단(日焼け対策) | `item/801` | 블러셔(チーク) | `item/914` |
| 샴푸·컨디셔너(シャンプー) | `item/920` | 향수(香水・フレグランス) | `item/804` |
| 핸드크림(ハンドクリーム) | `item/1035` | 매니큐어(マニキュア) | `item/1023` |

더 넓은 대분류가 필요하면: 스킨케어 `item/800`, 메이크업 `item/802`, 베이스 메이크업 `item/803`, 헤어케어 `item/805`, 바디·오럴케어 `item/806`, 뷰티 가전 `item/808`, 서플리먼트 `item/809`.

`effect` 축: 미백 `effect/1005`, 모공 `effect/1003`, 여드름 `effect/1004`, 보습 `effect/1002`, 안티에이징 `effect/1008`, 각질 케어 `effect/1062`, 자연주의·오가닉 `effect/1087`.

2026-08-18 확인: `item/900`, `item/916`, `item/804`, `effect/1005` 모두 랭킹 상품이 한 페이지 가득 돌아왔습니다.

읽는 것은 **메인 랭킹**뿐입니다. `ranking-rise`(急上昇), `ranking-age`(年代), `ranking-skin`(肌質), `ranking-search`(お好み) URL을 붙여 넣으면 조용히 메인 랭킹으로 바꿔 과금하지 않고 명확한 메시지와 함께 실패합니다 — 그쪽은 결과 집합도 집계 기간도 다른 별개의 랭킹이기 때문입니다.

#### 출력 Output

필드명은 영어 그대로 둡니다. API 표면이기 때문입니다.

*2026-08-01 실측 (@cosme 실제 페이지, 카테고리 `item/1069` リキッドクレンジング / 리퀴드 클렌징)*

```json
{
  "type": "category_summary",
  "category": "item/1069",
  "categoryName": "リキッドクレンジング",
  "rankingUpdatedOn": "2026-07-31",
  "aggregationPeriod": { "from": "2026-04-30", "to": "2026-07-29", "raw": "2026/4/30〜2026/7/29" },
  "productsRanked": 50,
  "totalListingsFound": 50,
  "pagesFetched": 5,
  "ratingScale": 7,
  "rating":   { "min": 3.7, "q1": 4.9,  "median": 5.1,  "q3": 5.4,  "max": 6.9,  "count": 50 },
  "priceJpy": { "min": 352, "q1": 1463, "median": 1760, "q3": 3242, "max": 7260, "count": 42 },
  "reviewCount": { "median": 186, "max": 8727, "count": 50 },
  "brandTop": [["ビオデルマ", 4], ["Chacott COSMETICS(チャコット・コスメティクス)", 2], ["ビフェスタ", 2]],
  "brandCount": 42,
  "topBrandShare": 0.08,
  "rankMovement": { "up": 8, "stay": 21, "down": 19, "new": 2, "unknown": 0 },
  "bestCosmeCount": 2,
  "variantsPerProductMedian": 1,
  "checkedAt": "2026-08-01T05:41:12.884Z",
  "sourceUrl": "https://www.cosme.net/categories/item/1069/ranking/",
  "priceUsd": { "min": 2.3, "q1": 9.55, "median": 11.49, "q3": 21.17, "max": 47.41 },
  "exchangeRateJpyUsd": 0.00653
}
```

`q1` 과 `q3` 은 중간 50% 구간의 양 끝입니다. 즉 50개 중 절반이 평점 4.9–5.4 사이, 가격이 있는 42개 중 절반이 ¥1,463–¥3,242 사이입니다.

선택 출력인 제품 레코드(`type: "product"`, 같은 2026-08-01 실측) — `url`은 **제품** 페이지이고 모든 용량·가격 쌍이 그대로 보존됩니다:

```json
{
  "type": "product",
  "category": "item/1069",
  "categoryName": "リキッドクレンジング",
  "rank": 1,
  "rankMovement": "stay",
  "rankMovementJa": "順位変わらず",
  "productId": "2892367",
  "name": "サンシビオ エイチツーオー D",
  "brand": "ビオデルマ",
  "brandId": "4680",
  "ratingScale": 7,
  "rating": 5.4,
  "reviewCount": 8727,
  "minPriceJpy": 1463,
  "priceVariants": [
    { "size": "100ml", "priceJpy": 1463 },
    { "size": "250ml", "priceJpy": 3069 },
    { "size": "500ml", "priceJpy": 3810 },
    { "size": "850ml", "priceJpy": 5060 }
  ],
  "priceVariantCount": 6,
  "priceLabelJa": "税込価格",
  "releaseDate": "2002-07-05",
  "releaseDateRaw": "2002/7/5",
  "bestCosme": true,
  "url": "https://www.cosme.net/products/2892367/"
}
```

#### 각 통계의 기준(basis)

- **평점 척도는 0~5점이 아니라 0~7점입니다.** @cosme는 7점 만점으로 평가하므로 5.4는 불가능한 숫자가 아니라 아주 강한 제품입니다. 다른 사이트의 별 5개 평점과 실수로 비교하지 못하도록 모든 레코드가 `ratingScale: 7`을 달고 나옵니다. (5점 척도로 환산: `rating / 7 * 5`.)
- **집계 기간은 답의 일부입니다.** @cosme는 약 3개월 롤링 윈도로 각 랭킹을 다시 계산하고 두 날짜를 페이지 헤더에 게시합니다. 두 값 모두 `rankingUpdatedOn`과 `aggregationPeriod`로 모든 레코드에 실립니다. 윈도가 같아야 두 랭킹이 비교 가능하며, 윈도 없는 스냅숏은 해석할 수 없으므로 절대 생략하지 않습니다.
- **랭킹은 50위까지이고, 그 50개를 전부 읽습니다 — 표본이 아닙니다.** `productsRanked`는 보통 정확히 50(페이지당 10 × 5페이지)이므로 중앙값과 중간 50% 구간은 추정값이 아니라 랭킹 집합 자체의 값입니다. 6페이지는 존재하지 않습니다.
- **제품 하나에 가격 여러 개.** 일본 화장품은 한 줄에 여러 용량을 함께 싣는 경우가 많습니다(「税込価格：100ml・1,463円 / 250ml・3,069円 / 500ml・3,810円」). 모든 쌍을 파싱하며, `priceJpy`에 들어가는 대표 가격은 **가장 싼 용량**인 `minPriceJpy`입니다. 850ml 대용량도 파는 제품이 100ml만 파는 제품보다 "비싼" 것은 아니기 때문입니다. 용량이 몇 개였는지는 `priceVariantCount`가 알려 줍니다.
- **모든 제품에 가격이 있는 것은 아닙니다.** 오픈 가격(「オープン価格」)이나 리필 전용 라인은 엔화 금액 없는 용량만 갖고 있어 `priceJpy: null`로 남고 `priceJpy`에서 제외됩니다. 위 예시에서 `priceJpy.count`(42)가 `productsRanked`(50)보다 작은 이유가 이것입니다. 빈자리를 메우려고 아무것도 지어내지 않습니다.
- **가격은 @cosme가 게시하는 세금 포함 정가**(`priceLabelJa`에 사이트 자체 라벨이 기록됩니다)이며, 매장 가격도 실거래 가격도 아닙니다.
- **순위 등락은 @cosme 자체 아이콘**을 읽습니다: `up`(「10位以上順位アップ」 포함), `stay`, `down`, `new`(ランキング初登場). 인식하지 못한 아이콘은 `stay`에 섞지 않고 `unknown`으로 보고합니다.
- **브랜드명은 브랜드 링크에서만 읽습니다.** 유료 제휴가 있는 브랜드는 안내 문구가 텍스트인 두 번째 링크를 갖는데, 이는 제외되므로 한 브랜드는 `brandTop`에서 항상 한 항목입니다.
- **인코딩**: @cosme는 Shift\_JIS로 서빙하며 코드에서 명시적으로 디코딩합니다. 일본어 브랜드·제품·카테고리명이 온전히 들어옵니다.

#### 이 Actor가 하지 않는 것

- **리뷰 본문은 절대 없습니다.** 위 섹션 참조 — 이것은 제품의 하드 제약이지 기능 부족이 아닙니다.
- **기본값으로는 제품을 한 건씩 쏟아내지 않습니다.** 요약 자체가 결과물이고, 개별 제품은 선택 사항이며 별도 과금입니다.
- **로그인 전용 데이터도, `/api/` 경로도 건드리지 않습니다.** 전부 공개 랭킹 페이지에서 오며 @cosme가 robots.txt에서 막은 경로는 한 번도 요청하지 않습니다.
- **실행 사이에 아무것도 저장하지 않습니다.** 매 실행마다 페이지를 실시간으로 읽습니다.
- **브라우저를 쓰지 않습니다.** 순수 HTTP, 256 MB, 한 번의 실행이 120초 안에 넉넉히 끝납니다.

#### 가격 Pricing — 카테고리당 $0.02

| 과금 이벤트 | 가격 | 언제 |
|---|---|---|
| 카테고리 요약 | **$0.02** | 제품이 나온 카테고리마다. 입력한 카테고리는 모두 과금됩니다 |
| 개별 제품 레코드 | **$0.002** | 「개별 제품 출력」을 켠 경우에만(기본값 꺼짐) |

기본 실행(카테고리 1개, 상위 50개 전체, 요약만)은 **$0.02**입니다. 개별 제품을 켜면 $0.02 + 50 × $0.002 = **$0.12**. 쓴 만큼만 내는 종량 과금이며 정액 요금은 없습니다. **결과가 0건인 카테고리는 과금되지 않습니다.**

#### 주의 Notes & limits

- 요청은 1.5초 간격이고 95초의 소프트 월클록 예산이 있어 여러 카테고리를 돌려도 타임아웃 안에 들어옵니다. 모든 카테고리의 1페이지는 반드시 실행되므로 카테고리마다 요약이 나옵니다. 예산 때문에 후속 페이지가 끊기면 해당 요약에 `truncatedForTimeLimit: true`와 더 작은 `pagesFetched`가 실립니다 — **상위 10개짜리 읽기를 상위 50개인 척 내보내는 일은 없습니다.** **모든** 카테고리가 실패하면 빈 성공을 반환하지 않고 실행 자체가 실패합니다.
- 주식회사 istyle / @cosme와 아무 관련이 없습니다. 시장 조사용 데이터이므로 중요한 결정 전에는 직접 확인하세요.
- 페이지 구조가 바뀌면 그럴듯한 빈 결과를 돌려주는 대신 **명확히 실패**합니다.

#### 활용 Use cases

- **소싱 선별** — 랭킹은 일본에서 실제로 팔리는 것이고, 이 Actor는 그것이 어느 가격대·어느 평점대에서 팔리는지를 알려 줍니다.
- **브랜드 벤치마크** — 자사 제품의 순위·평점·가격을 절대값이 아니라 카테고리 전체의 가격대·평점대 안에서 봅니다.
- **트렌드 모니터링** — 같은 카테고리를 주 단위로 돌리고 `rankMovement`와 집계 기간으로 물갈이 중인지 굳어 있는지 봅니다.

***

### English

#### Overview

Rating, review-count and price figures for any @cosme (cosme.net) ranking category. One row per category covers the **whole top 50**: the typical rating and the middle 50% range on @cosme's 0–7 scale, the same for price (each product's cheapest listed size), review-count median and maximum, brand concentration, rank-movement mix, best-cosme count, and the ranking's own update date and the period it covers. Optionally every ranked product as its own row.

This listing is the **Korean-language package** of our English Actor [@cosme Japan Beauty Ranking — Top 50 Ratings & Prices](https://apify.com/jpmarketdata/cosme-beauty-market-checker). It reads the same pages and works out the same numbers; only the documentation, store copy and input labels are written for Korean beauty buyers, cross-border resellers and brand teams (앳코스메 / 일본 화장품 / J뷰티 랭킹).

**Review text, reviewer names, reviewer profiles and review photos are never collected**, and no record ever contains a `.../review/` URL — see the Korean section above for the full statement and the executable guard that enforces it.

#### Input

| Field | Example | Notes |
|---|---|---|
| `categories` | `["item/1069"]` | `<axis>/<id>`, axis ∈ `item` / `effect` / `skin` / `age` / `pickup` — copy both halves from the URL, the ids are numbered per axis. Common ids: face wash `item/900`, cleanser `item/901`, toner `item/902`, serum `item/1006`, foundation `item/916`, lipstick `item/1015`, sunscreen `item/801`, perfume `item/804`. $0.02 each |
| `pagesPerCategory` | `5` | 10 products per page; the ranking is only 50 deep, so 5 is the whole thing and the maximum |
| `includeIndividualItems` | `false` | Turn on to also get each ranked product as its own row (+$0.002 each) |
| `convertToUsd` | `true` | Adds USD prices at the current exchange rate |

#### Output

One `type: "category_summary"` row per category (`rating`, `priceJpy`, `reviewCount`, `brandTop`, `brandCount`, `topBrandShare`, `rankMovement`, `bestCosmeCount`, `rankingUpdatedOn`, `aggregationPeriod`, USD conversion) — see the JSON example in the Korean section — plus optionally one `product` row per ranked product, whose `url` is always the product page.

#### Pricing

| What you pay for | Price |
|---|---|
| Category summary | **$0.02** |
| Individual product row | **$0.002** each |

Individual products are OFF by default, so a default run is a flat **$0.02** per category. You pay per category; there is no monthly fee. A category that returns nothing is never charged.

#### Notes & limits

- **The rating scale is 0–7, not 0–5.** Every record carries `ratingScale: 7`. To rescale: `rating / 7 * 5`.
- The ranking is 50 deep and all 50 are read, so the median and the middle 50% range describe the whole ranked set, not an estimate of it.
- Open-price products carry `priceJpy: null` and are excluded from `priceJpy`, which is why `priceJpy.count` can be lower than `productsRanked`.
- `minPriceJpy` (the cheapest listed size) is the representative price; every size/price pair is kept on the product record.
- Prices are @cosme's published tax-included list prices, not shop prices and not sold prices.
- Read-only and throttled (1.5 s), Shift\_JIS decoded explicitly, no login, no `/api/` paths, nothing stored between runs. Not affiliated with istyle Inc. / @cosme.

***

### 日本語

#### 概要 Overview

@cosme（アットコスメ）のカテゴリランキングを1コールで統計化します。カテゴリごとに `category_summary` を1件返し、**トップ50全体**の評価（0〜7点）の中央値と中間50%の幅、価格の中央値と中間50%の幅（各製品の最安サイズ基準）、クチコミ**件数**の中央値と最大値、ブランド集中度、順位変動の内訳、ベストコスメ数、そしてランキング自身の更新日と集計期間を含みます。韓国語圏の利用者（앳코스메 / 일본 화장품 / J뷰티 랭킹）向けに韓国語で書き直したパッケージで、英語版は [@cosme Japan Beauty Ranking — Top 50 Ratings & Prices](https://apify.com/jpmarketdata/cosme-beauty-market-checker)（取得・集計処理は同一）。中国語版 `cosme-beauty-market-cn` は同じソースの姉妹パッケージです。

**クチコミ本文・投稿者名・投稿者ページ・クチコミ写真は一切取得しません**（レコードに `.../review/` のURLが入ることもありません）。取得するのはクチコミの**件数**という数値のみです。

#### 入力 Input

`categories`（`<axis>/<id>` 形式、ランキングURL貼付も可）／`pagesPerCategory`（既定 5＝トップ50全体、最大5）／`includeIndividualItems`（既定 OFF）／`convertToUsd`（既定 ON）。

#### 出力 Output

カテゴリごとに `category_summary` を1件（`rating` / `priceJpy` / `reviewCount` / `brandTop` / `brandCount` / `topBrandShare` / `rankMovement` / `bestCosmeCount` / `rankingUpdatedOn` / `aggregationPeriod` / USD換算）。`includeIndividualItems` が ON のときは、ランクインした各製品の明細（順位・変動・ブランド・評価・クチコミ件数・全サイズ/価格・発売日・ベストコスメ・製品URL）も出力します。

#### 料金 Pricing

カテゴリサマリー（`category-analyzed`）**$0.02**／個別製品レコード（`product-scraped`）**$0.002 / 件**。個別明細は**既定 OFF** なので既定実行はカテゴリあたり $0.02 固定です。**0件のカテゴリには課金されません。** 使った分だけの従量課金です。

#### 注意 Notes

**評価は7点満点**（`ratingScale: 7`）です。ランキングは50位までで、その50件すべてを読むので、中央値も中間50%の幅も推定ではありません。オープン価格の製品は `priceJpy: null` として価格統計から除外されるため `priceJpy.count` が `productsRanked` より小さくなることがあります。価格は @cosme 掲載の税込価格（`priceLabelJa`）であり、店頭価格でも実売価格でもありません。集計期間が異なるランキング同士は比較できないため、`rankingUpdatedOn` と `aggregationPeriod` は常に付与します。リクエストは1.5秒間隔、Shift\_JIS を明示デコード、ログイン不要・`/api/` 不使用・実行間の保存なし。株式会社アイスタイル／@cosme とは無関係です。

### 문제가 생기면

- **숫자가 이상하거나 실행이 실패했나요?** **Issues** 탭에 남겨 주세요. 모두 읽고 2 영업일 안에 답합니다(일본 시간).
- **가짜 「빈 결과」는 돌려주지 않습니다.** 사이트를 읽을 수 없으면 실행이 실패하고 그렇게 알려줍니다.
- **결과가 없으면 요금이 없습니다.** 실제로 받은 결과에만 요금이 붙습니다.
- **매주 점검합니다.** 자동 테스트가 매주 돌아가고, 사이트가 바뀌면 고칩니다.
- **공개 페이지만 봅니다.** 로그인하지 않고 개인정보도 다루지 않으며, 사이트에 부담을 주지 않습니다.

### 같은 제작자의 다른 도구

- [북오프 BookOff 일본 중고책·만화·CD·게임 시세 — 중고가·재고](https://apify.com/jpmarketdata/bookoff-market-kr)
- [만다라케 Mandarake 일본 중고 피규어·만화 시세 — 판매가·품절가](https://apify.com/jpmarketdata/mandarake-market-kr)
- [유유테이 Yuyu-tei 일본 카드 싱글 시세 — 판매가·매입가](https://apify.com/jpmarketdata/yuyutei-tcg-price-kr)
- [BookOff Japan Used Manga, Books, CDs — Price & Stock](https://apify.com/jpmarketdata/bookoff-market-checker)
- [Digimart Japan Used Guitar & Instrument Prices](https://apify.com/jpmarketdata/digimart-instrument-market-checker)
- [Fujiya Camera Japan Used Camera Prices by Condition](https://apify.com/jpmarketdata/fujiya-camera-market-checker)
- [HobbyLink Japan Gunpla & Figure Prices + Stock Status](https://apify.com/jpmarketdata/hlj-hobby-market-checker)
- [Iosys Japan Used iPhone & Phone Prices by Condition](https://apify.com/jpmarketdata/iosys-phone-market-checker)

이 도구의 다른 언어판: [English](https://apify.com/jpmarketdata/cosme-beauty-market-checker) · [中文](https://apify.com/jpmarketdata/cosme-beauty-market-cn)

모든 도구(일본 마켓플레이스, 부동산, 채용, 경정·경륜·경마, 예측시장): <https://apify.com/jpmarketdata>

### 면책 조항

비공식 독립 도구입니다 — **@cosme와 제휴·보증·후원 관계가 없습니다**. 상품명과 로고는 각 소유자의 것이며 여기서는 데이터 출처를 나타낼 뿐입니다. 공개 페이지에서 읽은 데이터이며 시장 조사용입니다. 행동하기 전에 직접 확인하세요.

# Actor input Schema

## `categories` (type: `array`):

하나 이상의 @cosme 랭킹 카테고리를 '<axis>/<id>' 형식으로 적습니다. 예: 'item/1069'(리퀴드 클렌징). axis는 item, effect, skin, age, pickup 중 하나이며, id 는 axis 마다 따로 매겨지므로 두 조각을 URL 에서 함께 옮겨 오세요('effect/1069' 는 다른 랭킹입니다). 랭킹 URL 전체를 붙여 넣어도 정규화됩니다. 자주 쓰는 id: item/900 클렌징 폼, item/901 메이크업 리무버, item/902 스킨, item/1006 세럼, item/916 파운데이션, item/1015 립스틱, item/801 자외선 차단. 메인 랭킹만 읽으며 ranking-rise 등 변형은 오류로 알려 줍니다. 읽을 수 없는 카테고리는 건너뛰고 나머지는 실행됩니다. 카테고리당 $0.02.

## `pagesPerCategory` (type: `integer`):

랭킹을 얼마나 깊게 읽을지 정합니다. @cosme는 페이지당 10개를 싣고 랭킹은 5페이지에서 끝나므로, 기본값 5가 상위 50개 전체이며 그 뒤는 존재하지 않습니다. 상위 10개만 빠르게 보려면 1로 낮추세요.

## `includeIndividualItems` (type: `boolean`):

기본은 꺼짐: 한 번 실행하면 카테고리 요약 하나당 $0.02 고정입니다. 켜면 랭킹에 오른 제품마다 레코드를 하나씩 더 출력합니다(순위, 순위 등락, 브랜드, 0~7점 평점, 리뷰 수, 모든 용량·가격 쌍, 출시일, 베스트코스메 여부, 제품 URL). 건당 +$0.002. 리뷰 본문, 작성자 이름, 리뷰 사진은 절대 포함되지 않습니다 — README를 보세요.

## `convertToUsd` (type: `boolean`):

현재 환율(open.er-api.com)로 엔화 통계 옆에 달러 통계를 함께 붙입니다.

## Actor input object example

```json
{
  "categories": [
    "item/1069"
  ],
  "pagesPerCategory": 5,
  "includeIndividualItems": false,
  "convertToUsd": 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 = {
    "categories": [
        "item/1069"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("jpmarketdata/cosme-beauty-market-kr").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 = { "categories": ["item/1069"] }

# Run the Actor and wait for it to finish
run = client.actor("jpmarketdata/cosme-beauty-market-kr").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 '{
  "categories": [
    "item/1069"
  ]
}' |
apify call jpmarketdata/cosme-beauty-market-kr --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jpmarketdata/cosme-beauty-market-kr"
        }
    }
}

```

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/oHVo9QzD6ehHZxHax/builds/WDTJk2ZjEJ4E0D9Rb/openapi.json