Qyir/rank_backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
rank_backend/docs/API接口文档.md

10 KiB
Raw Blame History

抖音播放量数据API接口文档

概述

本API服务提供抖音播放量数据的查询、搜索、统计等功能，专为小程序优化设计。

基础信息

  • 服务地址：http://localhost:5001
  • 数据源：MongoDB数据库
  • 数据更新：每日14:23自动更新
  • 响应格式：JSON

通用响应格式

所有API接口都遵循以下响应格式：

{
  "success": true,
  "data": {},
  "message": "操作成功",
  "update_time": "2025-10-17 15:30:00"
}

字段说明

  • success: 请求是否成功
  • data: 返回的数据内容
  • message: 操作结果描述
  • update_time: 数据更新时间

数据模型

合集数据项

{
  "_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"]
}

分页信息

{
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

API接口列表

1. 首页信息

接口地址

GET /

功能描述 获取API服务的基本信息和所有可用接口列表

请求参数 无

响应示例

{
  "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": "获取榜单列表"
    },
    "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)

排序说明

  • playcount: 按当前播放量从高到低排序
  • growth: 按播放量增长差值从大到小排序
    • 计算公式：增长值 = 结束日期播放量 - 开始日期播放量
    • 只显示增长为正数的合集
    • 排序规则：增长差值越大，排名越靠前

使用示例

# 按播放量排序（当前播放量从高到低）
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

响应示例

播放量排序响应：

{
  "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"
}

增长榜排序响应（包含额外的growth字段）：

{
  "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,
      "growth": 5000000,
      "start_date": "2025-10-16",
      "end_date": "2025-10-17",
      "cover_image_url": "https://p3.douyinpic.com/xxx",
      "cover_backup_urls": ["url1", "url2"]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3,
    "has_next": true,
    "has_prev": false
  },
  "sort_by": "growth",
  "date_range": {
    "start_date": "2025-10-16",
    "end_date": "2025-10-17"
  },
  "update_time": "2025-10-17 15:30:00"
}

3. 获取热门榜单

接口地址

GET /api/rank/top

功能描述 获取热门视频榜单（按播放量排序）

请求参数

参数名 类型 必填 默认值 说明
limit int 否 10 返回数量

使用示例

GET /api/rank/top?limit=10

响应示例

{
  "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

响应示例

{
  "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

响应示例

{
  "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

功能描述 获取系统统计信息

请求参数 无

响应示例

{
  "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

功能描述 检查服务状态和数据库连接

请求参数 无

响应示例

{
  "success": true,
  "message": "服务正常",
  "data": {
    "database": "连接正常",
    "total_records": 1000,
    "timestamp": "2025-10-17 15:30:00"
  }
}

错误处理

通用错误格式

{
  "success": false,
  "message": "错误描述",
  "update_time": "2025-10-17 15:30:00"
}

常见错误

  • 数据库连接失败：MongoDB连接异常
  • 未找到合集信息：查询的合集不存在
  • 请提供搜索关键词：搜索接口缺少关键词参数
  • 获取数据失败：数据查询异常

小程序使用建议

1. 分页加载

推荐使用分页加载，避免一次性加载过多数据：

// 小程序端示例
wx.request({
  url: 'http://localhost:5001/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 字段，判断数据新鲜度
  • 合理使用缓存策略
  • 定期检查服务健康状态

部署说明

启动服务

cd C:\Users\EDY\Desktop\rank_backend
python app.py

服务信息

  • 端口：5000
  • 数据库：MongoDB (localhost:27017)
  • 数据更新：每晚24:00自动执行

注意事项

  • 确保MongoDB服务已启动
  • 确保网络连接正常
  • 小程序端需要配置合法域名（生产环境）

文档版本：v2.0 最后更新：2025-10-17维护者：系统自动生成