Pinterest Search API

Pinterest Search

主要特性

• 通过 query 发现 Pin接受一个非空文本 query，并通过 1 到 2,000 的 results_limit 请求数量受控的公开 Pin 记录。
• 标准化 Pin、创作者与媒体记录以一致结构返回 Pin ID、URL、标题、正文、公开创作者字段以及图片或视频引用。
• 分类与可见信号上下文保留可用的 categories、hashtags、Pin 类型、来源信息、可见点赞数、评论数、创作者粉丝数、发布时间、采集时间和输入 query 上下文。

参数

如何使用

提交 Pinterest 文本 query 和结果上限，跟踪异步任务，再通过 cursor 分页读取标准化 Pin。

1. 准备一个非空文本 query，并选择 1 到 2,000 的 results_limit。
2. 将 query 和 results_limit POST 到 /v1/pinterest/search，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
4. 读取 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