[中文]

用途:

复刻蒲公英网页「找博主 → 笔记博主广场」的搜索与筛选，约 60 个筛选条件按 7 组传入

每条结果内嵌约 140 个字段（报价、阅读/互动中位数、直播场次等），通常不必再逐个调博主详情类接口

1. 搜索与排序

参数	说明
`keyword`	搜索词；空=只筛选不搜索
`search_type`	`1`=按笔记关键词找博主（默认）`0`=按昵称搜
`column`	排序字段：`comprehensiverank` 综合（默认）/ `fansCount` 粉丝数 / `clickNum` 阅读 / `mEngagementNum` 互动 / `price` 报价
`sort`	`desc` 降序（默认）/ `asc` 升序
`brand_user_id`	品牌方/广告主用户ID，可不填。带上后按该品牌做个性化推荐与已合作标记

2. 筛选分组

筛选按维度分成 7 组，每组是一个对象：

分组	覆盖的筛选
`goal`	营销目标（曝光 / 种草 / 转化 × 指标 × 成本或规模）
`blogger`	博主类目、人设、擅长内容、内容题材、二十大人群、行业特色画像、预估消费行为、笔记类目、性别、地域、签约情况
`fans`	粉丝量、粉丝年龄、粉丝性别、粉丝地域、婚恋状态、消费水平、母婴阶段、手机价格、手机品牌
`note`	日常笔记的曝光/阅读/互动中位数、千赞笔记比例、笔记类型
`coop`	合作报价、合作订单数、合作信用度、近期合作行业与品牌、传播规模、预估 CPM / 阅读单价 / 互动单价、外溢进店单价
`live`	近 30 天直播场次、场均观播人数、场均销售额
`flags`	明星、优质博主、新锐博主、笔记+直播均可合作、意向行业匹配、行业推荐博主、热门活动、剔除低活/掉粉/已合作/已邀约

数值区间统一写成 {"min": 10000, "max": 50000}。两端都可省略：省略 min 视为 0，
省略 max 视为不限；但两端全空会 422。

3. 区间型字段（值写成 `{"min": x, "max": y}`）

参数路径	对应网页筛选
`fans.count`	粉丝量
`note.imp_median` / `note.read_median` / `note.inter_median`	日常笔记的曝光 / 阅读 / 互动中位数
`note.thousand_like_percent`	千赞笔记比例（单位 %）
`coop.pic_price` / `coop.video_price`	合作报价（图文 / 视频一口价，元）
`coop.order_count`	合作订单数
`coop.reply_48h_ratio`	合作信用度 → 48h 邀约回复率（%）
`coop.imp_median` / `coop.read_median` / `coop.inter_median`	传播规模（合作笔记的中位数）
`coop.cpuv` / `coop.estimate_cpuv`	CPUV / 外溢进店单价
`coop.pic_cpm` / `coop.video_cpm`	预估 CPM（图文 / 视频）
`coop.pic_read_price` / `coop.video_read_price`	预估阅读单价（图文 / 视频）
`coop.pic_engage_cost` / `coop.video_engage_cost`	预估互动单价（图文 / 视频）
`live.live_count` / `live.avg_viewer` / `live.avg_gmv`	近 30 天直播场次 / 场均观播 / 场均销售额

4. 开关型字段（值写 `true`）

参数路径	对应网页筛选
`flags.is_star` / `flags.high_quality` / `flags.new_high_quality`	明星 / 优质博主 / 新锐博主
`flags.note_and_live`	笔记 + 直播均可合作
`flags.filter_intention`	意向行业匹配
`flags.exclude_low_active` / `flags.exclude_fans_down`	剔除低活 / 掉粉博主
`flags.exclude_cooperated` / `flags.exclude_invited`	剔除已合作 / 已邀约博主
`coop.exclude_brands`	配合 `coop.brand_ids`：`true` = 排除与这些品牌合作过的博主

