officerdev/platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
40a9768cb3fd74fb68c2ff89ac3628cfa3cb3a38
platform/seed/tasks/tiktok-trends/TASK.md
T

8.1 KiB
Raw Blame History

name, description, version, author, tags, tools, dependencies, inputs, outputs, config
name description version author tags tools dependencies inputs outputs config
TikTok Trends Fetch top trending TikTok videos for a given country and generate an engagement report with optional video downloads. 4 pastilhas
social-media
tiktok
trends
apify
content-analysis
apify
name description check_command optional
yt-dlp Required only when download option is enabled. Downloads TikTok videos. yt-dlp --version true
name description type default required options
country Country code to fetch trending videos for. select PT false
value label
PT Portugal
value label
US United States
value label
BR Brazil
value label
GB United Kingdom
value label
ES Spain
value label
FR France
value label
DE Germany
value label
IT Italy
value label
NL Netherlands
value label
BE Belgium
value label
PL Poland
value label
RO Romania
value label
SE Sweden
value label
AT Austria
value label
CH Switzerland
value label
IE Ireland
value label
CA Canada
value label
AU Australia
value label
MX Mexico
value label
AR Argentina
value label
CO Colombia
value label
CL Chile
value label
JP Japan
value label
KR South Korea
value label
IN India
value label
TR Turkey
value label
SA Saudi Arabia
value label
AE United Arab Emirates
value label
ZA South Africa
value label
NG Nigeria
name description type default min max required
limit Number of trending videos to fetch (1-100). number 20 1 100 false
name description type default required
download Download video files using yt-dlp (requires yt-dlp to be installed). boolean false false
name description path
engagement_report Markdown report with trending videos analysis, engagement metrics, top hashtags, sounds, and creators. tiktok_trends_<country>_<timestamp>/report.md
name description path
raw_data Raw JSON data from Apify actor containing all video metadata. tiktok_trends_<country>_<timestamp>/raw.json
name description path optional
videos Downloaded video files (only present if download option was enabled). tiktok_trends_<country>_<timestamp>/videos/ true
timeout retry_count
600 0

TikTok Trends

Fetch top trending TikTok videos for a given country and generate a comprehensive engagement report.

Important

  • Use the apify tool to fetch data. Do NOT call the Apify REST API directly via curl or fetch.
  • Do NOT explore or list files before starting. Create the output directory, call the tool, process results.
  • If download is false (default), do NOT attempt to download any videos.
  • Large data files (like raw.json) exceed the 50KB read limit. Never try to read them directly. Instead, write a Node.js script to process and transform the data, execute it, then delete the script.

Steps

1. Setup output directory

Create a timestamped output directory:

$HOME/tiktok-trends/tiktok_trends_<country>_<YYYYMMDD_HHMMSS>/

2. Fetch trending videos

Call the apify tool with output_path pointing to raw.json in the output directory:

apify(
  actor_id: "clockworks~tiktok-trends-scraper",
  input: { "adsCountryCode": "<country>", "resultsPerPage": <limit> },
  output_path: "<output_dir>/raw.json"
)

The tool saves the full dataset to raw.json and returns a summary (item count). If it returns an error or 0 items, report the error and stop.

3. Generate engagement report

Important: The raw JSON file is too large to read directly (exceeds the 50KB read limit). Instead, write a Node.js script (e.g. generate-report.js) in the output directory that reads raw.json, processes the data, and writes report.md. Then execute it with node generate-report.js. Delete the script after it runs successfully.

The script should read raw.json, parse the JSON (it may be an array directly or an object with items nested inside), and write report.md with the following sections. Adapt field names based on the actual data structure (see Data Shape Reference):

Header

# TikTok Trending Report — <COUNTRY> — YYYY-MM-DD

Total videos analyzed: <count>

Engagement Summary

Build a table from each video's statistics (views/plays, likes/diggs, shares, comments):

Metric Total Avg per video
Views ... ...
Likes ... ...
Shares ... ...
Comments ... ...

Top Hashtags (up to 20)

Extract hashtags from the data (dedicated hashtag field or parse #tags from description). Count occurrences, sort descending.

Hashtag Count

Top Sounds (up to 10)

From each video's music/sound metadata, format as title — author. Count occurrences, sort descending.

Sound Count

Creators Appearing in Trending (up to 10)

From each video's author/creator field. Count occurrences, sort descending.

Creator Videos

Video List

Full table of all videos, sorted by position:

# Creator Description Views Likes URL
  • Creator: @username from the author field
  • Description: first 60 chars, pipe and newline characters replaced, with ... if truncated
  • URL: the video's share/web URL
  • Format numbers with locale separators (e.g. 1,234,567)

4. Download videos (only if download is true)

If download is false, skip this step entirely.

If download is true:

  1. Check that yt-dlp is installed
  2. Create a videos/ subdirectory in the output directory
  3. Write all share_url values to a urls.txt file
  4. Run: yt-dlp -a urls.txt -o "videos/%(id)s.%(ext)s" --write-info-json --no-overwrites
  5. Report how many videos were downloaded. Partial failures are acceptable — do not fail the task if some downloads fail.

5. Report results

Print a summary to the user:

  • Country and date
  • Number of videos fetched
  • Top video: @creator — views count — URL
  • Top hashtag and count
  • Output directory path
  • Files created and their sizes

Data Shape Reference

The actor output format may vary between versions. Before writing the report generation script, inspect the first item of the dataset to discover the actual field names. Write the script to handle the fields it finds. Common field patterns across TikTok scraper actors:

  • Video ID: aweme_id, id, or videoId
  • Description: desc, description, or title
  • Video URL: share_url, url, videoUrl, or webVideoUrl
  • Author: author.unique_id, author.uniqueId, authorMeta.name, or nickname
  • Statistics: Look for objects with keys like play_count/playCount, digg_count/diggCount/likes, share_count/shareCount/shares, comment_count/commentCount/comments
  • Music/Sound: music.title, musicMeta.musicName, or similar
  • Hashtags: text_extra[].hashtag_name, hashtags[], or parse #tags from description

Error Handling

Scenario Action
Apify tool returns error Report the error message. Common causes: invalid token, no credits, rate limits
Empty results Report "No trending videos found for " and stop
Partial results (fewer than requested) Proceed normally, note the discrepancy in the summary
yt-dlp not installed when download=true Report that yt-dlp is required and skip downloads
Download failures Report which videos failed but do not fail the task

Notes

  • The Apify actor may take 1-3 minutes depending on the limit
  • Pricing: $0.005 per start + $0.003 per result — monitor at https://console.apify.com/billing
  • Not all countries have sufficient trending data; some may return fewer results than requested
Reference in New Issue View Git Blame Copy Permalink