# 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 策略）

**请求示例**:
```javascript
// GET /api/pinterest/search?keyword=fashion
fetch('http://localhost:3000/api/pinterest/search?keyword=fashion')
  .then(res => res.json())
  .then(data => console.log(data));
```

**响应示例**:
```json
{
  "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

**请求示例**:
```javascript
// 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));
```

**响应示例**:
```json
{
  "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` (必填): 帖子的链接

**请求示例**:
```javascript
// 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));
```

**响应示例**:
```json
{
  "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` 进行编码。