Qyir/rank_backend

Fork 0

Qyir 8d4369ecef 优化修改文件

2025-10-17 11:28:39 +08:00

6.7 KiB

Raw Blame History

小程序抖音播放量数据API文档

概述

抖音短剧播放量数据API，专为小程序优化，支持分页、搜索、增长分析等功能。

服务地址: http://localhost:5001 启动命令: cd backend && python miniprogram_api_server.py

接口列表

1. 健康检查

GET /api/health

检查服务器和数据库状态

2. 视频列表

GET /api/videos

参数:

page: 页码（默认1）
limit: 每页数量（默认20，最大50）
sort: 排序方式
- playcount: 按总播放量排序
- growth: 按增长排序
- time: 按时间排序
start_date: 开始日期（增长排序用，格式：2025-10-16）
end_date: 结束日期（增长排序用，格式：2025-10-17）

示例:

# 总播放量排序
/api/videos?page=1&limit=10&sort=playcount

# 增长排序（昨天到今天）
/api/videos?page=1&limit=10&sort=growth

# 自定义日期增长排序
/api/videos?page=1&limit=10&sort=growth&start_date=2025-10-16&end_date=2025-10-17

3. 热门榜单

GET /api/top

limit: 返回数量（默认10，最大50）

4. 搜索视频

GET /api/search

q: 搜索关键词
page: 页码
limit: 每页数量

5. 视频详情

GET /api/detail

id: 视频ID

数据字段说明

视频数据字段

_id: 视频唯一ID
mix_name: 短剧名称
playcount: 播放量文本（如"2.1亿"）
play_vv: 播放量数值
video_url: 抖音合集链接
rank: 排名
batch_time: 数据采集时间
aweme_ids: 视频ID数组
cover_image_url: 封面图片
cover_backup_urls: 备用封面图片
request_id: 请求ID

增长排序特有字段

growth: 播放量增长值
start_date: 开始日期
end_date: 结束日期

响应格式

所有接口返回格式：

{
  "success": true/false,
  "data": [...],
  "message": "错误信息（仅当success为false时）"
}

视频列表接口额外包含：

pagination: 分页信息
sort_by: 排序方式
date_range: 日期范围（仅增长排序）
update_time: 更新时间

📱 小程序集成示例

微信小程序示例

// 获取视频列表
wx.request({
  url: 'http://localhost:5001/api/videos',
  data: {
    page: 1,
    limit: 10,
    sort: 'playcount'
  },
  success: function(res) {
    if (res.data.success) {
      const videos = res.data.data;
      videos.forEach(video => {
        console.log(`${video.mix_name}: ${video.playcount}`);
        console.log(`封面: ${video.cover_image_url}`);
        console.log(`链接: ${video.video_url}`);
        console.log(`视频数量: ${video.aweme_ids.length}`);
      });
      console.log('分页信息:', res.data.pagination);
    }
  }
});

// 搜索视频
wx.request({
  url: 'http://localhost:5001/api/search',
  data: {
    q: '奶团',
    page: 1,
    limit: 5
  },
  success: function(res) {
    if (res.data.success) {
      const results = res.data.data;
      results.forEach(video => {
        console.log(`找到: ${video.mix_name}`);
        console.log(`播放量: ${video.playcount}`);
        console.log(`数值播放量: ${video.play_vv}`);
      });
    }
  }
});

// 获取热门榜单
wx.request({
  url: 'http://localhost:5001/api/top',
  data: {
    limit: 10
  },
  success: function(res) {
    if (res.data.success) {
      console.log('热门榜单:', res.data.data);
    }
  }
});

uni-app示例

// 封装API请求
const API_BASE = 'http://localhost:5001';

// 获取视频列表
export function getVideoList(page = 1, limit = 20, sort = 'playcount') {
  return uni.request({
    url: `${API_BASE}/api/videos`,
    data: { page, limit, sort }
  });
}

// 搜索视频
export function searchVideos(keyword, page = 1, limit = 10) {
  return uni.request({
    url: `${API_BASE}/api/search`,
    data: { q: keyword, page, limit }
  });
}

// 获取视频详情
export function getVideoDetail(id) {
  return uni.request({
    url: `${API_BASE}/api/detail`,
    data: { id }
  });
}

// 使用示例
getVideoList(1, 10).then(([err, res]) => {
  if (!err && res.data.success) {
    console.log('视频列表:', res.data.data);
  }
});

🎯 数据字段说明

视频合集字段

_id: 合集唯一标识符（MongoDB ObjectId）
mix_name: 合集名称
playcount: 播放量文本（如"2.1亿"）
play_vv: 播放量数值
video_url: 合集链接
rank: 排名
batch_time: 批次时间
aweme_ids: 视频ID数组
cover_image_url: 封面图片URL
cover_backup_urls: 备用封面图片URL数组
request_id: 请求ID

分页信息字段

page: 当前页码
limit: 每页数量
total: 总记录数
pages: 总页数
has_next: 是否有下一页
has_prev: 是否有上一页

🔧 技术特性

1. 小程序优化

轻量级响应: 精简数据结构，减少传输量
分页支持: 避免一次性加载大量数据
搜索功能: 支持关键词模糊搜索
错误处理: 统一的错误响应格式

2. 性能优化

数据缓存: MongoDB查询优化
分页限制: 防止过大的数据请求
连接池: 数据库连接复用
日志记录: 完整的请求日志

3. 安全特性

参数验证: 输入参数安全检查
CORS支持: 跨域请求支持
错误隐藏: 不暴露内部错误信息

📊 测试结果

最新测试结果（100%通过率）：

✅ API首页: 正常
✅ 健康检查: 数据库连接正常，35条记录
✅ 视频列表: 分页功能正常
✅ 热门榜单: 排序功能正常
✅ 搜索功能: 关键词搜索正常
✅ 视频详情: 详情获取正常
✅ 统计信息: 数据统计正常

🚀 部署建议

开发环境

# 启动API服务器
python scripts/miniprogram_api_server.py

# 运行测试
python scripts/test_miniprogram_api.py

生产环境

# 使用Gunicorn部署
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5001 scripts.miniprogram_api_server:app

# 使用Nginx反向代理
# 配置SSL证书支持HTTPS

📝 更新日志

v2.0 (2025-10-16)

🎉 全新的小程序优化API
✨ 添加分页和搜索功能
🔧 优化数据结构和响应格式
📊 增加统计信息接口
🧪 完整的测试覆盖

与v1.0的主要区别

更好的分页: 支持灵活的分页参数
搜索功能: 关键词模糊搜索
详情接口: 单独的视频详情查看
统计分析: 数据统计和分类
小程序优化: 专为小程序设计的数据格式

🤝 技术支持

如有问题，请检查：

MongoDB服务是否正常运行
API服务器是否启动成功
网络连接是否正常
参数格式是否正确

测试工具会自动生成详细的测试报告，保存在 api_test_report.json 文件中。

6.7 KiB Raw Blame History Unescape Escape