Youtube Trending Scraper

A powerful Apify Actor that scrapes YouTube trending videos from any country with support for multiple content types. This actor intelligently handles proxy management and data extraction to ensure reliable collection of comprehensive video metadata.

Why Choose Us?

• Smart Proxy Management: Automatically uses proxies by default (YouTube often blocks Apify IPs) with intelligent fallback system
• Multi-Country Support: Scrape trending videos from 100+ countries worldwide
• Content Type Filtering: Filter by gaming, music, movies, sports, or entertainment
• Flexible Video Limits: Control how many videos to scrape per country (default: 10, set to 0 for unlimited)
• Comprehensive Data Extraction: Extracts complete video metadata including channel handles, thumbnails, and engagement metrics
• Robust Error Handling: Automatic retries, proxy fallback, and validation to ensure data quality
• Production Ready: Built with Apify SDK best practices for reliability and scalability

Key Features

✅ Intelligent Proxy System

• Uses proxy by default (recommended for YouTube scraping)
• Automatically detects incomplete HTML responses
• Falls back from datacenter → residential proxy if blocked
• Retries up to 3 times with residential proxy
• Sticks with working proxy for all remaining requests

✅ Comprehensive Data Extraction

• Video title, description, and full metadata
• View counts, likes, and comments
• Channel information with handles (@username), subscriber counts, and badges
• Thumbnails with dimensions
• Categories, keywords, and tags
• Publish dates, upload dates, and video duration
• Live stream detection
• Family-safe content flags

✅ Flexible Input Options

• Country codes (BD, US, IN, etc.) - most common use case
• YouTube URLs
• Channel usernames
• Keywords for trending searches

✅ Multiple Content Types

• Gaming videos
• Music content
• Movies and entertainment
• Sports highlights
• General trending content

✅ Video Limit Control

• Set maximum videos per input (default: 10)
• Set to 0 for unlimited (scrape all available trending videos)
• Perfect for sampling or comprehensive data collection

✅ Data Quality Validation

• Validates extracted data before returning
• Detects and retries on incomplete HTML responses
• Ensures meaningful data (title, views, channel info)
• Detailed logging for debugging

Input

Input Schema

{
  "startUrls": [
    "BD",
    "US",
    "IN"
  ],
  "contentType": "gaming",
  "maxVideosPerInput": 10,
  "sortOrder": "relevance",
  "maxComments": 0,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}

Input Parameters

Field	Type	Required	Description
startUrls	Array	Yes	List of YouTube URLs, usernames, keywords, or country codes (e.g., "BD", "US", "IN") for trending videos. Enter one item per line.
contentType	String	No	Type of content to scrape. Options: music, gaming, movies, sports, entertainment. Default: gaming
maxVideosPerInput	Integer	No	Maximum number of videos to scrape per input (country code). Set to 0 for unlimited (get all available trending videos). Default: 10
sortOrder	String	No	Sort order for results. Options: relevance, date, viewCount, rating. Default: relevance
maxComments	Integer	No	Maximum number of comments to retrieve (reserved for future use). Default: 0
proxyConfiguration	Object	No	Apify proxy configuration. By default, proxy is enabled (recommended for YouTube scraping). Set useApifyProxy: false to disable. The actor will automatically fallback to proxies if blocked.

Input Examples

Example 1: Scrape 10 Gaming Videos from Bangladesh (Default)

{
  "startUrls": ["BD"],
  "contentType": "gaming",
  "maxVideosPerInput": 10
}

Example 2: Scrape 50 Videos Per Country from Multiple Countries

{
  "startUrls": [
    "US",
    "GB",
    "CA"
  ],
  "contentType": "music",
  "maxVideosPerInput": 50
}

Example 3: Get ALL Available Trending Videos (Unlimited)

{
  "startUrls": ["IN"],
  "contentType": "sports",
  "maxVideosPerInput": 0
}

Example 4: Custom Proxy Configuration

{
  "startUrls": ["JP"],
  "contentType": "gaming",
  "maxVideosPerInput": 25,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}

Example 5: Disable Proxy (Not Recommended)

{
  "startUrls": ["US"],
  "contentType": "gaming",
  "maxVideosPerInput": 10,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}

Output

Output Format

The actor outputs an array of video objects, each containing comprehensive video metadata:

