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