此外 flags.industry_first / flags.industry_second 是行业推荐博主的一级/二级行业名，
flags.activity_codes 是热门活动 code（取自 /get_blogger_filter_options 的 activities）。
枚举型字段（性别、签约情况、粉丝年龄等）的完整取值见各字段在 Swagger 中的说明。

5. 翻页

参数	取值	说明
`page_num`	1-250	上游只放出前 5000 条 = 250 页，第 251 页起返回空数组
`page_size`	1-20	蒲公英网页固定 20。建议保持 20：上游会对当页结果做二次过滤（下架、不可合作等），取太小可能整页被过滤成 0 条

翻页只改 page_num，其余筛选必须原样保持不变，否则两页口径不一致会重复或遗漏。
total 不是命中总数，是可翻上限，恒为 5000。想缩小结果集请加筛选，而不是指望翻到底。

6. 返回

kols[]: 命中的博主，每条约 140 个字段

身份: userId / name / redId / headPhoto / location / gender

标签: contentTags / featureTags / personalTags / tradeType

数据: fansNum / clickMidNum 阅读中位数 / interMidNum 互动中位数 / fans30GrowthRate 粉丝增速 / kliveCnt30d 直播场次

商业: picturePrice / videoPrice / lowerPrice / estimatePictureCpm / cooperateState

total: 可翻上限（恒 5000）

trackId / highlightWords

7. 注意:

字段名写错会直接 422，不会被静默忽略

树形筛选的可选值请用 /get_blogger_filter_options 实时拉取，不要写死

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

resp["data"] 是蒲公英原样信封（含 code/msg/success），业务数据还在它里面一层

正确取法：data = resp["data"]["data"]；下面「返回」列的字段都在这一层下

计费:

HTTP 200 → 计费。包含「查无结果」（data 为 null，如 ID 不存在或筛选无命中）——
请求已送达蒲公英，同样扣费，不要因为拿不到数据就重试

HTTP 400 → 不计费（参数格式非法，或上游资源不足/异常）

[English]

Purpose:

Full replica of PGY "Find Bloggers → Note Blogger Square"; ~60 filters grouped into 7 objects

Each result embeds ~140 fields (quotes, read/engagement medians, live sessions, ...)

1. Search & Sort

Param	Description
`keyword`	Search term; empty = filter only
`search_type`	`1`=find bloggers by note keyword (default), `0`=search by nickname
`column`	Sort field: `comprehensiverank` (default) / `fansCount` / `clickNum` / `mEngagementNum` / `price`
`sort`	`desc` (default) / `asc`
`brand_user_id`	Brand/advertiser user ID, optional; enables brand-specific recommendation and "already cooperated" marks

2. Filter Groups

Group	Covers
`goal`	Marketing goal (exposure / seeding / conversion × metric × cost or scale)
`blogger`	Category, persona, expertise, content theme, top-20 crowds, industry-specific portrait, estimated consumption, note category, gender, location, agency status
`fans`	Fans count, age, gender, location, marital status, consumption level, parenting stage, phone price, phone brand
`note`	Organic note impression / read / engagement medians, 1000-like ratio, note type
`coop`	Quotes, order count, credit score, recent industries & brands, reach scale, estimated CPM / read cost / engagement cost, store-visit cost
`live`	Live sessions in last 30d, average viewers, average GMV
`flags`	Celebrity, high-quality, rising bloggers, note+live capable, intention match, industry recommendation, campaigns, exclude inactive / fans-declining / already-cooperated / already-invited

Numeric ranges are written as {"min": 10000, "max": 50000}. Either bound may be omitted
(omitting min means 0, omitting max means unlimited), but omitting both returns 422.

3. Range Fields (value = `{"min": x, "max": y}`)

