687 lines
14 KiB
Markdown
687 lines
14 KiB
Markdown
# 抖音播放量数据API接口文档
|
||
|
||
## 概述
|
||
|
||
本API服务提供抖音播放量数据的查询、搜索、统计等功能，专为小程序优化设计。
|
||
|
||
**基础信息**
|
||
- 服务地址：`http://localhost:5000`
|
||
- 数据源：MongoDB数据库
|
||
- 数据更新：每晚24:00自动更新
|
||
- 响应格式：JSON
|
||
|
||
## 通用响应格式
|
||
|
||
所有API接口都遵循以下响应格式：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {},
|
||
"message": "操作成功",
|
||
"update_time": "2025-10-17 15:30:00"
|
||
}
|
||
```
|
||
|
||
**字段说明**
|
||
- `success`: 请求是否成功
|
||
- `data`: 返回的数据内容
|
||
- `message`: 操作结果描述
|
||
- `update_time`: 数据更新时间
|
||
|
||
## 数据模型
|
||
|
||
### 合集数据项
|
||
```json
|
||
{
|
||
"_id": "674f1234567890abcdef",
|
||
"batch_time": "2025-10-17 15:30:00",
|
||
"mix_name": "合集名称",
|
||
"video_url": "https://www.douyin.com/video/xxx",
|
||
"playcount": "1.2亿",
|
||
"play_vv": 120000000,
|
||
"request_id": "request_xxx",
|
||
"rank": 1,
|
||
"cover_image_url": "https://p3.douyinpic.com/xxx",
|
||
"cover_backup_urls": ["url1", "url2"]
|
||
}
|
||
```
|
||
|
||
### 分页信息
|
||
```json
|
||
{
|
||
"pagination": {
|
||
"page": 1,
|
||
"limit": 20,
|
||
"total": 100,
|
||
"pages": 5,
|
||
"has_next": true,
|
||
"has_prev": false
|
||
}
|
||
}
|
||
```
|
||
|
||
## API接口列表
|
||
|
||
### 1. 首页信息
|
||
|
||
**接口地址**
|
||
```
|
||
GET /
|
||
```
|
||
|
||
**功能描述**
|
||
获取API服务的基本信息和所有可用接口列表
|
||
|
||
**请求参数**
|
||
无
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"name": "抖音播放量数据API服务",
|
||
"version": "2.0",
|
||
"description": "主程序服务 - 整合小程序API功能",
|
||
"endpoints": {
|
||
"/api/rank/videos": "获取视频列表 (支持分页和排序)",
|
||
"/api/rank/top": "获取热门视频榜单",
|
||
"/api/rank/search": "搜索视频",
|
||
"/api/rank/detail": "获取视频详情",
|
||
"/api/rank/stats": "获取统计信息",
|
||
"/api/rank/health": "健康检查",
|
||
"/api/rank/rankings": "获取榜单列表",
|
||
"/api/rank/rankings/dates": "获取可用榜单日期",
|
||
"/api/rank/rankings/types": "获取榜单类型",
|
||
"/api/rank/rankings/latest": "获取最新榜单",
|
||
"/api/rank/rankings/stats": "获取榜单统计"
|
||
},
|
||
"features": [
|
||
"分页支持",
|
||
"多种排序方式",
|
||
"搜索功能",
|
||
"详情查看",
|
||
"统计分析",
|
||
"榜单查询",
|
||
"动态排序",
|
||
"小程序优化"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 获取视频列表
|
||
|
||
**接口地址**
|
||
```
|
||
GET /api/rank/videos
|
||
```
|
||
|
||
**功能描述**
|
||
获取分页的视频合集列表，支持多种排序方式
|
||
|
||
**请求参数**
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| page | int | 否 | 1 | 页码 |
|
||
| limit | int | 否 | 20 | 每页数量 |
|
||
| sort | string | 否 | playcount | 排序方式：playcount(播放量) / growth(增长量) |
|
||
| start_date | string | 否 | 昨天 | 增长计算开始日期(格式: YYYY-MM-DD) |
|
||
| end_date | string | 否 | 今天 | 增长计算结束日期(格式: YYYY-MM-DD) |
|
||
|
||
**使用示例**
|
||
```
|
||
# 按播放量排序
|
||
GET /api/rank/videos?page=1&limit=20&sort=playcount
|
||
|
||
# 按增长量排序（默认昨天到今天的增长）
|
||
GET /api/rank/videos?page=1&limit=20&sort=growth
|
||
|
||
# 按自定义日期范围的增长排序
|
||
GET /api/rank/videos?page=1&limit=20&sort=growth&start_date=2025-10-16&end_date=2025-10-17
|
||
```
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"_id": "674f1234567890abcdef",
|
||
"batch_time": "2025-10-17 15:30:00",
|
||
"mix_name": "热门合集1",
|
||
"video_url": "https://www.douyin.com/video/xxx",
|
||
"playcount": "1.2亿",
|
||
"play_vv": 120000000,
|
||
"request_id": "request_xxx",
|
||
"rank": 1,
|
||
"cover_image_url": "https://p3.douyinpic.com/xxx",
|
||
"cover_backup_urls": ["url1", "url2"]
|
||
}
|
||
],
|
||
"pagination": {
|
||
"page": 1,
|
||
"limit": 20,
|
||
"total": 100,
|
||
"pages": 5,
|
||
"has_next": true,
|
||
"has_prev": false
|
||
},
|
||
"sort_by": "playcount",
|
||
"update_time": "2025-10-17 15:30:00"
|
||
}
|
||
```
|
||
|
||
### 3. 获取热门榜单
|
||
|
||
**接口地址**
|
||
```
|
||
GET /api/rank/top
|
||
```
|
||
|
||
**功能描述**
|
||
获取热门视频榜单（按播放量排序）
|
||
|
||
**请求参数**
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| limit | int | 否 | 10 | 返回数量 |
|
||
|
||
**使用示例**
|
||
```
|
||
GET /api/rank/top?limit=10
|
||
```
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"_id": "674f1234567890abcdef",
|
||
"batch_time": "2025-10-17 15:30:00",
|
||
"mix_name": "热门合集1",
|
||
"video_url": "https://www.douyin.com/video/xxx",
|
||
"playcount": "1.2亿",
|
||
"play_vv": 120000000,
|
||
"request_id": "request_xxx",
|
||
"rank": 1,
|
||
"cover_image_url": "https://p3.douyinpic.com/xxx",
|
||
"cover_backup_urls": ["url1", "url2"]
|
||
}
|
||
],
|
||
"total": 10,
|
||
"update_time": "2025-10-17 15:30:00"
|
||
}
|
||
```
|
||
|
||
### 4. 搜索视频
|
||
|
||
**接口地址**
|
||
```
|
||
GET /api/rank/search
|
||
```
|
||
|
||
**功能描述**
|
||
根据关键词搜索视频合集
|
||
|
||
**请求参数**
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| q | string | 是 | - | 搜索关键词 |
|
||
| page | int | 否 | 1 | 页码 |
|
||
| limit | int | 否 | 10 | 每页数量 |
|
||
|
||
**使用示例**
|
||
```
|
||
GET /api/rank/search?q=关键词&page=1&limit=10
|
||
```
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"_id": "674f1234567890abcdef",
|
||
"batch_time": "2025-10-17 15:30:00",
|
||
"mix_name": "包含关键词的合集",
|
||
"video_url": "https://www.douyin.com/video/xxx",
|
||
"playcount": "1.2亿",
|
||
"play_vv": 120000000,
|
||
"request_id": "request_xxx",
|
||
"rank": 1,
|
||
"cover_image_url": "https://p3.douyinpic.com/xxx",
|
||
"cover_backup_urls": ["url1", "url2"]
|
||
}
|
||
],
|
||
"keyword": "关键词",
|
||
"pagination": {
|
||
"page": 1,
|
||
"limit": 10,
|
||
"total": 15,
|
||
"pages": 2,
|
||
"has_next": true,
|
||
"has_prev": false
|
||
},
|
||
"update_time": "2025-10-17 15:30:00"
|
||
}
|
||
```
|
||
|
||
### 5. 获取视频详情
|
||
|
||
**接口地址**
|
||
```
|
||
GET /api/rank/detail
|
||
```
|
||
|
||
**功能描述**
|
||
获取指定合集的详细信息
|
||
|
||
**请求参数**
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| id | string | 是 | - | 合集ID（支持ObjectId、合集名称、request_id） |
|
||
|
||
**使用示例**
|
||
```
|
||
GET /api/rank/detail?id=674f1234567890abcdef
|
||
```
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"_id": "674f1234567890abcdef",
|
||
"batch_time": "2025-10-17 15:30:00",
|
||
"mix_name": "合集名称",
|
||
"video_url": "https://www.douyin.com/video/xxx",
|
||
"playcount": "1.2亿",
|
||
"play_vv": 120000000,
|
||
"request_id": "request_xxx",
|
||
"rank": 1,
|
||
"cover_image_url": "https://p3.douyinpic.com/xxx",
|
||
"cover_backup_urls": ["url1", "url2"]
|
||
},
|
||
"update_time": "2025-10-17 15:30:00"
|
||
}
|
||
```
|
||
|
||
### 6. 获取统计信息
|
||
|
||
**接口地址**
|
||
```
|
||
GET /api/rank/stats
|
||
```
|
||
|
||
**功能描述**
|
||
获取系统统计信息
|
||
|
||
**请求参数**
|
||
无
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"total_mixes": 1000,
|
||
"total_playcount": 5000000000,
|
||
"avg_playcount": 5000000,
|
||
"max_playcount": 200000000,
|
||
"min_playcount": 1000,
|
||
"categories": [
|
||
{
|
||
"name": "超热门",
|
||
"min": 100000000,
|
||
"count": 5
|
||
},
|
||
{
|
||
"name": "热门",
|
||
"min": 50000000,
|
||
"max": 99999999,
|
||
"count": 20
|
||
},
|
||
{
|
||
"name": "中等",
|
||
"min": 10000000,
|
||
"max": 49999999,
|
||
"count": 150
|
||
},
|
||
{
|
||
"name": "一般",
|
||
"min": 0,
|
||
"max": 9999999,
|
||
"count": 825
|
||
}
|
||
],
|
||
"latest_update": "2025-10-17 15:30:00"
|
||
},
|
||
"update_time": "2025-10-17 15:30:00"
|
||
}
|
||
```
|
||
|
||
### 7. 健康检查
|
||
|
||
**接口地址**
|
||
```
|
||
GET /api/rank/health
|
||
```
|
||
|
||
**功能描述**
|
||
检查服务状态和数据库连接
|
||
|
||
**请求参数**
|
||
无
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "服务正常",
|
||
"data": {
|
||
"database": "连接正常",
|
||
"total_records": 1000,
|
||
"timestamp": "2025-10-17 15:30:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8. 获取榜单列表
|
||
|
||
**接口地址**
|
||
```
|
||
GET /api/rank/rankings
|
||
```
|
||
|
||
**功能描述**
|
||
获取榜单列表，支持按日期和类型查询，支持动态排序
|
||
|
||
**请求参数**
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| date | string | 否 | 最新日期 | 日期，格式：YYYY-MM-DD |
|
||
| type | string | 否 | - | 榜单类型：playcount(播放量榜) / growth(增长榜) / newcomer(新晋榜) |
|
||
| sort_by | string | 否 | default | 排序方式：default / play_vv_change / play_vv_change_rate / play_vv |
|
||
| sort_order | string | 否 | desc | 排序顺序：asc / desc |
|
||
| page | int | 否 | 1 | 页码 |
|
||
| limit | int | 否 | 50 | 每页数量 |
|
||
|
||
**使用示例**
|
||
```
|
||
# 获取最新日期的所有榜单
|
||
GET /api/rank/rankings
|
||
|
||
# 获取指定日期的播放量榜
|
||
GET /api/rank/rankings?date=2025-01-17&type=playcount
|
||
|
||
# 按播放量变化排序
|
||
GET /api/rank/rankings?sort_by=play_vv_change&sort_order=desc
|
||
|
||
# 分页获取增长榜
|
||
GET /api/rank/rankings?type=growth&page=1&limit=20
|
||
```
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取榜单成功",
|
||
"data": {
|
||
"rankings": [
|
||
{
|
||
"date": "2025-01-17",
|
||
"ranking_type": "playcount",
|
||
"ranking_name": "播放量榜",
|
||
"description": "按播放量排序的榜单",
|
||
"data": [
|
||
{
|
||
"_id": "674f1234567890abcdef",
|
||
"mix_name": "热门合集1",
|
||
"play_vv": 120000000,
|
||
"rank": 1,
|
||
"timeline_data": {
|
||
"play_vv_change": 5000000,
|
||
"play_vv_change_rate": 4.35
|
||
}
|
||
}
|
||
],
|
||
"total_count": 100,
|
||
"current_page_count": 20,
|
||
"generated_at": "2025-01-17 15:30:00",
|
||
"version": "1.0",
|
||
"sort_info": {
|
||
"sort_by": "default",
|
||
"sort_order": "desc"
|
||
}
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"limit": 50,
|
||
"sort_by": "default",
|
||
"sort_order": "desc"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 9. 获取可用榜单日期
|
||
|
||
**接口地址**
|
||
```
|
||
GET /api/rank/rankings/dates
|
||
```
|
||
|
||
**功能描述**
|
||
获取所有可用的榜单日期列表
|
||
|
||
**请求参数**
|
||
无
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取日期列表成功",
|
||
"data": {
|
||
"dates": [
|
||
"2025-01-17",
|
||
"2025-01-16",
|
||
"2025-01-15"
|
||
],
|
||
"total": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
### 10. 获取榜单类型
|
||
|
||
**接口地址**
|
||
```
|
||
GET /api/rank/rankings/types
|
||
```
|
||
|
||
**功能描述**
|
||
获取支持的榜单类型及其说明
|
||
|
||
**请求参数**
|
||
无
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取榜单类型成功",
|
||
"data": {
|
||
"types": [
|
||
{
|
||
"type": "playcount",
|
||
"description": "播放量榜 - 按播放量排序"
|
||
},
|
||
{
|
||
"type": "growth",
|
||
"description": "增长榜 - 播放量增长最快"
|
||
},
|
||
{
|
||
"type": "newcomer",
|
||
"description": "新晋榜 - 新上榜内容"
|
||
}
|
||
],
|
||
"total": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
### 11. 获取最新榜单
|
||
|
||
**接口地址**
|
||
```
|
||
GET /api/rank/rankings/latest
|
||
```
|
||
|
||
**功能描述**
|
||
获取最新日期的所有类型榜单（每个榜单只返回前20条数据）
|
||
|
||
**请求参数**
|
||
无
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取最新榜单成功",
|
||
"data": {
|
||
"date": "2025-01-17",
|
||
"rankings": [
|
||
{
|
||
"ranking_type": "playcount",
|
||
"ranking_name": "播放量榜",
|
||
"description": "按播放量排序的榜单",
|
||
"data": [
|
||
{
|
||
"_id": "674f1234567890abcdef",
|
||
"mix_name": "热门合集1",
|
||
"play_vv": 120000000,
|
||
"rank": 1
|
||
}
|
||
],
|
||
"total_count": 100,
|
||
"preview_count": 20
|
||
}
|
||
],
|
||
"total_types": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
### 12. 获取榜单统计
|
||
|
||
**接口地址**
|
||
```
|
||
GET /api/rank/rankings/stats
|
||
```
|
||
|
||
**功能描述**
|
||
获取榜单系统的统计信息
|
||
|
||
**请求参数**
|
||
无
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取榜单统计成功",
|
||
"data": {
|
||
"total_rankings": 150,
|
||
"total_dates": 30,
|
||
"total_types": 3,
|
||
"latest_date": "2025-01-17",
|
||
"earliest_date": "2024-12-18",
|
||
"date_range": "2024-12-18 至 2025-01-17"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
### 通用错误格式
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误描述",
|
||
"update_time": "2025-10-17 15:30:00"
|
||
}
|
||
```
|
||
|
||
### 常见错误
|
||
- `数据库连接失败`：MongoDB连接异常
|
||
- `未找到合集信息`：查询的合集不存在
|
||
- `请提供搜索关键词`：搜索接口缺少关键词参数
|
||
- `获取数据失败`：数据查询异常
|
||
|
||
## 小程序使用建议
|
||
|
||
### 1. 分页加载
|
||
推荐使用分页加载，避免一次性加载过多数据：
|
||
```javascript
|
||
// 小程序端示例
|
||
wx.request({
|
||
url: 'http://localhost:5000/api/rank/videos',
|
||
data: {
|
||
page: 1,
|
||
limit: 20,
|
||
sort: 'playcount'
|
||
},
|
||
success: (res) => {
|
||
if (res.data.success) {
|
||
this.setData({
|
||
videos: res.data.data,
|
||
hasNext: res.data.pagination.has_next
|
||
})
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
### 2. 搜索优化
|
||
- 使用防抖处理搜索请求
|
||
- 显示搜索进度和结果数量
|
||
- 提供搜索建议
|
||
|
||
### 3. 图片加载
|
||
- 优先使用 `cover_image_url`
|
||
- 备用 `cover_backup_urls` 作为备选
|
||
- 添加图片加载失败处理
|
||
|
||
### 4. 数据更新
|
||
- 注意 `update_time` 字段，判断数据新鲜度
|
||
- 合理使用缓存策略
|
||
- 定期检查服务健康状态
|
||
|
||
## 部署说明
|
||
|
||
### 启动服务
|
||
```bash
|
||
cd C:\Users\EDY\Desktop\rank_backend
|
||
python app.py
|
||
```
|
||
|
||
### 服务信息
|
||
- 端口：5000
|
||
- 数据库：MongoDB (localhost:27017)
|
||
- 数据更新：每晚24:00自动执行
|
||
|
||
### 注意事项
|
||
- 确保MongoDB服务已启动
|
||
- 确保网络连接正常
|
||
- 小程序端需要配置合法域名（生产环境）
|
||
|
||
---
|
||
|
||
**文档版本**：v3.0
|
||
**最后更新**：2025-01-17
|
||
**维护者**：系统自动生成
|
||
**更新内容**：新增榜单查询相关API接口，更新所有接口路径为/api/rank前缀 |