Qyir be44334960 解决封面图片过期情况，存入TOS中media/rank/目录中

热播总榜选择日期之后永久显示图片。

2025-10-20 18:47:49 +08:00

19 KiB

Raw Blame History

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

概述

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

基础信息

服务地址：http://localhost:5001
数据源：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"
}

文章数据项

{
  "_id": "68f3ad112ba085e5d676537e",
  "title": "文章标题",
  "author_id": "test_user_1",
  "cover_image": "封面图片URL",
  "status": "draft",
  "summary": "文章摘要",
  "created_at": "2025-10-18 15:06:57",
  "likes": [],
  "likes_count": 0
}

文章详情数据项

{
  "_id": "68f3ad112ba085e5d676537e",
  "title": "文章标题",
  "content": "文章完整内容",
  "author_id": "test_user_1",
  "cover_image": "封面图片URL",
  "status": "draft",
  "summary": "文章摘要",
  "created_at": "2025-10-18 15:06:57",
  "likes": [],
  "likes_count": 0
}

分页信息

{
  "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": "获取榜单统计",
      "/api/article/list": "获取文章列表 (支持分页和排序)",
      "/api/article/search": "搜索文章",
      "/api/article/detail": "获取文章详情",
      "/api/article/stats": "获取文章统计信息",
      "/api/article/health": "文章服务健康检查"
    },
    "features": [
      "分页支持",
      "多种排序方式",
      "搜索功能",
      "详情查看",
      "统计分析",
      "榜单查询",
      "动态排序",
      "小程序优化",
      "文章管理",
      "内容搜索"
    ]
  }
}

2. 获取视频列表

接口地址

GET /api/rank/videos

功能描述 获取分页的视频合集列表，支持多种排序方式

请求参数

参数名	类型	必填	默认值	说明
page	int	否	1	页码
limit	int	否	20	每页数量
sort	string	否	playcount	排序方式：playcount(播放量) / growth(增长量)
start_date	string	否	昨天	增长计算开始日期(格式: YYYY-MM-DD)，仅在sort=growth时有效
end_date	string	否	今天	增长计算结束日期(格式: YYYY-MM-DD)，仅在sort=growth时有效

数据源说明

sort=playcount：从Rankings_list集合动态查询当日播放量数据
sort=growth：从Ranking_storage集合读取预计算的增长排名数据（由定时任务生成）

使用示例

# 按播放量排序
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",
      "growth": 5000000,
      "growth_rate": 4.35
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5,
    "has_next": true,
    "has_prev": false
  },
  "sort_by": "growth",
  "data_source": "ranking_storage",
  "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"
    }
  ],
  "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"
    }
  ],
  "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"
  },
  "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. 获取文章列表

接口地址

GET /api/article/list

功能描述 获取文章列表，支持分页和排序

请求参数

参数名	类型	必填	默认值	说明
page	int	否	1	页码
limit	int	否	10	每页数量
sort	string	否	created_at	排序字段
order	string	否	desc	排序方向 (asc/desc)

响应示例