Path	Web filter
`fans.count`	Fans count
`note.imp_median` / `note.read_median` / `note.inter_median`	Organic note impression / read / engagement median
`note.thousand_like_percent`	1000-like note ratio (%)
`coop.pic_price` / `coop.video_price`	Sponsored quote (image-text / video, CNY)
`coop.order_count`	Sponsored order count
`coop.reply_48h_ratio`	48h invitation reply rate (%)
`coop.imp_median` / `coop.read_median` / `coop.inter_median`	Sponsored note medians
`coop.cpuv` / `coop.estimate_cpuv`	CPUV / store-visit cost
`coop.pic_cpm` / `coop.video_cpm`	Estimated CPM (image-text / video)
`coop.pic_read_price` / `coop.video_read_price`	Estimated cost per read
`coop.pic_engage_cost` / `coop.video_engage_cost`	Estimated cost per engagement
`live.live_count` / `live.avg_viewer` / `live.avg_gmv`	Live sessions / avg viewers / avg GMV

4. Boolean Flags (value = `true`)

Path	Web filter
`flags.is_star` / `flags.high_quality` / `flags.new_high_quality`	Celebrity / high-quality / rising blogger
`flags.note_and_live`	Accepts both note and live cooperation
`flags.filter_intention`	Industry intention match
`flags.exclude_low_active` / `flags.exclude_fans_down`	Exclude inactive / fans-declining bloggers
`flags.exclude_cooperated` / `flags.exclude_invited`	Exclude already-cooperated / already-invited
`coop.exclude_brands`	With `coop.brand_ids`: `true` = exclude bloggers who worked with those brands

flags.industry_first / flags.industry_second are industry names for industry-recommended
bloggers; flags.activity_codes are campaign codes from /get_blogger_filter_options.

5. Paging

Param	Range	Note
`page_num`	1-250	Upstream exposes only the first 5000 items = 250 pages; page 251+ returns an empty array
`page_size`	1-20	Fixed at 20 on the web page. Keep it at 20: upstream post-filters each page, so a small size may leave 0 rows

Change page_num only and keep every other filter identical, otherwise pages overlap or skip.
total is not the match count, it is the paging cap and is always 5000.

6. Return

kols[]: matched bloggers (~140 fields each)

Identity: userId / name / redId / headPhoto / location / gender

Tags: contentTags / featureTags / personalTags / tradeType

Metrics: fansNum / clickMidNum (read median) / interMidNum (engagement median) /
fans30GrowthRate (fan growth) / kliveCnt30d (live sessions)

Commercial: picturePrice / videoPrice / lowerPrice / estimatePictureCpm /
cooperateState

total: paging cap (always 5000 — not the real match count, see Paging above)

trackId / highlightWords

7. Notes:

Misspelled field names return 422 instead of being silently ignored

Fetch tree-style option values from /get_blogger_filter_options instead of hardcoding them

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]

// ① 关键词找博主：搜「咖啡」相关笔记的博主，按粉丝数降序；带品牌方 ID 做个性化推荐并剔除已合作过的
{"page_num": 1, "page_size": 20, "keyword": "咖啡", "search_type": 1,
 "column": "fansCount", "sort": "desc",
 "brand_user_id": "5dcfa5370000000001006030",
 "flags": {"exclude_cooperated": true}}

// ② 按昵称找号：search_type=0 时 keyword 匹配的是博主昵称而不是笔记内容
{"page_num": 1, "page_size": 20, "keyword": "小鹿", "search_type": 0}

// ③ 最基础的类目 + 粉丝量筛选：粉丝 1 万-5 万的美妆博主，按互动中位数降序
{"page_num": 1, "page_size": 20, "column": "mEngagementNum",
 "fans": {"count": {"min": 10000, "max": 50000}},
 "blogger": {"content_tag": ["美妆"]}}

// ④ 按画像选号：1 万-5 万粉、粉丝以 25-34 岁女性为主的美妆「妈妈」博主
{"page_num": 1, "page_size": 20,
 "blogger": {"content_tag": ["美妆"], "personal_tags": ["妈妈"]},
 "fans": {"count": {"min": 10000, "max": 50000}, "gender": 2, "age": 3}}

