hongben-server/docs/api/pinterest/frontend_guide.md

Pinterest API 前端调用指南

本指南详细说明了如何调用后端提供的 Pinterest 数据采集接口。

Base URL: http://<your-server-ip>:3000/api/pinterest

---

1. 搜索博主 (Search Profiles)

根据关键词搜索 Pinterest 博主。 注意: 后端会自动将关键词转换为 Pinterest 搜索链接 (https://www.pinterest.com/search/users/?q=...) 进行采集。

• Endpoint: /search
• Method: GET
• Params:
  • keyword (必填): 搜索关键词，例如 fashion
  • country (选填): 国家代码，默认为 US（目前该参数主要用于记录，实际搜索结果取决于 Dataset 采集时的 IP 策略）

请求示例:

// GET /api/pinterest/search?keyword=fashion
fetch('http://localhost:3000/api/pinterest/search?keyword=fashion')
  .then(res => res.json())
  .then(data => console.log(data));

响应示例:

{
  "success": true,
  "data": [
    {
      "url": "https://www.pinterest.com/example_user/",
      "name": "Example User",
      "follower_count": 12345,
      "description": "Fashion blogger...",
      // ... 其他博主信息
    }
  ],
  "timestamp": "2024-02-14T..."
}

---

2. 获取博主帖子 (Get User Posts)

获取指定博主的帖子/视频列表。

• Endpoint: /users/posts
• Method: GET
• Params:
  • url (必填): 博主的 Pinterest 个人主页链接
  • count (选填): 获取数量，默认为 20

请求示例:

// GET /api/pinterest/users/posts?url=https://www.pinterest.com/example_user/&count=10
const profileUrl = encodeURIComponent('https://www.pinterest.com/example_user/');
fetch(`http://localhost:3000/api/pinterest/users/posts?url=${profileUrl}&count=10`)
  .then(res => res.json())
  .then(data => console.log(data));

响应示例:

{
  "success": true,
  "data": [
    {
      "url": "https://www.pinterest.com/pin/123456789/",
      "title": "Post Title",
      "image_video_url": "...",
      // ... 其他帖子信息
    }
  ],
  "timestamp": "..."
}

---

3. 获取帖子评论 (Get Post Comments)

获取指定帖子的详情及评论。

• Endpoint: /posts/comments
• Method: GET
• Params:
  • url (必填): 帖子的链接

请求示例:

// GET /api/pinterest/posts/comments?url=https://www.pinterest.com/pin/123456789/
const postUrl = encodeURIComponent('https://www.pinterest.com/pin/123456789/');
fetch(`http://localhost:3000/api/pinterest/posts/comments?url=${postUrl}`)
  .then(res => res.json())
  .then(data => console.log(data));

响应示例:

{
  "success": true,
  "data": {
    "post_id": "123456789",
    "title": "Post Title",
    "comments_num": 10,
    "comments": [
      {
        "comment_id": "...",
        "text": "Great post!",
        "author_name": "User A",
        "date": "...",
        "likes": 5
      }
    ]
  },
  "timestamp": "..."
}

注意事项

1. 异步处理: 后端会自动触发采集任务并轮询直到完成，因此请求可能会持续几秒到几十秒（甚至更久，取决于 Bright Data 的队列），请前端务必做好 Loading 状态展示（建议显示“正在从 Pinterest 采集数据，请稍候...”）。
2. 超时控制: 由于采集耗时较长，请确保前端请求的超时时间（Timeout）设置得足够长（建议 60秒以上）。
3. URL 编码: 传递 URL 参数时，必须使用 encodeURIComponent 进行编码。