{
  "success": true,
  "data": [
    {
      "_id": "68f3ad112ba085e5d676537e",
      "title": "对于ai影视化的思考",
      "author_id": "test_user_1",
      "cover_image": "",
      "status": "draft",
      "summary": "AI影视化的发展趋势和思考",
      "created_at": "2025-10-18 15:06:57",
      "likes": [],
      "likes_count": 0
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_items": 1,
    "has_next": false,
    "has_prev": false
  },
  "message": "获取文章列表成功",
  "update_time": "2025-10-18 15:06:57"
}

2. 搜索文章

接口地址

GET /api/article/search

功能描述 根据关键词搜索文章

请求参数

参数名	类型	必填	默认值	说明
q	string	是	-	搜索关键词
page	int	否	1	页码
limit	int	否	10	每页数量

响应示例

{
  "success": true,
  "data": [
    {
      "_id": "68f3ad112ba085e5d676537e",
      "title": "对于ai影视化的思考",
      "author_id": "test_user_1",
      "cover_image": "",
      "status": "draft",
      "summary": "AI影视化的发展趋势和思考",
      "created_at": "2025-10-18 15:06:57",
      "likes": [],
      "likes_count": 0
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_items": 1,
    "has_next": false,
    "has_prev": false
  },
  "message": "搜索文章成功",
  "update_time": "2025-10-18 15:06:57"
}

3. 获取文章详情

接口地址

GET /api/article/detail

功能描述 根据文章ID获取文章详细信息

请求参数

参数名	类型	必填	默认值	说明
id	string	是	-	文章ID

响应示例

{
  "success": true,
  "data": {
    "_id": "68f3ad112ba085e5d676537e",
    "title": "对于ai影视化的思考",
    "content": "# AI影视化的思考\n\n在2025年，AI技术在影视行业的应用...",
    "author_id": "test_user_1",
    "cover_image": "",
    "status": "draft",
    "summary": "AI影视化的发展趋势和思考",
    "created_at": "2025-10-18 15:06:57",
    "likes": [],
    "likes_count": 0
  },
  "message": "获取文章详情成功",
  "update_time": "2025-10-18 15:06:57"
}

4. 获取文章统计信息

接口地址

GET /api/article/stats

功能描述 获取文章相关的统计信息

请求参数 无

响应示例

{
  "success": true,
  "data": {
    "total_articles": 1,
    "latest_update": "2025-10-18 15:06:57",
    "status_count": {
      "draft": 1,
      "published": 0,
      "archived": 0
    }
  },
  "message": "获取文章统计成功",
  "update_time": "2025-10-18 15:06:57"
}

5. 文章服务健康检查

接口地址

GET /api/article/health

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

请求参数 无

响应示例

{
  "success": true,
  "data": {
    "status": "服务正常",
    "database": "连接正常",
    "article_count": 1
  },
  "message": "文章服务健康检查通过",
  "update_time": "2025-10-18 15:06:57"
}

小程序使用建议

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 作为封面图片
添加图片加载失败处理

4. 数据更新

注意 update_time 字段，判断数据新鲜度
合理使用缓存策略
定期检查服务健康状态

5. 文章管理

推荐的文章列表加载方式：

// 小程序端示例 - 文章列表
wx.request({
  url: 'http://localhost:5001/api/article/list',
  data: {
    page: 1,
    limit: 10,
    sort: 'created_at',
    order: 'desc'
  },
  success: (res) => {
    if (res.data.success) {
      this.setData({
        articles: res.data.data,
        hasNext: res.data.pagination.has_next
      })
    }
  }
})

文章搜索示例：

// 小程序端示例 - 文章搜索
wx.request({
  url: 'http://localhost:5001/api/article/search',
  data: {
    q: 'AI',
    page: 1,
    limit: 5
  },
  success: (res) => {
    if (res.data.success) {
      this.setData({
        searchResults: res.data.data
      })
    }
  }
})

部署说明

启动服务

cd /Users/binghuixiong/剧变AI/rank_backend
python3 app.py

服务信息

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

注意事项

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

文档版本：v4.1
最后更新：2025-01-18
维护者：系统自动生成
更新内容：优化增长排名接口数据源策略，现在专门使用Ranking_storage预计算数据，提升查询性能和数据一致性

19 KiB Raw Blame History Unescape Escape

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

概述

通用响应格式

数据模型

合集数据项

文章数据项

文章详情数据项

分页信息

API接口列表

1. 首页信息

2. 获取视频列表

3. 获取热门榜单

4. 搜索视频

5. 获取视频详情

6. 获取统计信息

7. 健康检查

8. 获取榜单列表

9. 获取可用榜单日期

10. 获取榜单类型

11. 获取最新榜单

12. 获取榜单统计

错误处理

通用错误格式

常见错误

文章管理接口

1. 获取文章列表

2. 搜索文章

3. 获取文章详情

4. 获取文章统计信息

5. 文章服务健康检查

小程序使用建议

1. 分页加载

2. 搜索优化

3. 图片加载

4. 数据更新

5. 文章管理

部署说明

启动服务

服务信息

注意事项

19 KiB

Raw Blame History