# 日本化妆品排行榜 @cosme Top 50 评分与价格 (`jpmarketdata/cosme-beauty-market-cn`) 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-cn.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`（卸妆液），或直接粘贴排行页网址。

**你得到：** 评分典型值与区间（0–7 分制）；价格典型值与区间；点评数中位数与最大值；品牌数；上升 / 下降 / 新上榜的产品数；排行更新日。可选：每个产品一行。绝不采集点评正文。

**价格：** 每个分类 $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）

**日本化妆品是日本对中国最大的消费品类之一**——从美妆代购、跨境电商选品到国内品牌做竞品对标，链路上每个人都在问同一个问题：现在日本人到底在买什么、买在什么价位、口碑落在哪一档。而这个问题在中文圈里有一个默认答案：**看 @cosme（アットコスメ）的排行**。它是日本占绝对主导地位的美妆点评平台，它的分类排行榜就是中文买家引用的那把尺子，但它没有公开 API。

这个 Actor 把一张排行榜变成一条可以直接进选品表的行情记录：

- **`rating` —— 评分的最低 / Q1 / 中位 / Q3 / 最高（@cosme 的 0–7 分制）**，看清一个品类是清一色 5.1 分的混战，还是头部真的拉开了质量差距。
- **`priceJpy` —— 同样的四分位，按每款产品最便宜的那个规格算**，并附美元换算。这个品类现在赢在哪个价位段？
- **`reviewCount` —— 点评数的中位数与最大值**。一款 2002 年的常青款 8,727 条点评，和一款 2026 年新品 17 条点评，排名只差三位——这个差别只有点评数能说出来。
- **`brandTop` / `brandCount` / `topBrandShare`** —— 品牌集中度：这个品类是被一家吃掉，还是 42 个品牌在混战。
- **`rankMovement`** —— 上榜产品里有多少在上升、持平、下滑或是新入榜。构成比告诉你这个品类是在换血还是已经固化。
- **`bestCosmeCount`**（ベストコスメ 获奖数）、**`variantsPerProductMedian`**，以及排行榜自身的 **`rankingUpdatedOn`**（更新日）与 **`aggregationPeriod`**（统计区间）。
- 可选：每一款上榜产品（名次、名次升降、品牌、评分、点评数、**全部规格与价格**、发售日、最佳美妆标记、产品链接）。

无需登录、无需 API key、运行之间不存储任何数据。

本 Actor 是英文版 **@cosme Japan Beauty Rankings — Rating, Review-Count & Price Stats**（同一账号下的英文入口）的**中文语言包**：抓取逻辑与统计口径完全相同，只有标题、商店说明、文档和输入项标签改写成中文。

#### ⚠️ 本 Actor 刻意**不采集**的东西

@cosme 是点评站，所以这一点必须说明白：

> **点评正文、点评者昵称、点评者主页与点评图片——绝不采集，这是设计决定，且永久有效。**

| 不采集 | 为什么 |
|---|---|
| 点评正文（用户写的文字） | 那是用户创作的个人内容。做统计不需要它 |
| 点评者昵称、年龄、肤质、个人主页 | 那是与本产品无关的个人的个人数据 |
| 点评图片 | 同上——用户上传的个人内容 |
| 点评永久链接与产品页的 `/review/` 标签页链接 | 给出链接就等于给出指针。**任何一条记录里都不会出现 `.../review/` 链接**——`url` 永远是产品页 |

**真正被采集的是点评的「条数」——一个数字**，以及聚合后的评分值。这就是本 Actor 在点评侧的全部足迹。

这不是一句文案上的承诺，而是写进代码里的：`src/main.py` 带有 `DELIBERATE EXCLUSION` 段落和一个可执行的守卫函数 `review_text_leaks(record)`，它会扫描每条输出记录的所有值，找出点评标记（`review-body`、`review-text`、`reviewer-desc`、`/reviewer/`、`/review/`、`/reviews/`）。**测试套件断言它对每一种输出记录形状都返回 `[]`。** 将来若有人改动导致整块产品 HTML 被剥标签复制、或把点评标签页链接带了进来，标记会一起进来，构建随即失败。

#### 概览 Overview

每个分类返回**一条 `category_summary` 汇总记录**：评分四分位、价格四分位、点评数中位数与最大值、品牌集中度、名次升降构成、最佳美妆获奖数、排行更新日与统计区间、汇率。开启单品输出后，另外为每一款上榜产品返回一条记录。

#### 输入 Input

