613 lines
17 KiB
Markdown
613 lines
17 KiB
Markdown
# Discovery模块API文档
|
||
|
||
## 概述
|
||
|
||
Discovery (发现) 模块是一个用于搜索和发现创作者/达人的系统。该模块提供了一系列RESTful API接口，用于创建搜索会话、搜索创作者和查询历史搜索结果。
|
||
|
||
## 通用响应格式
|
||
|
||
所有API响应都遵循以下统一的JSON格式：
|
||
|
||
```json
|
||
{
|
||
"code": 200, // 状态码，200表示成功，其他值表示错误
|
||
"message": "成功", // 响应消息
|
||
"data": {} // 响应数据，可能是对象、数组或null
|
||
}
|
||
```
|
||
|
||
## 分页响应格式
|
||
|
||
使用分页的接口将返回以下格式：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取数据成功",
|
||
"data": {
|
||
"count": 100, // 总记录数
|
||
"next": "下一页URL或null", // 下一页链接
|
||
"previous": "上一页URL或null", // 上一页链接
|
||
"results": [] // 当前页的数据
|
||
}
|
||
}
|
||
```
|
||
|
||
## 认证方式
|
||
|
||
所有接口都需要使用自定义Token认证，请在HTTP请求头中添加以下字段：
|
||
|
||
```
|
||
Authorization: Token your_token_here
|
||
```
|
||
|
||
## 1. 搜索会话管理 (Sessions)
|
||
|
||
搜索会话保存了搜索历史记录和搜索结果，便于追踪和回顾之前的搜索。
|
||
|
||
### 1.1 获取搜索会话列表
|
||
|
||
- **URL**: `/sessions/`
|
||
- **方法**: `GET`
|
||
- **描述**: 获取所有搜索会话的列表
|
||
- **请求参数**:
|
||
- `page`: 页码，默认为1
|
||
- `page_size`: 每页记录数，默认为20，最大为100
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取搜索会话列表成功",
|
||
"data": {
|
||
"count": 10,
|
||
"next": null,
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"session_number": 1,
|
||
"creator_count": 20,
|
||
"shoppable_creators": 15,
|
||
"avg_followers": 10000.5,
|
||
"avg_gmv": 5000.25,
|
||
"avg_video_views": 20000.75,
|
||
"date_created": "2023-06-01"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.2 创建搜索会话
|
||
|
||
- **URL**: `/sessions/`
|
||
- **方法**: `POST`
|
||
- **描述**: 创建一个新的搜索会话
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"session_number": 1, // 可选，默认为1
|
||
"creator_count": 0, // 可选，默认为0
|
||
"shoppable_creators": 0, // 可选，默认为0
|
||
"avg_followers": 0, // 可选，默认为0
|
||
"avg_gmv": 0, // 可选，默认为0
|
||
"avg_video_views": 0, // 可选，默认为0
|
||
"date_created": "2023-06-01" // 可选，默认为当前日期
|
||
}
|
||
```
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "创建搜索会话成功",
|
||
"data": {
|
||
"id": 1,
|
||
"session_number": 1,
|
||
"creator_count": 0,
|
||
"shoppable_creators": 0,
|
||
"avg_followers": 0,
|
||
"avg_gmv": 0,
|
||
"avg_video_views": 0,
|
||
"date_created": "2023-06-01"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.3 获取搜索会话详情
|
||
|
||
- **URL**: `/sessions/{id}/`
|
||
- **方法**: `GET`
|
||
- **描述**: 获取指定ID的搜索会话详情，包含相关的创作者数据
|
||
- **请求参数**: 无
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取搜索会话详情成功",
|
||
"data": {
|
||
"id": 1,
|
||
"session_number": 1,
|
||
"creator_count": 20,
|
||
"shoppable_creators": 15,
|
||
"avg_followers": 10000.5,
|
||
"avg_gmv": 5000.25,
|
||
"avg_video_views": 20000.75,
|
||
"date_created": "2023-06-01",
|
||
"creators": [
|
||
{
|
||
"id": 1,
|
||
"session": 1,
|
||
"name": "创作者名称",
|
||
"avatar": "https://example.com/avatar.jpg",
|
||
"category": "Sports & Outdoor",
|
||
"ecommerce_level": "L3",
|
||
"exposure_level": "KOL-2",
|
||
"followers": 15000,
|
||
"gmv": 8000,
|
||
"items_sold": 500,
|
||
"avg_video_views": 25000,
|
||
"has_ecommerce": true,
|
||
"tiktok_url": "https://tiktok.com/@username",
|
||
"hashtags": "#sport#fitness#outdoor",
|
||
"trends": "summer fitness",
|
||
"profile": "tiktok"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.4 更新搜索会话
|
||
|
||
- **URL**: `/sessions/{id}/`
|
||
- **方法**: `PUT`/`PATCH`
|
||
- **描述**: 更新指定ID的搜索会话信息
|
||
- **请求参数**: 同创建搜索会话
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "更新搜索会话成功",
|
||
"data": {
|
||
"id": 1,
|
||
"session_number": 2,
|
||
"creator_count": 25,
|
||
"shoppable_creators": 18,
|
||
"avg_followers": 12000.5,
|
||
"avg_gmv": 6000.25,
|
||
"avg_video_views": 22000.75,
|
||
"date_created": "2023-06-01"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.5 删除搜索会话
|
||
|
||
- **URL**: `/sessions/{id}/`
|
||
- **方法**: `DELETE`
|
||
- **描述**: 删除指定ID的搜索会话
|
||
- **请求参数**: 无
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "删除搜索会话成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 1.6 获取会话创作者列表
|
||
|
||
- **URL**: `/sessions/{id}/results/`
|
||
- **方法**: `GET`
|
||
- **描述**: 获取指定会话的搜索结果（创作者列表）
|
||
- **请求参数**:
|
||
- `page`: 页码，默认为1
|
||
- `page_size`: 每页记录数，默认为20，最大为100
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取会话创作者列表成功",
|
||
"data": {
|
||
"count": 20,
|
||
"next": null,
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"session": 1,
|
||
"name": "创作者名称",
|
||
"avatar": "https://example.com/avatar.jpg",
|
||
"category": "Sports & Outdoor",
|
||
"ecommerce_level": "L3",
|
||
"exposure_level": "KOL-2",
|
||
"followers": 15000,
|
||
"gmv": 8000,
|
||
"items_sold": 500,
|
||
"avg_video_views": 25000,
|
||
"has_ecommerce": true,
|
||
"tiktok_url": "https://tiktok.com/@username",
|
||
"hashtags": "#sport#fitness#outdoor",
|
||
"trends": "summer fitness",
|
||
"profile": "tiktok"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.7 获取会话摘要
|
||
|
||
- **URL**: `/sessions/summary/`
|
||
- **方法**: `GET`
|
||
- **描述**: 获取所有会话的摘要数据，用于展示在表格中
|
||
- **请求参数**: 无
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取会话摘要列表成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"session_number": 1,
|
||
"date": "2023-06-01",
|
||
"creator_count": 20,
|
||
"shoppable_creators": 15,
|
||
"avg_followers": 10000.5,
|
||
"avg_gmv": 5000.25,
|
||
"avg_video_views": 20000.75
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 1.8 搜索会话
|
||
|
||
- **URL**: `/sessions/search/`
|
||
- **方法**: `GET`
|
||
- **描述**: 根据关键词搜索会话，支持模糊匹配
|
||
- **请求参数**:
|
||
- `keyword`: 搜索关键词（必填），可以是会话ID、会话编号、日期或日期的一部分（如年份"2025"或月份"6"）
|
||
- **搜索说明**:
|
||
- 支持按会话ID或会话编号精确搜索
|
||
- 支持按完整日期格式（如"2023-06-01"）搜索
|
||
- 支持按年份（如"2025"）搜索该年的所有会话
|
||
- 支持按月份数字（1-12）或月份名称（如"june"、"六月"）搜索
|
||
- 支持模糊匹配ID和会话编号
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "搜索会话成功，关键词: 2025",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"session_number": 1,
|
||
"date": "2025-06-01",
|
||
"creator_count": 20,
|
||
"shoppable_creators": 15,
|
||
"avg_followers": 10000.5,
|
||
"avg_gmv": 5000.25,
|
||
"avg_video_views": 20000.75
|
||
},
|
||
{
|
||
"id": 2,
|
||
"session_number": 2,
|
||
"date": "2025-07-15",
|
||
"creator_count": 18,
|
||
"shoppable_creators": 12,
|
||
"avg_followers": 12000.5,
|
||
"avg_gmv": 6000.25,
|
||
"avg_video_views": 25000.75
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 2. 创作者管理 (Creators)
|
||
|
||
创作者是系统中的核心数据实体，代表平台上的内容创作者/达人。
|
||
|
||
### 2.1 获取创作者列表
|
||
|
||
- **URL**: `/creators/`
|
||
- **方法**: `GET`
|
||
- **描述**: 获取所有创作者的列表
|
||
- **请求参数**:
|
||
- `page`: 页码，默认为1
|
||
- `page_size`: 每页记录数，默认为20，最大为100
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取创作者列表成功",
|
||
"data": {
|
||
"count": 100,
|
||
"next": "http://example.com/api/creators/?page=2",
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"session": 1,
|
||
"name": "创作者名称",
|
||
"avatar": "https://example.com/avatar.jpg",
|
||
"category": "Sports & Outdoor",
|
||
"ecommerce_level": "L3",
|
||
"exposure_level": "KOL-2",
|
||
"followers": 15000,
|
||
"gmv": 8000,
|
||
"items_sold": 500,
|
||
"avg_video_views": 25000,
|
||
"has_ecommerce": true,
|
||
"tiktok_url": "https://tiktok.com/@username",
|
||
"hashtags": "#sport#fitness#outdoor",
|
||
"trends": "summer fitness",
|
||
"profile": "tiktok"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 获取创作者详情
|
||
|
||
- **URL**: `/creators/{id}/`
|
||
- **方法**: `GET`
|
||
- **描述**: 获取指定ID的创作者详细信息
|
||
- **请求参数**: 无
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取创作者详情成功",
|
||
"data": {
|
||
"id": 1,
|
||
"session": 1,
|
||
"name": "创作者名称",
|
||
"avatar": "https://example.com/avatar.jpg",
|
||
"category": "Sports & Outdoor",
|
||
"ecommerce_level": "L3",
|
||
"exposure_level": "KOL-2",
|
||
"followers": 15000,
|
||
"gmv": 8000,
|
||
"items_sold": 500,
|
||
"avg_video_views": 25000,
|
||
"has_ecommerce": true,
|
||
"tiktok_url": "https://tiktok.com/@username",
|
||
"hashtags": "#sport#fitness#outdoor",
|
||
"trends": "summer fitness",
|
||
"profile": "tiktok"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.3 搜索创作者
|
||
|
||
- **URL**: `/creators/search/`
|
||
- **方法**: `POST`
|
||
- **描述**: 根据多种条件搜索创作者，会自动创建搜索会话并保存搜索结果
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"query": "运动", // 可选，搜索关键词
|
||
"category": "Sports & Outdoor", // 可选，类别
|
||
"ecommerce_level": "L3", // 可选，电商等级（L1-L5）
|
||
"exposure_level": "KOL-2", // 可选，曝光等级
|
||
"hashtag": "fitness", // 可选，标签
|
||
"trend": "summer", // 可选，趋势
|
||
"profile": "tiktok" // 可选，平台（tiktok、instagram等）
|
||
}
|
||
```
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "搜索创作者成功",
|
||
"data": {
|
||
"id": 1,
|
||
"session_number": 1,
|
||
"creator_count": 5,
|
||
"shoppable_creators": 3,
|
||
"avg_followers": 12000.5,
|
||
"avg_gmv": 5500.25,
|
||
"avg_video_views": 20500.75,
|
||
"date_created": "2023-06-01",
|
||
"creators": [
|
||
{
|
||
"id": 1,
|
||
"session": 1,
|
||
"name": "创作者名称",
|
||
"avatar": "https://example.com/avatar.jpg",
|
||
"category": "Sports & Outdoor",
|
||
"ecommerce_level": "L3",
|
||
"exposure_level": "KOL-2",
|
||
"followers": 15000,
|
||
"gmv": 8000,
|
||
"items_sold": 500,
|
||
"avg_video_views": 25000,
|
||
"has_ecommerce": true,
|
||
"tiktok_url": "https://tiktok.com/@username",
|
||
"hashtags": "#sport#fitness#outdoor",
|
||
"trends": "summer fitness",
|
||
"profile": "tiktok"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.4 搜索标签和趋势
|
||
|
||
- **URL**: `/creators/search_tags/`
|
||
- **方法**: `POST`
|
||
- **描述**: 专门用于搜索标签和趋势，会创建搜索会话并保存搜索结果
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"mode": "hashtag", // 必填，搜索模式，"hashtag"或"trend"
|
||
"keyword": "fitness", // 必填，搜索关键词
|
||
"profile": "tiktok" // 可选，平台
|
||
}
|
||
```
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "搜索hashtag成功，关键词: fitness",
|
||
"data": {
|
||
"id": 1,
|
||
"session_number": 1,
|
||
"creator_count": 8,
|
||
"shoppable_creators": 5,
|
||
"avg_followers": 13000.5,
|
||
"avg_gmv": 6500.25,
|
||
"avg_video_views": 22500.75,
|
||
"date_created": "2023-06-01",
|
||
"creators": [
|
||
{
|
||
"id": 1,
|
||
"session": 1,
|
||
"name": "创作者名称",
|
||
"avatar": "https://example.com/avatar.jpg",
|
||
"category": "Sports & Outdoor",
|
||
"ecommerce_level": "L3",
|
||
"exposure_level": "KOL-2",
|
||
"followers": 15000,
|
||
"gmv": 8000,
|
||
"items_sold": 500,
|
||
"avg_video_views": 25000,
|
||
"has_ecommerce": true,
|
||
"tiktok_url": "https://tiktok.com/@username",
|
||
"hashtags": "#sport#fitness#outdoor",
|
||
"trends": "summer fitness",
|
||
"profile": "tiktok"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.5 自然语言搜索创作者
|
||
|
||
- **URL**: `/creators/search_individual/`
|
||
- **方法**: `POST`
|
||
- **描述**: 根据用户输入的自然语言文本搜索达人，使用外部API进行处理
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"criteria": "我需要粉丝超过10万的健身类达人，擅长做运动装备测评", // 必填，搜索条件
|
||
"top_n": 10 // 可选，返回结果数量，默认10
|
||
}
|
||
```
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "搜索创作者成功",
|
||
"data": {
|
||
"id": 1,
|
||
"session_number": 1,
|
||
"creator_count": 10,
|
||
"shoppable_creators": 7,
|
||
"avg_followers": 150000.5,
|
||
"avg_gmv": 9500.25,
|
||
"avg_video_views": 35000.75,
|
||
"date_created": "2023-06-01",
|
||
"creators": [
|
||
{
|
||
"id": 1,
|
||
"session": 1,
|
||
"name": "创作者名称",
|
||
"avatar": "https://example.com/avatar.jpg",
|
||
"category": "Sports & Outdoor",
|
||
"ecommerce_level": "L4",
|
||
"exposure_level": "KOL-2",
|
||
"followers": 180000,
|
||
"gmv": 12000,
|
||
"items_sold": 800,
|
||
"avg_video_views": 45000,
|
||
"has_ecommerce": true,
|
||
"tiktok_url": "https://tiktok.com/@username",
|
||
"hashtags": "#sport#fitness#outdoor#review",
|
||
"trends": "fitness equipment review",
|
||
"profile": "tiktok"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3. 字段说明
|
||
|
||
### 3.1 搜索会话字段
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|------------------|---------|------------------------------|
|
||
| id | 整数 | 会话ID |
|
||
| session_number | 整数 | 会话编号 |
|
||
| creator_count | 整数 | 创作者数量 |
|
||
| shoppable_creators | 整数 | 可购物创作者数量 |
|
||
| avg_followers | 浮点数 | 平均粉丝数 |
|
||
| avg_gmv | 浮点数 | 平均GMV(商品总价值) |
|
||
| avg_video_views | 浮点数 | 平均视频观看量 |
|
||
| date_created | 日期 | 创建日期 |
|
||
|
||
### 3.2 创作者字段
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|------------------|---------|------------------------------|
|
||
| id | 整数 | 创作者ID |
|
||
| session | 整数 | 所属会话ID |
|
||
| name | 字符串 | 创作者名称 |
|
||
| avatar | URL | 头像链接 |
|
||
| category | 字符串 | 类别，可选值：Phones & Electronics, Womenswear & Underwear等 |
|
||
| ecommerce_level | 字符串 | 电商等级，可选值：L1, L2, L3, L4, L5, New tag |
|
||
| exposure_level | 字符串 | 曝光等级，可选值：KOC-1, KOC-2, KOL-2, KOL-3, New tag |
|
||
| followers | 浮点数 | 粉丝数 |
|
||
| gmv | 浮点数 | GMV(商品总价值) |
|
||
| items_sold | 浮点数 | 已售项目数 |
|
||
| avg_video_views | 浮点数 | 平均视频观看量 |
|
||
| has_ecommerce | 布尔值 | 是否有电商 |
|
||
| tiktok_url | URL | 抖音链接 |
|
||
| hashtags | 字符串 | 标签，格式如"#sport#fitness" |
|
||
| trends | 字符串 | 趋势，格式如"summer fitness" |
|
||
| profile | 字符串 | 达人平台，可选值：tiktok, instagram, youtube, xiaohongshu, other |
|
||
|
||
## 4. 使用示例
|
||
|
||
### 4.1 搜索标签为"fitness"的TikTok创作者
|
||
|
||
```http
|
||
POST /api/creators/search_tags/
|
||
Content-Type: application/json
|
||
Authorization: Token your_token_here
|
||
|
||
{
|
||
"mode": "hashtag",
|
||
"keyword": "fitness",
|
||
"profile": "tiktok"
|
||
}
|
||
```
|
||
|
||
### 4.2 获取最近一次搜索会话的详情
|
||
|
||
```http
|
||
GET /api/sessions/1/
|
||
Authorization: Token your_token_here
|
||
```
|
||
|
||
### 4.3 使用自然语言搜索创作者
|
||
|
||
```http
|
||
POST /api/creators/search_individual/
|
||
Content-Type: application/json
|
||
Authorization: Token your_token_here
|
||
|
||
{
|
||
"criteria": "需要3个粉丝超过50万的美妆达人，产品转化率高",
|
||
"top_n": 3
|
||
}
|
||
```
|