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

일본 최대 뷰티 리뷰 사이트 @cosme(앳코스메)의 카테고리 하나를 고르면 그 랭킹 Top 50 전체를 한 번에 요약해 줍니다. 평점 대표값과 범위(0~7점), 가격 대표값과 범위, 리뷰 수 중앙값과 최대값, 브랜드 수, 순위 상승/하락/신규 개수, 랭킹 갱신일을 돌려줍니다. 카테고리당 $0.02. @cosme Japan top-50 ranking ratings and prices per category. 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, 100.0% 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/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

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

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

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

**결과:** 평점 대표값과 범위(0~7점); 가격 대표값과 범위; 리뷰 수 중앙값과 최대값; 브랜드 수; 순위 상승 / 하락 / 신규 개수; 랭킹 갱신일. 선택: 제품 1개당 1행. 리뷰 본문은 절대 수집하지 않음.

**가격:** 카테고리당 $0.02, 목록까지 원하면 제품당 +$0.002. 결과 없음 = 과금 없음.

**예시:** `item/1069` 입력 → 제품 50개 · 평점 대표값 5.1(범위 3.7–6.9) · 가격 대표값 ¥1,760(범위 ¥352–7,260) · 브랜드 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 price and range, review-count median and max, number of brands, rank movement counts and the ranking date.

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

### 한국어

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

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

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

