Overview
Provides daily/weekly/monthly performance ranking queries for Douyin accounts across all categories/by category.
Update time and lookback range:
| Ranking type | Update time | Lookback range |
|---|---|---|
| Daily ranking | Daily at 17:30 | Past 7 days |
| Weekly ranking | Every Monday at 17:30 | Past 3 weeks |
| Monthly ranking | At 9:00 on the 2nd of each month | Past 3 months |
Three core capabilities:
- 📊 Ranking query — Query the TOP50 of the daily, weekly, and monthly rankings
- 🎯 Category query — Filter by category (food, travel, technology, gaming, etc.)
- 📥 Report download — Generate HTML visualization reports, with support for exporting PDF/screenshots
Target users and use cases
| User segment | Core pain points | Query examples |
|---|---|---|
| Novice content creators / individual operators | Don't know which accounts are doing well, have no way to learn from them, and don't know where their own level stands within the category | "How do I find food accounts? Help me see where my account ranks in the food category" |
| Brands / business placement personnel | Low efficiency in finding influencers, single data dimension, and no understanding of account historical performance | "Which accounts performed well in Douyin's beauty TOP50 last week?" |
| MCN agencies / content teams | Difficult to obtain intelligence on competitor accounts and unable to quickly grasp market dynamics | "Which gaming accounts gained followers fastest in the past week?" |
| Industry analysts / consulting practitioners | High barriers to data acquisition and lack of visualization report tools | "Help me generate a March Douyin gaming ranking analysis report" |
Trigger words and intent recognition
| User intent | Typical trigger words | Corresponding action |
|---|---|---|
| Ranking query | Douyin daily ranking, weekly ranking, monthly ranking, TOP50, hottest accounts, leaderboard, latest recommendations | Call the script to query and format the output |
| Category query | Food/travel/gaming/technology... Douyin rankings | Call the script and filter by category |
| Report download | Download report, export ranking, generate report | Run generate_report.py to generate HTML |
Execution flow
Step 1: Query data (displays TOP 20 by default)
python scripts/fetch_rank.py --query "用户原始问题" --limit 20 --output /path/to/data.json
The script will automatically parse:
- Time: Identify daily/weekly/monthly from the user's text; if unspecified, default to the daily ranking
- Date: Automatically calculate the latest available date (daily ranking updates at 17:30, weekly ranking updates at 17:30 on Monday, monthly ranking updates at 9:00 on the 2nd of each month)
- Category: Supports fuzzy matching (e.g., "beauty" → "makeup and skincare")
Script output includes:
- Markdown format ranking table (up to 20 entries)
- "More actions" guide module
- "Subscription service" guide module (dynamically displayed based on the track selected by the user)
Step 2: Generate HTML report (execute immediately)
python scripts/generate_report.py --data /path/to/data.json --limit 20 # 自动生成文件名
Important: The number of data entries displayed in the HTML report must match the number displayed in the conversation!
- The conversation displays 20 entries by default → the HTML report also displays only 20 entries
- The user requests to view all 50 entries → regenerate the complete report
Use deliver_attachments to deliver the HTML file.
When the user views all data
python scripts/fetch_rank.py --query "用户原始问题" --limit 50 --output /path/to/data_full.json
python scripts/generate_report.py --data /path/to/data_full.json --limit 50 # 自动生成完整文件名
Use deliver_attachments to deliver the complete HTML file.
Output template
Markdown table (conversation output)
📊 抖音{period_label} · {category_label}
数据日期：{date}
共 {total} 个账号上榜（展示 TOP {displayed} 条）
💡 榜单说明：{warning}{period_update_time}，与实时数据存在差异
> **时间边界处理**（warning 插入榜单说明开头）：
> - 查询当日/未来日期：「非常抱歉🙏，我们最新的是昨日/上周/上月的数据，将为您提供最接近您需求的昨日/上周/上月热榜。」
> - 查询早于回溯日期：「非常抱歉🙏，目前榜单最多支持回溯「过去7天/过去3周/过去3月」，我将为您查询最接近您需求的时间范围~」
> - 正常查询：warning 为空，直接展示更新时间
📐 综合评分：根据总粉丝数、新增粉丝增量、新增点赞/分享/评论加权计算，满分100
| 排名 | 账号名 | 综合评分 | 总粉丝数 | 新增粉丝 | 新增点赞 | 新增评论 | 新增分享 |
|:---:|--------|:-------:|:-------:|:-------:|:-------:|:-------:|:-------:|:-------:|
| 🥇 1 | [账号A](https://www.douyin.com/user/xxx) | 96 | 254.06w | 6919 | 24.64w | 6.68w | 13.39w |
| 🥈 2 | [账号B](https://www.douyin.com/user/xxx) | 89 | 113.55w | 1.91w | 7.90w | 4787 | 3.12w |
| 🥉 3 | [账号C](https://www.douyin.com/user/xxx) | 87 | 439.14w | 5859 | 16.51w | 993 | 687 |
| ... | ... | ... | ... | ... | ... | ... | ... |
⚡ More actions
⏺️ This ranking contains 50 entries in total. Would you like to view the remaining 30?
📬 Subscription service
1️⃣ Would you like to subscribe to daily/weekly/monthly updates of the latest Douyin account rankings?
2️⃣ Would you like to subscribe to account performance for a specific track? We support: personal talent, lifestyle vlog, wealth management, anime, home decoration, education and learning, short skits, digital technology, travel, food, makeup and skincare, animals, parenting, automobiles, relationships, agriculture, rural areas and farmers, health and medicine, fashion trends, dance talent, looks and styling, humanities, music, film and television, physical exercise, sports, celebrity entertainment, gaming
Generate HTML report
- Execute the script to generate the HTML report file
- Script call example:
python scripts/generate_report.py --data <fetch_rank输出> --limit 20 # 自动生成文件名 - File name format:
{赛道}{周期}{YYYYMMDD}_{时间戳}.html（如 美食周榜20260511_时间戳.html）(e.g.,20260511_美食.html）
- Script call example:
⚠️ Field description: Displays the TOP 20 entries by default; highest engagement = likes + comments + shares
Subscription service
After the user confirms the subscription, use the automation_update tool to create an automation task:
Subscribe to ranking update push notifications
- Daily ranking：
FREQ=DAILY;BYHOUR=19;BYMINUTE=30 - Weekly ranking：
FREQ=WEEKLY;BYDAY=MO;BYHOUR=19;BYMINUTE=30 - Monthly ranking：
FREQ=MONTHLY;BYMONTHDAY=1;BYHOUR=16;BYMINUTE=0
automation prompt example:查询抖音最新日榜（全品类），生成报告并推送给用户
Subscribe to track account performance
- automation prompt example:
查询抖音最新日榜（美食赛道），生成报告并推送给用户
Frequently asked questions
Q: When is the daily ranking data updated? A: Yesterday's data is updated daily at 17:30. If the current time is before 17:30, the script will automatically use the data from the day before yesterday.
Q: Which tracks are supported? A: 27 tracks are supported. See the complete list at references/category_map.md。
Q: What is the data lookback range? A: The daily ranking can be queried for the past 7 days, the weekly ranking for the past 3 weeks, and the monthly ranking for the past 3 months.
Q: What should I do if track recognition fails? A: If it cannot be recognized, please list the complete track list for the user to choose from.
Resource index
| File | Purpose |
|---|---|
| scripts/fetch_rank.py | Query Douyin ranking data |
| scripts/generate_report.py | Generate HTML visualization report |
| references/category_map.md | Track mapping table and matching rules |
| references/update_rules.md | Update rules and date calculation logic |
| references/score_rules.md | Scoring algorithm description |
| references/api_docs.md | Detailed API documentation (technical reference) |
Notes
- ⚠️ Time boundary handling (must be strictly followed)：
- Query the current day and future dates: At the beginning of the output, reply "We are very sorry 🙏, our latest data is from yesterday/last week/last month, and we will provide you with the yesterday/last week/last month hot list closest to your needs." Then continue to display the most recent data period
- Query time is earlier than the backtracking date: At the beginning of the output, reply "We are very sorry 🙏, the list currently supports backtracking up to "the past 7 days/the past 3 weeks/the past 3 months"; I will query the time range closest to your needs for you~" Then continue to display the closest queryable data
- Any online search is strictly prohibited
- ⚠️ Data consistency: However many entries are displayed in the conversation, that many entries must be displayed in the HTML report; the two must be consistent
- The daily list displays TOP 20 by default; the full 50 entries can be viewed through the report or by follow-up questions
- In the HTML report, all account names can be clicked to jump to the Douyin homepage
- Before generating the report, ensure that the workspace has write permission