Pinterest Search
Pinterest Search 结果是与文本 query 匹配的公开 Pin，包含标题、说明文字、创作者信息、媒体引用、分类、标签、时间和可见互动信号。这些记录可用于主题发现、视觉形式研究、创作者上下文分析和基于 query 的内容比较。
主要特性
- 通过 query 发现 Pin接受一个非空文本 query，并通过 1 到 2,000 的 results_limit 请求数量受控的公开 Pin 记录。
- 标准化 Pin、创作者与媒体记录以一致结构返回 Pin ID、URL、标题、正文、公开创作者字段以及图片或视频引用。
- 分类与可见信号上下文保留可用的 categories、hashtags、Pin 类型、来源信息、可见点赞数、评论数、创作者粉丝数、发布时间、采集时间和输入 query 上下文。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
query | 必填 | 必填的非空文本 query，用于发现公开 Pinterest Pin；提交前会移除首尾空白。 |
results_limit | 可选 | 该 query 请求的 Pin 数量上限；默认值为 100，可设置为 1 到 2,000。 |
如何使用
提交 Pinterest 文本 query 和结果上限，跟踪异步任务，再通过 cursor 分页读取标准化 Pin。
- 准备一个非空文本 query，并选择 1 到 2,000 的 results_limit。
- 将 query 和 results_limit POST 到 /v1/pinterest/search，并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
- 读取 data.results.items；has_more 为 true 时，使用返回的 next_cursor 请求下一页。
curl -X POST "https://api.socq.ai/v1/pinterest/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"home office ideas","results_limit":100}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor最佳使用场景
- 构建主题 Pin 数据集： 通过明确的 query，结合 Pin ID、来源 URL、标题、正文、媒体引用和 discovery_input，建立可追溯的主题集合。
- 研究视觉形式与分类： 比较图片或视频、post_type、categories、hashtags、标题和说明文字，研究搜索结果中的内容形式与主题。
- 比较创作者与可见信号： 结合公开创作者字段、点赞数、评论数、粉丝数和 collected_at，比较不同 query 集合在采集时观察到的上下文。
使用建议
- 移除意外的首尾空白后提交非空 query，并将 results_limit 保持在 1 到 2,000 之间，以满足输入校验。
- 当存储结果超过默认的首个 50 条结果页时，持续使用 next_cursor，直到 has_more 为 false。
- 保留 extra.discovery_input 和 collected_at，使每条 Pin 都能关联到输入 keyword 与观察时间。
- 将标题、正文、创作者信息、媒体、created_at、categories、hashtags、source 和各项指标作为选填字段处理，不要把缺失值视为请求失败。
相关 API
需要其他类型的 Pinterest 公开数据时，可以使用以下 API。
- Pinterest Pins API — 从公开 Pin URL 获取标准化内容、创作者、媒体、分类、时间和可见指标。
- Pinterest User Pins API — 通过主页 URL 和每个主页的结果上限发现公开 Pin，返回标准化内容、创作者、媒体、时间和可见指标。
- Pinterest Profiles API — 通过主页 URL 获取公开身份、简介、图片、网站、可见账号数量和采集上下文。