- **`rating` — 최저 / Q1 / 중앙값 / Q3 / 최고 (@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 Rankings — Rating, Review-Count & Price Stats**(같은 계정의 영어 입구)의 **한국어 언어 패키지**입니다. 수집 로직과 통계 기준은 완전히 동일하고, 제목·스토어 설명·문서·입력 라벨만 한국어로 다시 썼습니다.

#### ⚠️ 이 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건**을 반환합니다: 평점 사분위, 가격 사분위, 리뷰 수 중앙값·최대값, 브랜드 집중도, 순위 등락 구성, 베스트코스메 수, 랭킹 갱신일과 집계 기간, 환율. 개별 제품 출력을 켜면 랭킹에 오른 제품마다 레코드를 하나씩 더 반환합니다.

#### 입력 Input

| 필드 | 예시 | 설명 |
|---|---|---|
| `categories` | `["item/1069"]` | `<axis>/<id>`, axis ∈ `item` / `effect` / `skin` / `age` / `pickup`. 랭킹 URL 전체를 붙여 넣어도 정규화됩니다. 카테고리당 $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의 다른 랭킹 축으로 사용법은 같습니다.

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

#### 출력 Output

필드명은 영어 그대로 둡니다. API 표면이기 때문입니다. 아래는 `item/1069`(リキッドクレンジング / 리퀴드 클렌징)의 2026-08-01 실측입니다:

```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
}
```

선택 출력인 제품 레코드(`type: "product"`) — `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위까지이고, 그것이 표본이 아니라 모집단 전체입니다.** `productsRanked`는 보통 정확히 50(페이지당 10 × 5페이지)이므로 사분위는 추정값이 아니라 랭킹 집합의 실제 사분위입니다. 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부터, 구독 없음

| 과금 이벤트 | 가격 | 언제 |
|---|---|---|
| 카테고리 랭킹 요약 (`category-analyzed`) | **$0.02** | 제품이 나온 카테고리마다 |
| 개별 제품 레코드 (`product-scraped`) | **$0.002** | 「개별 제품 출력」을 켠 경우에만 |

기본 실행(카테고리 1개, 상위 50개 전체, 요약만)은 **$0.02**입니다. 개별 제품을 켜면 $0.02 + 50 × $0.002 = **$0.12**.

#### 주의 Notes & limits

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

#### 활용 Use cases

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

***

### English

#### Overview

Rating, review-count and price statistics for any @cosme (cosme.net) ranking category. One call returns the **whole top 50** as a single `category_summary` record: rating quartiles on @cosme's 0–7 scale, price quartiles over 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 aggregation window. Optionally every ranked product as its own record.

This listing is the **Korean-language package** of our English Actor **@cosme Japan Beauty Rankings — Rating, Review-Count & Price Stats**. The scraping and the statistics are identical; 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`. A full ranking URL is accepted and normalized. $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` | Enable to also get each ranked product as a record (+$0.002 each) |
| `convertToUsd` | `true` | Adds USD price stats at the current exchange rate |

#### Output

One `type: "category_summary"` record 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` record per ranked product, whose `url` is always the product page.

#### Pricing

| Event | Price |
|---|---|
| Category ranking summary (`category-analyzed`) | **$0.02** |
| Individual product record (`product-scraped`) | **$0.002** each |

Individual products are OFF by default, so a default run is a flat **$0.02** per category. A category that returns nothing is never charged. No subscription.

#### 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 that is the whole population, so the quartiles are true quartiles, not estimates.
- 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点）四分位、価格四分位（各製品の最安サイズ基準）、クチコミ**件数**の中央値と最大値、ブランド集中度、順位変動の内訳、ベストコスメ数、そしてランキング自身の更新日と集計期間を含みます。韓国語圏の利用者（앳코스메 / 일본 화장품 / J뷰티 랭킹）向けに韓国語で書き直したパッケージで、英語版は **@cosme Japan Beauty Rankings — Rating, Review-Count & Price Stats**（取得・統計処理は同一）。中国語版 `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位までで、それが母集団そのものなので四分位は推定ではありません。オープン価格の製品は `priceJpy: null` として価格統計から除外されるため `priceJpy.count` が `productsRanked` より小さくなることがあります。価格は @cosme 掲載の税込価格（`priceLabelJa`）であり、店頭価格でも実売価格でもありません。集計期間が異なるランキング同士は比較できないため、`rankingUpdatedOn` と `aggregationPeriod` は常に付与します。リクエストは1.5秒間隔、Shift\_JIS を明示デコード、ログイン不要・`/api/` 不使用・実行間の保存なし。株式会社アイスタイル／@cosme とは無関係です。

### If something goes wrong

- **Wrong number or a failed run?** Open a ticket on the **Issues** tab. I read every one and reply within 2 business days (Japan time).
- **You never get a fake "empty" result.** If the site can't be read, the run fails and says so.
- **No results = no charge.** You only pay for results you actually get.
- **Checked every week.** An automatic test runs this tool weekly; if the site changes, I fix it.
- **Public pages only.** No login, no personal data, and it goes easy on the site.

### More tools by the same author

- [북오프 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)

Other language editions of this tool: [English](https://apify.com/jpmarketdata/cosme-beauty-market-checker) · [中文](https://apify.com/jpmarketdata/cosme-beauty-market-cn)

All tools (Japan marketplaces, real estate, jobs, racing, prediction markets): <https://apify.com/jpmarketdata>

### Disclaimer

Unofficial, independent tool — **not affiliated with, endorsed by, or sponsored by @cosme**. Product names and logos belong to their owners and only say where the data comes from. Data is read from public pages, for market research; check before you act on it.

# Actor input Schema

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

하나 이상의 @cosme 랭킹 카테고리를 '<axis>/<id>' 형식으로 적습니다. 예: 'item/1069'(リキッドクレンジング / 리퀴드 클렌징). axis는 item, effect, skin, age, pickup 중 하나입니다. 랭킹 URL 전체(https://www.cosme.net/categories/item/1069/ranking/)를 붙여 넣어도 자동으로 정규화됩니다. 읽는 것은 메인 랭킹뿐이며 ranking-rise / ranking-age / ranking-skin / ranking-search는 결과 집합 자체가 다르므로 조용히 바꿔치기하지 않고 오류로 알려 줍니다. 카테고리당 $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/mZgaOOlxaHUdCxNtq/openapi.json