overseas-trending-search

Overseas Cross-Platform Trending Content Search

Enter any keyword (Chinese/English) to search popular content across X / TikTok / YouTube with one click, taking the Top N per platform by likes/views/comments/publish time (default 5), and output a unified field list: platform, title, author, views, likes, comments, publish time, link.

All API requests carry the ChinaTrendingDigest-RedSkill identifier. You need to configure an API Key first, passed via the environment variable REDFOX_API_KEY or the --api-key parameter. The architecture uses a platform adapter pattern: a new platform (such as YouTube) only requires adding an adapter file, with zero changes to the main flow.

Use Cases

Scenario	Example
Daily trending tracking	Run "AI" once a day to grasp the hottest content of the day across the three platforms
Cross-platform comparison	Compare the popularity and content format differences of the same keyword across X / TikTok / YouTube
Topic/event tracking	Search "new energy,EV" to track cross-platform spread of a specific topic
Competitor/public opinion monitoring	Search a brand or product name to see real discussions and viral feedback from overseas users
Material and inspiration collection	Export CSV for a topic library and data analysis
Account content mining	On the TikTok side, drill down by author work list (userAwemeList) is supported

Usage

# 基础用法：单关键词（默认最近 24 小时，按播放数降序）
python3 "$SKILL_PATH/scripts/digest.py" "AI"

# 中文关键词 / 多关键词（英文逗号分隔）
python3 "$SKILL_PATH/scripts/digest.py" "人工智能,AI agent"

# 放宽时间窗口到最近 3 天（TikTok 热门多为历史内容，建议放宽）
python3 "$SKILL_PATH/scripts/digest.py" "AI" --days 3

# 只跑指定平台
python3 "$SKILL_PATH/scripts/digest.py" "AI" --platforms tiktok

# 按发布时间排序
python3 "$SKILL_PATH/scripts/digest.py" "AI" --sort time

# 按点赞数排序 / 调整每平台返回条数（默认 5）
python3 "$SKILL_PATH/scripts/digest.py" "AI" --sort likes --top 10

# 仅导出 CSV / 不自动打开浏览器
python3 "$SKILL_PATH/scripts/digest.py" "AI" --csv-only --no-open

CSV / HTML are saved by default in ~/Downloads/QoderOverseasTrending/。

Result Display Specification

When showing results to users,mustinclude the following fields:

Field	Description
Platform	X / TikTok / YouTube (with platform brand colors)
Title	Tweet/video copy summary, showing only the first 20 characters (hover in the HTML table to see the full text)
Author	Author nickname
Views	Abbreviated in thousands/tens of thousands (e.g. 47.3w), displayed after the author
Likes	Abbreviated in thousands/tens of thousands (e.g. 62.9w)
Comments	Same as above
Publish time	`YYYY-MM-DD HH:mm`
Link	Clickable to jump to the original post

Platform status must be clearly indicated before the results: when a platform has an upstream failure, degrade gracefully and note it in the report without affecting results from other platforms.

Count constraint: each platform returns at most --top N items (default 5), sorted descending within the platform group by the --sort metric; both the terminal and HTML display results grouped by platform.
Language priority layering: for Chinese keywords, Chinese content is prioritized within each platform group; for English keywords, English content is prioritized; when there is insufficient Chinese/English content within a group, other languages are used as a fallback; within each layer, results are still sorted descending by the sorting metric.
The HTML report supports switching between "card / table" dual views; the table view includes all fields: likes/comments/views/shares.
YouTube like/comment counts are filled in one by one via the videoDetail detail API (by default, all 20 search results are fully covered; localized count strings have been parsed into integers).

Parameter Description

