Rednote Search Notes
Rednote Search Notes 是与关键词匹配的公开帖子，包含笔记身份、正文、作者信息、媒体、发布时间和可见互动数据。这些记录可用于主题研究、内容形式比较、来源审阅以及分时点搜索结果分析。
主要特性
- 关键词搜索与三类筛选条件接受一个文本 query，并可按受支持的排序、媒体类型和发布时间范围限定公开笔记搜索。
- 标准化笔记身份与内容通过统一 PostItem 结构返回笔记 ID、公开 URL、正文、资源类型、发布时间和采集时间。
- 作者、媒体与可见互动信息保留可用的公开作者字段、图片或视频引用、标签、提及，以及可见点赞、评论、分享和浏览数量。
- 范围明确的来源搜索页每个任务按所选条件执行一次第 1 页搜索，提供范围明确的快照，不将其描述为覆盖全部后续页。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
query | 必填 | 用于搜索公开 Rednote 笔记的必填非空文本；Playground 会保持为空，直到你输入自己的搜索词。 |
sort_by | 可选 | 选填的结果排序方式：general、latest 或 most_liked。Playground 初始选择 general。 |
media_type | 可选 | 选填的笔记形式筛选：all、image 或 video。Playground 初始选择 all。 |
published_within | 可选 | 选填的发布时间范围：all、day、week 或 six_months。Playground 初始选择 all。 |
如何使用
提交 Rednote 搜索 query 和可选筛选条件，跟踪异步任务，再使用 SocQ cursor 分页读取已存储的笔记记录。
- 准备非空 query，并仅选择受支持的 sort_by、media_type 和 published_within 值。
- 将请求体 POST 到 /v1/rednote/search-notes，并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
- 读取 data.results.items；has_more 为 true 时继续使用 next_cursor。该 cursor 只翻阅已存储结果，不会请求更多 Rednote 搜索页。
curl -X POST "https://api.socq.ai/v1/rednote/search-notes" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"query\":\"$REDNOTE_SEARCH_QUERY\",\"sort_by\":\"general\",\"media_type\":\"all\",\"published_within\":\"all\"}"
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor最佳使用场景
- 建立关键词结果目录： 结合笔记 ID、公开 URL、正文、作者引用和 collected_at，为明确的 query 建立可追溯快照。
- 比较图片与视频结果： 分别使用不同 media_type，比较各快照中的媒体引用、笔记正文和可见互动指标。
- 审阅近期主题内容： 结合 latest 排序或发布时间范围，以及 published_at 和 collected_at，审阅某个主题近期出现的笔记。
- 分析作者上下文： 将匹配笔记的正文和媒体关联到可用作者身份字段，研究某次 query 快照中出现的公开账号。
使用建议
- 提交前移除 query 首尾空白并确认内容非空，避免任务被必填校验拒绝。
- 只使用已列出的枚举值；需要范围最宽的明确配置时，选择 general、all 和 all。
- 将每个任务视为一个来源搜索页；如需比较筛选条件，应分别提交任务，不要假设快照包含后续来源页。
- 当已存储快照跨越多个 SocQ 结果页时，持续使用 next_cursor 直到 has_more 为 false；该 cursor 不会请求新的 Rednote 来源页。
- 对不同时间的 query 结果进行核对时，使用笔记 ID 和 URL 去重，因为排序和可见指标可能随采集时间变化。
- 将正文、作者字段、媒体、发布时间、标签、提及和单项指标按可空字段处理，并在渲染公开文本前进行安全转义。