[
  {
    "type": "video",
    "id": "2dmCaK0qslM",
    "title": "Video Title Here",
    "status": "OK",
    "url": "https://www.youtube.com/watch?v=2dmCaK0qslM",
    "description": "Video description text...",
    "duration": 8940,
    "views": "1487513",
    "likes": "124690",
    "comments": "1K",
    "channel": {
      "id": "UCE-8FgcXvnAsb2EG1FizSyg",
      "name": "Channel Name",
      "handle": "@channelname",
      "url": "https://www.youtube.com/@channelname",
      "subscriberCount": "4.81M subscribers",
      "thumbnails": [],
      "badges": ["Verified"]
    },
    "keywords": [
      "keyword1",
      "keyword2",
      "keyword3"
    ],
    "isRatingsAllowed": true,
    "isLive": false,
    "isFamilySafe": true,
    "category": "Gaming",
    "isPrivate": false,
    "isExclusive": false,
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi/2dmCaK0qslM/maxresdefault.jpg",
        "width": 168,
        "height": 94
      }
    ],
    "embedUrl": "https://www.youtube.com/embed/2dmCaK0qslM",
    "isEmbeddable": true,
    "isUnlisted": false,
    "publishDate": "2025-10-31T07:06:17-07:00",
    "relativeDate": null,
    "uploadDate": "2025-10-31T07:06:17-07:00"
  }
]

Output Fields

Field	Type	Description
type	String	Always "video"
id	String	YouTube video ID
title	String	Video title
status	String	Status ("OK" or "UNKNOWN")
url	String	Full YouTube video URL
description	String	Video description
duration	Integer	Video duration in seconds
views	String	View count (formatted string)
likes	String	Like count (formatted string)
comments	String	Comment count (formatted string)
channel	Object	Channel information object
channel.id	String	Channel ID
channel.name	String	Channel name
channel.handle	String	Channel handle (e.g., "@channelname") or null
channel.url	String	Channel URL or null
channel.subscriberCount	String	Subscriber count (formatted string)
channel.thumbnails	Array	Channel thumbnails (currently empty)
channel.badges	Array	Channel badges (e.g., ["Verified"])
keywords	Array	Video keywords/tags
category	String	Video category (Gaming, Music, etc.)
thumbnails	Array	Video thumbnail URLs with dimensions
publishDate	String	ISO 8601 publish date
uploadDate	String	ISO 8601 upload date
isLive	Boolean	Whether video is a live stream
isFamilySafe	Boolean	Family-friendly content flag
isRatingsAllowed	Boolean	Whether ratings are allowed
isPrivate	Boolean	Whether video is private (always false for trending)
isExclusive	Boolean	Whether video is exclusive
isUnlisted	Boolean	Whether video is unlisted
isEmbeddable	Boolean	Whether video can be embedded
embedUrl	String	Embed URL for the video

🚀 How to Use the Actor (via Apify Console)

1. Log in at https://console.apify.com and navigate to Actors

2. Find the actor (youtube-trending-scraper) and click on it

3. Configure inputs:

   • Add country codes, URLs, usernames, or keywords in the startUrls field (one per line)
   • Select content type (gaming, music, movies, etc.)
   • Set maxVideosPerInput (default: 10, set to 0 for unlimited)
   • Optionally configure proxy settings (proxy is enabled by default)
   • Set sort order if needed

4. Run the actor by clicking the "Start" button

5. Monitor logs in real-time to see:

   • Progress updates every 10 videos
   • HTML extraction status (length, JSON structures detected)
   • Proxy switches and fallback events
   • Video processing status with extracted fields
   • Data validation warnings
   • Final statistics summary

6. Access results in the OUTPUT tab:

   • View data in the table format
   • Export to JSON or CSV
   • Download individual video data

7. Export results:

   • Click "Export" button
   • Choose format (JSON, CSV, Excel)
   • Download your data

Best Use Cases

• Content Research: Discover trending topics and videos in specific regions
• Market Analysis: Track trending content across different countries and categories
• Competitor Monitoring: Monitor trending videos in your niche
• Trend Discovery: Find viral content and emerging trends
• Data Collection: Build datasets of trending videos for analysis
• Content Strategy: Understand what content performs well in different regions
• SEO Research: Identify trending keywords and topics
• Social Media Marketing: Find trending content to share or analyze
• Influencer Research: Discover trending channels and creators
• Regional Content Analysis: Compare trending content across countries

How It Works

Proxy Management

The actor uses a smart proxy system:

1. Default Behavior: Proxy is enabled by default (recommended) because YouTube often blocks Apify IPs
2. Detection: Monitors HTML response quality (length, JSON structures)
3. Validation: Checks if extracted data is meaningful (title, views, channel info)
4. Fallback: If incomplete data detected, automatically tries proxy fallback
5. Persistence: Once a proxy works, uses it for all remaining requests

Data Extraction

The actor extracts data from multiple sources with priority:

