[中文]

用途:

• 复刻蒲公英「学内容 → 创意灵感 → 内容广场」：不需要任何 ID，直接查「现在什么内容在火」
• 与其它接口方向相反 —— 其余接口都要先有博主/笔记 ID，本接口是入口式的， 拿到榜单后可以顺着笔记里的博主 ID 再去调博主侧接口深挖

1. 全部参数一览

不传的筛选就是「不限」。不要把不需要的字段传成空字符串或 0 —— 那会被当成一次真实筛选。

2. 翻页

翻页只改 page_num，其余参数必须原样保持不变。

每个榜单固定只有 100 条（返回的 total 恒为 100）—— 这是榜单不是全量搜索， 上游只放出 Top 100。所以 page_size=34 时翻到第 3 页就到底了，第 4 页返回空数组。 要更多内容请换榜单、换筛选或换 date_range，调大 page_size 没用（上限 34）。

响应里的 pageInfoDto.totalPage 实测恒为 0，不要拿它判断还有没有下一页。

3. 榜单（biz_type）

4. 各榜支持的筛选不同

榜单决定了可用的筛选项 —— 传了该榜不支持的字段会返回 422 并告诉你这个榜支持哪些， 不会被静默忽略（否则你会拿到一份没按预期过滤的数据却发现不了）。

行业怎么填（不同榜是不同的分类体系，别混用）：

5. 排序（order_by）

留空即用该榜的网页默认排序（榜 2 和 3 默认阅读率，其余默认曝光量）。

通用（所有榜可用）：

仅 3 电商推广 / 6 电商热门 额外支持：premium_ecm_dgmv（笔记支付金额）、 premium_ecm_order_pv（笔记支付订单数）、premium_ecm_order_rate（笔记支付转化率）。

仅 4 蒲公英合作 额外支持（小红星=淘宝、小红盟=京东、小红链=唯品会）： taobao_third_active_pgy_user_ratio / taobao_third_active_pgy_user_cost / jd_third_active_pgy_user_ratio / jd_third_active_pgy_user_cost / wph_third_active_pgy_user_ratio / wph_third_active_pgy_user_cost。

传了本榜不支持的排序同样返回 422。

6. 其它枚举一览

price（创作者报价，仅榜 4）要同时给口径和区间，因为图文和视频是两套独立报价： {"kind": 1, "range": {"min": 10000, "max": 50000}}，kind 取 1 图文笔记 / 2 视频笔记。 fans（创作者粉丝，仅榜 4）只要区间：{"min": 100000, "max": 500000}。

7. 返回

• noteList[]: 命中的笔记。每条含 noteInfo（title 标题、noteType 类型、 noteLink 笔记链接、noteImages 封面、readNum 阅读、likeNum 点赞、favNum 收藏、 cmtNum 评论、videoDuration 视频时长、notePublishTime 发布时间）与博主信息
• total: 该榜的条数，恒为 100
• pageInfoDto: 上游分页回执，其中 totalPage 恒为 0，不可用

8. 注意:

• 字段名写错、枚举值不合法、榜单与筛选不匹配都会 422
• 关键词支持英文逗号分隔批量搜（与网页搜索框一致）

响应结构（取数要剥两层）:

• resp["data"] 是蒲公英原样信封（含 code/msg/success），业务数据还在它里面一层
• 正确取法：data = resp["data"]["data"]；下面「返回」列的字段都在这一层下

计费:

• HTTP 200 → 计费。包含「查无结果」（data 为 null，如 ID 不存在或筛选无命中）—— 请求已送达蒲公英，同样扣费，不要因为拿不到数据就重试
• HTTP 400 → 不计费（参数格式非法，或上游资源不足/异常）

[English]

Purpose:

• Replica of PGY "Learn Content → Inspiration → Content Square": no ID required, directly answers "what content is hot right now"
• Opposite direction from every other endpoint — this one is an entry point; take the blogger IDs from the returned notes and drill down with the blogger endpoints

1. Full Parameter List

Omitted filters mean "no limit". Do not send unused fields as empty strings or 0 — they would be treated as a real filter.

2. Paging

Change page_num only and keep every other parameter identical.

Each board holds exactly 100 items (total is always 100) — this is a leaderboard, not a full search; upstream only exposes the Top 100. With page_size=34 you reach the end at page 3, and page 4 returns an empty array. For more content switch boards, filters or date_range — raising page_size does not help (capped at 34).

pageInfoDto.totalPage is always 0 in practice — do not use it to detect more pages.

3. Leaderboards (biz_type)

4. Filters Differ per Board

The board determines which filters are available — sending an unsupported field returns 422 listing what the board does support, instead of being silently ignored (otherwise you would receive unfiltered data without noticing).

How to fill industry (different boards use different taxonomies — do not mix them):

5. Sorting (order_by)

Leave empty to use the board default (boards 2 and 3 default to read rate, others to impressions).

Common to all boards:

Boards 3 / 6 additionally support premium_ecm_dgmv (paid GMV), premium_ecm_order_pv (paid orders), premium_ecm_order_rate (paid conversion rate).

Board 4 additionally supports off-site metrics (小红星=Taobao, 小红盟=JD, 小红链=VIP): taobao_third_active_pgy_user_ratio / _cost, jd_third_active_pgy_user_ratio / _cost, wph_third_active_pgy_user_ratio / _cost.

Sending a sort value the board does not support also returns 422.

6. Other Enums

price (board 4) needs both the quote type and the range, because image-text and video are two independent quotes: {"kind": 1, "range": {"min": 10000, "max": 50000}} where kind is 1 image-text / 2 video. fans (board 4) takes a plain range.

7. Return

• noteList[]: matched notes; each has noteInfo (title, noteType, noteLink, noteImages, readNum, likeNum, favNum, cmtNum, videoDuration, notePublishTime) plus blogger info
• total: always 100 (board capacity)
• pageInfoDto: upstream paging echo; its totalPage is always 0 and unusable

8. Notes:

• Misspelled fields, invalid enums, and board/filter mismatches all return 422
• Keyword supports comma-separated batch search (same as the web search box)

Response shape (two layers):

• resp["data"] is PGY's raw envelope (with code/msg/success); the payload is one level deeper
• Correct access: data = resp["data"]["data"] — every field listed under "Return" lives here

Billing:

• HTTP 200 → charged, including "no result" (data is null, e.g. ID not found or filters matched nothing): the request did reach PGY, so retrying on empty data just burns quota
• HTTP 400 → not charged (malformed params, or upstream unavailable/error)

[示例/Example]

// ① 近 7 日全平台最热的美妆视频（榜 1 用 category，不是 industry）
{"biz_type": 1, "category": "内容类目#美妆", "note_type": 2}

// ② 母婴行业近 30 日互动率最高的蒲公英合作笔记，博主图文报价 1~5 万
{"biz_type": 4, "industry": "母婴", "date_range": 30,
 "order_by": "premium_engage_rate",
 "price": {"kind": 1, "range": {"min": 10000, "max": 50000}}}

// ③ 电商推广榜按笔记支付金额排序，只看搜索场域
{"biz_type": 3, "order_by": "premium_ecm_dgmv", "placement": 2}

// ④ 带关键词看榜
{"biz_type": 1, "search_word": "面膜"}

// ⑤ 批量关键词（英文逗号分隔）+ 只看博主合作笔记
{"biz_type": 1, "search_word": "面膜,精华", "content_type": 1}

// ⑥ 翻页：只改 page_num，其余参数原样不动（改了口径两页会重复/遗漏）；每榜只有 100 条，34/页翻到第 3 页到底
{"biz_type": 1, "page_num": 1, "page_size": 34, "category": "内容类目#美妆"}
{"biz_type": 1, "page_num": 2, "page_size": 34, "category": "内容类目#美妆"}

// ⑦ 蒲公英合作榜（仅榜 4 支持站外指标）：按小红星站外转化率排，限蒲公英博主、10~50 万粉的视频
{"biz_type": 4, "order_by": "taobao_third_active_pgy_user_ratio", "author_type": 1,
 "note_type": 2, "fans": {"min": 100000, "max": 500000}}

// ⑧ 产品种草榜近 3 日：美妆个护行业、测评题材、发现页场域的图文（留空 order_by = 用该榜默认排序）
{"biz_type": 2, "industry": "美妆个护", "theme": "测评类", "placement": 1,
 "note_type": 1, "date_range": 3}

// ⑨ 电商推广榜只看直播推广（marketing_target 仅榜 3 可用），按支付订单数排
{"biz_type": 3, "marketing_target": 8, "order_by": "premium_ecm_order_pv", "note_type": 2}

// ⑩ 电商热门榜近 14 日：industry 这里是电商商品类目（与榜 2/4/5/7/8 的行业名不是一套），看买手笔记的支付转化率
{"biz_type": 6, "industry": "厨房电器", "order_by": "premium_ecm_order_rate",
 "content_type": 5, "date_range": 14}

// ⑪ 应用推广榜（sub_biz_type 仅榜 8 可用）：应用下载口径、互联网行业、发现页的知识科普题材
{"biz_type": 8, "sub_biz_type": 1, "industry": "互联网", "placement": 1, "theme": "知识科普"}

// 取数：notes = resp["data"]["data"]["noteList"]

{
  "biz_type": 1,
  "page_num": 1,
  "page_size": 34,
  "search_word": "面膜",
  "order_by": "premium_imp_num",
  "date_range": 7,
  "sub_biz_type": 3,
  "category": "内容类目#美妆",
  "industry": "母婴",
  "note_type": 2,
  "content_type": 1,
  "theme": "开箱",
  "author_type": 1,
  "placement": 1,
  "marketing_target": 3
}