| 字段 | 示例 | 说明 |
|---|---|---|
| `categories` | `["item/1069"]` | `<axis>/<id>`，axis ∈ `item` / `effect` / `skin` / `age` / `pickup`。粘贴完整排行链接也会被自动规范化。每个分类 $0.02 |
| `pagesPerCategory` | `5` | 每页 10 款；**排行只到第 50 名**，所以 5 就是全部，也是上限。只看 Top 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`（お好み）链接，运行会明确报错，而不是悄悄按主排行给你计费——那是统计区间与结果集都不同的另一张榜。

#### 输出 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–7 分制，不是 0–5 分制。** @cosme 用七分制，所以 5.4 分是一款很强的产品，而不是一个不可能的数字。每条记录都带 `ratingScale: 7`，就是为了防止你不小心拿它去和别的站的五星评分直接比。（换算成五分制：`rating / 7 * 5`。）
- **统计区间是答案的一部分。** @cosme 用大约 3 个月的滚动窗口重算每张榜，并把两个日期写在页头；它们以 `rankingUpdatedOn` 和 `aggregationPeriod` 出现在每条记录上。两张榜只有窗口可比时才可比——没有窗口的快照是无法解释的，所以这两项绝不省略。
- **排行只有 50 名深，这就是全部总体，不是样本。** `productsRanked` 正常情况下恰好是 50（每页 10 × 5 页），所以四分位是上榜集合的真实四分位，而不是估计值。没有第 6 页。
- **一款产品，多个价格。** 日本化妆品常常在同一行里列出多个规格（「税込価格：100ml・1,463円 / 250ml・3,069円 / 500ml・3,810円」）。全部规格都会被解析；`minPriceJpy`——**最便宜的那个规格**——是进入 `priceJpy` 的代表价，因为一款同时卖 850ml 大瓶的产品并不比只卖 100ml 的「更贵」。`priceVariantCount` 告诉你一共有几个规格。
- **不是每款都有价格。** 开放价格（「オープン価格」）与仅有替换装的产品会带一个没有日元金额的规格；它们保持 `priceJpy: null` 并被排除在 `priceJpy` 之外——这就是为什么上例中 `priceJpy.count`（42）小于 `productsRanked`（50）。缺口不会被任何编造的数字填上。
- **价格是 @cosme 公布的含税建议零售价**（`priceLabelJa` 记录站方自己的标签），不是店铺售价，更不是成交价。
- **名次升降取自 @cosme 自己的图标**：`up`（含「10位以上順位アップ」）、`stay`、`down`、`new`（ランキング初登場）。不认识的图标报为 `unknown`，绝不并进 `stay`。
- **品牌名只从品牌链接读取。** 有付费合作的品牌会多出一个链接，其文字是广告告知；该链接被排除，所以一个品牌在 `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 个分类、完整 Top 50、只要汇总）花费 **$0.02**。开启单品输出后是 $0.02 + 50 × $0.002 = **$0.12**。\*\*零结果的分类绝不收费。

#### 注意事项 Notes & limits

- 请求限速 1.5 秒，并有 95 秒的软性总时长预算，保证多分类运行不超时。每个分类的第 1 页一定会跑，所以每个分类都会产出汇总；如果预算截断了后续页，受影响的汇总会带 `truncatedForTimeLimit: true` 和更小的 `pagesFetched`——**Top 10 绝不会被当成完整 Top 50 端出来**。若**所有**分类都失败，运行会明确失败，而不是返回一个空的「成功」。
- 与株式会社アイスタイル / @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 **Chinese-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 Chinese-speaking beauty buyers, cross-border resellers and brand teams (日本化妆品 / 日妆排行 / 日本美妆代购).

**Review text, reviewer names, reviewer profiles and review photos are never collected**, and no record ever contains a `.../review/` URL — see the Chinese 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 Chinese 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点）四分位、価格四分位（各製品の最安サイズ基準）、クチコミ**件数**の中央値と最大値、ブランド集中度、順位変動の内訳、ベストコスメ数、そしてランキング自身の更新日と集計期間を含みます。中国語圏の利用者（日本化妆品 / 日妆排行 / 日本美妆代购）向けに中国語で書き直したパッケージで、英語版は **@cosme Japan Beauty Rankings — Rating, Review-Count & Price Stats**（取得・統計処理は同一）。

**クチコミ本文・投稿者名・投稿者ページ・クチコミ写真は一切取得しません**（レコードに `.../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-cn)
- [日本二手乐器 Digimart 吉他·乐器价格 — 二手价与成色](https://apify.com/jpmarketdata/digimart-instrument-market-cn)
- [藤屋相机 Fujiya Camera 日本二手相机·镜头价格 — 按成色分级](https://apify.com/jpmarketdata/fujiya-camera-market-cn)
- [日本高达模型·手办 HobbyLink Japan 价格 — 现货还是预订](https://apify.com/jpmarketdata/hlj-hobby-market-cn)
- [日本二手手机店 Iosys 二手 iPhone·手机价格 — 按成色分级](https://apify.com/jpmarketdata/iosys-phone-market-cn)
- [万代书店 Mandarake 日本二手手办·漫画价格 — 在售价与售罄价](https://apify.com/jpmarketdata/mandarake-market-cn)
- [游游亭 Yuyu-tei 日本卡牌单卡价格 — 售价与回收价](https://apify.com/jpmarketdata/yuyutei-tcg-price-cn)
- [BookOff Japan Used Manga, Books, CDs — Price & Stock](https://apify.com/jpmarketdata/bookoff-market-checker)

Other language editions of this tool: [English](https://apify.com/jpmarketdata/cosme-beauty-market-checker) · [한국어](https://apify.com/jpmarketdata/cosme-beauty-market-kr)

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 之一。也可以直接粘贴完整排行链接（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（默认值）就是完整的 Top 50，再往后没有了。只想快速看 Top 10 就设成 1。

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

默认关闭：一次运行每个分类汇总固定 $0.02。开启后还会为每一款上榜产品输出一条记录（名次、名次升降、品牌、0–7 分评分、点评数、全部规格与价格、发售日、最佳美妆标记、产品链接），+$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-cn").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-cn").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-cn --silent --output-dataset

```

## MCP server setup

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

```

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/iZe1saXCbkfg1hUdT/builds/LHD5nz1SEuw4SJdqZ/openapi.json