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

14 KiB
Raw Blame History

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

概述

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

基础信息

  • 服务地址：http://localhost:5000
  • 数据源：MongoDB数据库
  • 数据更新：每晚24:00自动更新
  • 响应格式：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": "获取榜单列表",
      "/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

响应示例

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

响应示例

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

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

响应示例

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

功能描述 获取所有可用的榜单日期列表

请求参数 无

响应示例

{
  "success": true,
  "message": "获取日期列表成功",
  "data": {
    "dates": [
      "2025-01-17",
      "2025-01-16",
      "2025-01-15"
    ],
    "total": 3
  }
}

10. 获取榜单类型

接口地址

GET /api/rank/rankings/types

功能描述 获取支持的榜单类型及其说明

请求参数 无

响应示例

{
  "success": true,
  "message": "获取榜单类型成功",
  "data": {
    "types": [
      {
        "type": "playcount",
        "description": "播放量榜 - 按播放量排序"
      },
      {
        "type": "growth",
        "description": "增长榜 - 播放量增长最快"
      },
      {
        "type": "newcomer",
        "description": "新晋榜 - 新上榜内容"
      }
    ],
    "total": 3
  }
}

11. 获取最新榜单

接口地址

GET /api/rank/rankings/latest

功能描述 获取最新日期的所有类型榜单（每个榜单只返回前20条数据）

请求参数 无

响应示例

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

功能描述 获取榜单系统的统计信息

请求参数 无

响应示例

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

错误处理

通用错误格式

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

常见错误

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

小程序使用建议

1. 分页加载

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

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

部署说明

启动服务

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前缀