1. Basic HTML Extraction: Meta tags, regex patterns (highest priority)
2. Player Response: YouTube's ytInitialPlayerResponse JSON
3. Initial Data: YouTube's ytInitialData JSON

Data is merged with priority: basic > player > initial_data, ensuring the most reliable data sources take precedence.

Quality Assurance

• Validates HTML contains expected YouTube JSON structures
• Checks for meaningful data (title, views, channel) before returning
• Retries with proxy if incomplete data detected
• Logs extraction quality for debugging

Frequently Asked Questions

Why does the actor use proxy by default?

YouTube frequently blocks requests from Apify's IP addresses. Using a proxy by default ensures higher success rates and better data quality. You can disable it by setting useApifyProxy: false in proxy configuration.

How does the proxy fallback work?

The actor intelligently detects when YouTube returns incomplete HTML or blocks requests:

1. Monitors HTML response quality (length, JSON structures)
2. Validates extracted data completeness
3. If incomplete data detected, automatically falls back to datacenter proxy (SHADER)
4. If still blocked, switches to residential proxy (RESIDENTIAL)
5. Retries up to 3 times with residential proxy
6. Once a proxy works, uses that proxy for all remaining requests

What is maxVideosPerInput?

This parameter controls how many videos to scrape per country/input:

• Default: 10 - Scrapes first 10 trending videos per country
• Set to 0 - Scrapes ALL available trending videos (unlimited)
• Any positive number - Limits to that many videos per country

Example: If you set maxVideosPerInput: 25 and provide 3 countries, you'll get up to 75 videos total (25 per country).

What countries are supported?

The actor supports 100+ countries including:

• United States (US)
• Bangladesh (BD)
• India (IN)
• United Kingdom (GB)
• Canada (CA)
• Japan (JP)
• Germany (DE)
• France (FR)
• Australia (AU)
• And many more...

Use the 2-letter ISO country code in the startUrls field.

Can I scrape specific channels or videos?

Currently, the actor focuses on trending videos. For specific channels or videos, you can:

• Use country codes to get trending videos from that region
• Filter by content type to narrow down results
• Future updates may include direct channel/video scraping

How many videos can I scrape?

The number of videos depends on:

• maxVideosPerInput setting (default: 10, set to 0 for unlimited)
• Number of countries/inputs provided
• Available trending videos for each country/content type
• Time of day (trending lists update frequently)

Example: With maxVideosPerInput: 10 and 3 countries, you'll get up to 30 videos.

What happens if a request fails?

The actor includes robust error handling:

• Automatic retries (up to 3 attempts per video)
• Proxy fallback on blocks or incomplete data
• Data validation before returning results
• Graceful failure handling (continues with other videos)
• Detailed error logging with extraction status

Is the data real-time?

Yes! The actor scrapes current trending videos at the time of execution. YouTube's trending lists update frequently throughout the day.

Can I use my own proxies?

Yes! Configure custom proxies through the proxyConfiguration input field. The actor will use your proxy settings and still fallback if needed.

How long does scraping take?

Scraping time depends on:

• Number of videos to process
• maxVideosPerInput setting
• Network speed
• Proxy performance
• YouTube response times

Typically:

• 10 videos: 1-2 minutes
• 50 videos: 5-8 minutes
• 100 videos: 10-15 minutes

What if I get incomplete data?

The actor validates data quality:

• Checks for title, views, and channel information
• Detects incomplete HTML responses
• Automatically retries with proxy if needed
• Logs warnings for incomplete data
• Returns data even if incomplete after max retries (with warning)

Check the logs for extraction status and proxy fallback events.

Support and Feedback

• Issues: Report bugs or request features through Apify platform
• Questions: Check the FAQ section above or contact support
• Feedback: We welcome suggestions for improvements

Cautions

⚠️ Important Legal and Ethical Considerations

• Public Data Only: This actor collects only publicly available data from YouTube
• Rate Limiting: The actor includes delays and rate limiting to respect YouTube's servers
• Terms of Service: Ensure your use case complies with YouTube's Terms of Service
• Data Privacy: Be mindful of data privacy regulations (GDPR, CCPA, etc.) when processing personal information
• Responsible Use: Use the actor responsibly and avoid overwhelming YouTube's servers
• No Private Content: The actor cannot access private, unlisted, or password-protected content
• Proxy Usage: Using proxies may incur additional costs depending on your Apify plan

Disclaimer: The end user is responsible for ensuring legal compliance with all applicable laws, including but not limited to:

• Spam laws
• Privacy regulations
• Data protection laws
• YouTube Terms of Service
• Copyright laws

---

Built with ❤️ using Apify SDK