Parameter	Description	Default Value
`keywords`	Keywords, Chinese or English, multiple words separated by English commas (positional argument)	—
`--days`	Time window: last N days (0=unlimited)	`1`
`--platforms`	Platform list:`x,tiktok,youtube` any combination	`x,tiktok,youtube`
`--sort`	Sort:`views` / `likes` / `comments` / `time`	`views`
`--top`	Maximum number of results returned per platform (0=unlimited)	`5`
`--output-dir`	Output directory	`~/Downloads/QoderOverseasTrending`
`--api-key`	Specify RedFox API Key	—
`--csv-only`	Generate only CSV, not HTML	—
`--no-open`	Do not automatically open the browser	—

API Key Configuration

Choose any one way to configure your personal Key:

Method	Command
Environment variable (recommended)	`export REDFOX_API_KEY=ak_你的密钥`
Command-line argument	`--api-key ak_你的密钥`
Configuration file	`echo '{"api_key":"ak_你的密钥"}' > ~/.qoder/apis/redfox.json`

Registration address:redfox.hk

Architecture Description

scripts/
├── digest.py            # 主编排器：关键词×平台采集 → 时间过滤 → 排序 → 输出
├── config.py            # RedFox 网关地址、密钥加载（三级优先级）
└── sources/             # 平台适配器（新增平台只需加一个文件并在 __init__ 登记）
    ├── base.py          # BaseSource：统一 schema + 递增延迟重试
    ├── x_source.py      # X：search/tweetDetail/tweetComments
    ├── tiktok_source.py # TikTok：searchVideo（一条请求自带点赞/评论数）
    └── youtube_source.py# YouTube：searchVideo 列表 + videoDetail 补点赞/评论

Unified record schema:platform / title / url / author / likes / comments / views / publish_ts / publish_time / keyword / shares。

Platform API status (tested 2026-07)

Platform	API	Status
X	search / tweetDetail / tweetComments	✅ All available; search requires `searchType`(Top/Latest), missing it will falsely report 3203
TikTok	searchVideo / awemeDetail / userAwemeList	✅ All available, searchVideo comes with full interaction data
YouTube	searchVideo / videoDetail / videoComments	✅ All available; searchVideo returns view count and relative publish time, likes/comments are filled in by videoDetail (Top 10)

Dependencies

pip3 install requests

FAQ

Q: X search returns a 3203 error? A: The X search API's searchType is a required parameter (Top Top / Latest Latest), when missing RedFox returns a misleading 3203 "X capability call failed". This skill has this parameter built in; in addition, calling tweetDetail with an expired/invalid tweetId will also report 3203.

Q: Does TikTok search need to call the detail API to supplement data? A: No. searchVideo returns likes/comments/views/shares and publish time in a single request, which is sufficient for daily summaries.

Q: Where does YouTube's like/comment data come from? A: The searchVideo list API only returns view count; likes/comments need to be filled in one by one via videoDetail. By default the skill fully supplements details for all 20 search results (youtube_source.py in detail_top can be lowered to save credits), so all videos have real like/comment counts; still being 0 means the video truly has no likes/comments. The YouTube platform itself does not disclose share counts, so the share column is always 0.

Q: How many results are returned per platform? A: By default, each platform takes the Top 5 by the sort metric (likes/views/comments/publish time),--top N is adjustable (0=unlimited). Each platform is grouped independently and sorted in descending order within the group, without affecting each other.

Q: Why can't I see TikTok content with the default parameters? A: TikTok searchVideo returns popular videos, whose publish times are mostly several days or even months ago, and the default --days 1(last 24 hours) will filter them all out. To see TikTok popular content, add --days 0 or --days 7; when filtering, the terminal will indicate the number of excluded items per platform.

Q: When searching Chinese keywords, why is Japanese content on X ranked behind? A: Built-in language priority layering for skills: when the keyword is Chinese, within each platform group, Chinese content is shown first, followed by English, with other languages such as Japanese as a fallback (solving ambiguity issues like "南海" matching the Japanese "南海電鉄"); the same applies to English keywords, which prioritize English content. Language identification is based on the title character set (Han characters/kana/Hangul/Latin letters), with no third-party dependencies.

Q: Want to run it on a daily schedule? A: You can have the AI register a scheduled task to automatically run digest.py every day and generate a report.