# Changelog of YouTube Trend Spotter (`sleek_waveform/youtube-trend-spotter`) Actor

- **URL**: https://apify.com/sleek\_waveform/youtube-trend-spotter/changelog.md
- **Full Actor documentation**: https://apify.com/sleek\_waveform/youtube-trend-spotter.md

## Changelog

All notable changes to the YouTube Trend Spotter Actor will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

***

### \[1.1] - 2026-03-09

#### Added

- **Channel Analytics Enrichment** — Each video now includes `channel_subscribers`, `channel_total_views`, and `channel_video_count`. Uses the YouTube Channels API endpoint, batched (50 per request) and deduplicated across videos for quota efficiency
- **Upload Timing Analysis** — Analyzes upload timestamps to find the best posting days and hours. Shows day-of-week and hour-of-day distributions with average view and engagement correlation. Provides a human-readable recommendation (e.g. "Videos posted on Wednesday at 2:00 PM tend to get 45% more views"). Requires 5+ videos with valid dates
- **Tag Trend Analysis** — Aggregates and analyzes tags across all extracted videos. Shows top 20 tags by frequency with average views and engagement. Identifies "rising tags" (correlated with ≥75th percentile velocity, 2+ appearances) and "recommended tags" (weighted composite: 30% frequency × 40% views × 30% engagement). Summary stats include unique tag count and average tags per video
- **Enhanced Computed Fields** — Five new per-video fields: `engagement_rate` ((likes + comments) / views), `views_per_day` (views / age with 0.1-day floor), `days_since_upload`, `like_to_view_ratio`, `comment_to_view_ratio`. All handle edge cases (zero views, missing dates)
- **Custom Scoring Weights** — New input parameters `velocityWeight`, `engagementWeight`, `momentumWeight` (default 40/30/30) let users customize the trend scoring algorithm. Values are auto-normalized to sum to 100%
- **Expanded Regions** — From 10 to 34 supported countries: added ES, IT, NL, SE, NO, DK, FI, PL, RU, KR, TW, TH, ID, PH, TR, AR, CO, CL, EG, SA, AE, NG, KE

#### Fixed

- **Dockerfile** — All 13 required Python files now included in the Docker image (previously missing `demo_data.py`, `trend_store.py`, `trend_tracker.py`, `main.py`, `__init__.py`)

***

### \[1.0] - 2026-03-08

#### Added

- Initial public release of YouTube Trend Spotter on Apify Store
- **Trend Score (0–100)** — composite ranking score per video
- **Velocity Score** — views-per-day scoring, normalised 0–100 across keyword results
- **Engagement Score** — (likes + comments) / views, normalised 0–100
- **Momentum Score** — percentage view growth since previous run (50 = neutral/first run)
- **Niche Opportunity Score** — keyword-level saturation analysis with human-readable verdict
- Multi-keyword support — analyse multiple keywords in a single run; all results in one dataset
- Historical tracking via persistent Key-Value Store (`youtube-trend-history`) for cross-run momentum
- HTML trend report saved per keyword to default KVS under key `trend_report_{keyword_slug}`
- `TREND_SUMMARY` JSON record in default KVS with keyword-level insights and top videos
- 3 dataset views in Apify Console: Overview (with thumbnails), Trend Scores, Full Details
- `thumbnail_url` rendered as image in Overview view; `youtube_url` rendered as clickable link
- Input schema with 7 fields: `keywords`, `youtubeApiKey`, `maxResults`, `region`, `sortBy`, `enableHistory`, `outputHtmlReport`
- Output schema defining 3 outputs: scored videos dataset, trend summary KVS record, HTML reports
- Full store README with real example output, all 27 output fields documented, API integration guide, FAQ
- Apify Store categories: Social media, Marketing
- Pricing: $0.50 per run

#### Technical

- Python 3.12 on `apify/actor-python:3.12` base image
- YouTube Data API v3 — no scraping, fully ToS compliant
- Default KVS for per-run outputs (HTML reports, TREND\_SUMMARY); named KVS `youtube-trend-history` for persistent momentum snapshots
- `engagement_rate` stored as percentage (e.g. `4.046` = 4.046%)
- HTML report key format: `trend_report_{slug}` where slug = `re.sub(r"[^a-z0-9]+", "_", keyword.lower()).strip("_")[:50]`

#### Fixed

- `environmentVariables` in `actor.json` changed from array `[]` to object `{}` (Apify schema requirement)
- `storages.dataset` changed from inline object to string path `"./DATASET_SCHEMA.json"` (Apify schema requirement)
- `version` format changed from `1.0.0` to `1.0` (Apify MAJOR.MINOR requirement)
- Removed invalid `fields` key from dataset schema — only `views` is accepted by Apify validator
- README delivery via `"readme": "../README.md"` in `actor.json` (REST API does not accept readme field directly)