// ⑤ 按预算与响应速度选号：图文报价 1 万-5 万、48h 邀约回复率 ≥80%
{"page_num": 1, "page_size": 20,
 "coop": {"pic_price": {"min": 10000, "max": 50000},
          "reply_48h_ratio": {"min": 80}}}

// ⑥ 按性价比选号：图文报价 ≤5000、阅读中位数 ≥3000 的视频博主，只看优质号并剔除低活
{"page_num": 1, "page_size": 20,
 "note": {"read_median": {"min": 3000}, "note_type": 2},
 "coop": {"pic_price": {"max": 5000}},
 "flags": {"high_quality": true, "exclude_low_active": true}}

// ⑦ 找会直播带货的博主：近 30 天开播 1-5 场、场均销售额 ≥1 万，且笔记+直播均可合作
{"page_num": 1, "page_size": 20,
 "live": {"live_count": {"min": 1, "max": 5}, "avg_gmv": {"min": 10000}},
 "flags": {"note_and_live": true}}

// ⑧ 多维组合：7 个筛选组同时生效（字段名写错会直接 422，不会被静默忽略）
{"page_num": 1, "page_size": 20, "column": "comprehensiverank", "sort": "desc",
 "goal":    {"market_target": "mAccumImpNum"},
 "blogger": {"content_tag": ["美妆"], "gender": "女", "signed": 0},
 "fans":    {"count": {"min": 10000}, "age": 3, "device_brand": ["苹果"]},
 "note":    {"inter_median": {"min": 500}, "thousand_like_percent": {"min": 20}},
 "coop":    {"industry": "美妆个护", "video_price": {"max": 8000}},
 "live":    {"avg_viewer": {"min": 5000}},
 "flags":   {"exclude_cooperated": true}}

// 取数：kols = resp["data"]["data"]["kols"]

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Example

{
    "page_num": 1,
    "page_size": 20,
    "keyword": "咖啡",
    "search_type": 1,
    "column": "comprehensiverank",
    "sort": "desc",
    "brand_user_id": "5dcfa5370000000001006030"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

蒲公英笔记博主广场（找博主/选号）/PGY note blogger square

[中文]

用途:

1. 搜索与排序

2. 筛选分组

3. 区间型字段（值写成 `{"min": x, "max": y}`）

4. 开关型字段（值写 `true`）

5. 翻页

6. 返回

7. 注意:

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

计费:

[English]

Purpose:

1. Search & Sort

2. Filter Groups

3. Range Fields (value = `{"min": x, "max": y}`)

4. Boolean Flags (value = `true`)

5. Paging

6. Return

7. Notes:

Response shape (two layers):

Billing:

[示例/Example]

Request

Request Code Samples

Responses

蒲公英笔记博主广场（找博主/选号）/PGY note blogger square

[中文]#

用途:#

1. 搜索与排序#

2. 筛选分组#

3. 区间型字段（值写成 {"min": x, "max": y}）#

4. 开关型字段（值写 true）#

5. 翻页#

6. 返回#

7. 注意:#

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

计费:#

[English]#

Purpose:#

1. Search & Sort#

2. Filter Groups#

3. Range Fields (value = {"min": x, "max": y})#

4. Boolean Flags (value = true)#

5. Paging#

6. Return#

7. Notes:#

Response shape (two layers):#

Billing:#

[示例/Example]#

Request

Request Code Samples

Responses

[中文]

用途:

1. 搜索与排序

2. 筛选分组

3. 区间型字段（值写成 `{"min": x, "max": y}`）

4. 开关型字段（值写 `true`）

5. 翻页

6. 返回

7. 注意:

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

计费:

[English]

Purpose:

1. Search & Sort

2. Filter Groups

3. Range Fields (value = `{"min": x, "max": y}`)

4. Boolean Flags (value = `true`)

5. Paging

6. Return

7. Notes:

Response shape (two layers):

Billing:

[示例/Example]