YouTube Channel Discovery & Enrichment

Discover YouTube channels through web-based search with advanced filtering options and optional YouTube Data API v3 enrichment for detailed channel statistics.

🎯 Features

• Web-Based Discovery: Scrapes YouTube search results using Playwright (no API quota needed for discovery)
• Quota-Free Handle Resolution: Resolves channel handles (like @eatnlive or non-ASCII Korean handles) using lightweight web requests, saving expensive YouTube Search API quota (100 units per query) and only consuming 1 unit per channel for enrichment.
• Real-Time Output: Pushes channel data to the Apify dataset in real-time (query-by-query) so you don't have to wait for the entire scraping run to complete.
• Advanced Filters: Filter results by upload date, content type, and sort order
• API Enrichment: Optional YouTube Data API v3 integration for subscriber counts, video stats, and metadata
• Multiple Queries: Process multiple search queries in a single run
• Smart Deduplication: Automatically removes duplicate channels across queries
• High Capacity: Up to 1000 channels per query
• Error Resilience: Query-level error isolation - one failed query won't stop others

📊 Use Cases

• Influencer Research: Find fitness, beauty, gaming, or tech channels by hashtags
• Competitor Analysis: Discover channels in your niche sorted by view count or relevance
• Trend Monitoring: Track newly uploaded content with time-based filters
• Lead Generation: Build lists of potential collaboration partners
• Market Research: Analyze channel distribution across topics

🚀 Quick Start

Basic Channel Search

{
  "searchQueries": ["#fitness", "#yoga"],
  "filters": {
    "type": "channel",
    "sort": "relevance"
  },
  "maxResultsPerQuery": 50,
  "useYoutubeApi": true
}

Recent Video Creators

{
  "searchQueries": ["home workout"],
  "filters": {
    "type": "video",
    "uploadDate": "week",
    "sort": "view_count"
  },
  "maxResultsPerQuery": 100,
  "useYoutubeApi": false
}

📥 Input Configuration

Required Fields

• searchQueries (array): List of search queries
  • Examples: ["#fitness", "yoga tutorial", "@channelname"]
  • Min: 1, Max: 100 queries

Optional Fields

• filters (object): YouTube search filters

  • uploadDate: "any", "hour", "today", "week", "month", "year"
  • type: "video", "channel", "playlist"
  • sort: "relevance", "upload_date", "view_count", "rating"

• maxResultsPerQuery (integer): Maximum channels per query

  • Default: 100
  • Range: 1 to 1000

• useYoutubeApi (boolean): Enable API enrichment

  • Default: true
  • Set to true to get subscriber counts, video stats, and metadata
  • Note: Requires setting YOUTUBE_API_KEY in environment variables or providing youtubeApiKey in the input. If not provided, it will fallback to web-scraping only.

📤 Output Data

Basic Discovery (API enrichment disabled)

{
  "channelId": "UCxxxxxxxxxxxx",
  "channelHandle": "@channelname",
  "channelUrl": "https://www.youtube.com/@channelname",
  "source": "video",
  "scrapedAt": "2026-01-13T02:00:22.489Z",
  "_searchQuery": "#fitness",
  "_timestamp": "2026-01-13T02:00:53.021Z"
}

With API Enrichment (useYoutubeApi: true)

{
  "channelId": "UCxxxxxxxxxxxx",
  "channelHandle": "@channelname",
  "channelUrl": "https://www.youtube.com/@channelname",
  "title": "Fitness Channel Name",
  "description": "Welcome to our fitness journey...",
  "customUrl": "@channelname",
  "publishedAt": "2020-03-15T10:30:00Z",
  "thumbnails": {
    "default": { "url": "...", "width": 88, "height": 88 },
    "medium": { "url": "...", "width": 240, "height": 240 },
    "high": { "url": "...", "width": 800, "height": 800 }
  },
  "subscriberCount": 125000,
  "videoCount": 387,
  "viewCount": 15680000,
  "_enriched": true,
  "_enrichedAt": "2026-01-13T02:00:23.683Z",
  "_searchQuery": "#fitness",
  "_timestamp": "2026-01-13T02:00:53.021Z"
}

💡 YouTube API Enrichment

Enrich discovered channels with rich statistics by setting useYoutubeApi: true. To use API enrichment, either set the YOUTUBE_API_KEY environment variable in your Apify Actor settings, or provide the key via the youtubeApiKey input parameter.

When enabled, the Actor will retrieve:

• ✅ Subscriber counts
• ✅ Video counts
• ✅ Total view counts
• ✅ Channel descriptions
• ✅ Thumbnails
• ✅ Published dates

⚡ Quota-Optimized Handle Resolution

Previously, converting scraped handles (e.g. @channelname) to channel IDs used the YouTube Search API, which consumes a massive 100 quota units per call (exhausting default limits very quickly).

This Actor now uses direct HTML parsing via lightweight web requests to resolve channel IDs. This uses 0 API quota units for handle resolution, meaning the API quota is only consumed for detail enrichment (1 quota unit per channel). This allows you to process up to 10,000 channels per day on a standard free API quota!

Performance Note

• Without API enrichment: ~20-50 channels per 10 seconds (fastest)
• With API enrichment: Adds a fast web-lookup and a 1-quota API call per channel (highly optimized, runs in concurrent batches)

⚙️ Advanced Configuration

High-Volume Collection

{
  "searchQueries": ["fitness motivation"],
  "filters": {
    "type": "channel",
    "sort": "view_count"
  },
  "maxResultsPerQuery": 1000,
  "useYoutubeApi": true
}

Note: Large collections may take 5-10 minutes and consume more API quota.

Time-Sensitive Discovery

{
  "searchQueries": ["#trending", "#shorts"],
  "filters": {
    "type": "video",
    "uploadDate": "today",
    "sort": "upload_date"
  },
  "maxResultsPerQuery": 30,
  "useYoutubeApi": true
}

Use case: Monitor newly uploaded content for real-time trending analysis.

Fast Discovery Without API

{
  "searchQueries": ["workout", "exercise"],
  "filters": {
    "type": "channel"
  },
  "maxResultsPerQuery": 200,
  "useYoutubeApi": false
}

Benefits: Fastest execution, no API quota consumption, basic channel info only.

🎯 Filter Combinations

Use Case	Type	Upload Date	Sort
Popular channels	channel	any	view_count
New creators	channel	week/month	upload_date
Trending videos	video	today/week	view_count
Relevant content	video/channel	any	relevance
Highly rated	video	any	rating

📊 Performance

• Discovery speed: ~20-50 channels per 10 seconds
• API enrichment: ~50 channels per API call
• Average run time:
  • 50 channels without API: ~15 seconds
  • 50 channels with API: ~20 seconds
  • 500 channels with API: ~2 minutes
  • 1000 channels with API: ~5-10 minutes

🚨 Error Handling

Query-Level Isolation

If one query fails, others continue processing:

{
  "summary": {
    "totalQueries": 3,
    "totalChannelsCollected": 150,
    "apiEnriched": 150
  },
  "results": [
    {
      "searchQuery": "#fitness",
      "channels": [...],
      "channelCount": 100
    },
    {
      "searchQuery": "#invalid",
      "channels": [],
      "error": {
        "message": "No results found",
        "code": "NO_RESULTS"
      }
    },
    {
      "searchQuery": "#yoga",
      "channels": [...],
      "channelCount": 50
    }
  ]
}

Common Issues

No channels found

• Try different search queries
• Remove or change filters
• Use type: "video" instead of "channel" (more results)

API quota exhausted

• Set useYoutubeApi: false temporarily
• Enrichment will automatically stop if quota is exhausted
• Actor will continue with basic data (no subscriber counts)

📖 Integration Examples

Node.js

const { ApifyClient } = require('apify-client');

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const input = {
  searchQueries: ['#fitness', '#workout'],
  filters: { type: 'channel', sort: 'view_count' },
  maxResultsPerQuery: 100,
  useYoutubeApi: true,  // API key is pre-configured!
};

const run = await client.actor('YOUR_ACTOR_ID').call(input);
const { items } = await client.dataset(run.defaultDatasetId).listItems();

console.log(`Found ${items.length} channels`);
items.forEach(channel => {
  console.log(`${channel.title} - ${channel.subscriberCount} subscribers`);
});

Python

from apify_client import ApifyClient

client = ApifyClient('YOUR_APIFY_TOKEN')

run_input = {
    'searchQueries': ['#fitness', '#workout'],
    'filters': {'type': 'channel', 'sort': 'view_count'},
    'maxResultsPerQuery': 100,
    'useYoutubeApi': True,  # API key is pre-configured!
}

run = client.actor('YOUR_ACTOR_ID').call(run_input=run_input)
items = client.dataset(run['defaultDatasetId']).list_items().items

print(f"Found {len(items)} channels")
for channel in items:
    print(f"{channel['title']} - {channel['subscriberCount']} subscribers")

cURL

curl -X POST https://api.apify.com/v2/acts/YOUR_ACTOR_ID/runs \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchQueries": ["#fitness"],
    "filters": {"type": "channel", "sort": "view_count"},
    "maxResultsPerQuery": 100,
    "useYoutubeApi": true
  }'

# Note: YouTube API is pre-configured, no key needed!

🆘 Support

• GitHub Issues: Report bugs or request features
• Documentation: See DEPLOYMENT_GUIDE.md and TEST_SCENARIOS.md in repository
• Apify Forum: Get help from community

📝 Changelog

Version 1.1.0 (2026-06-07)

• ⚡ Quota-Free Handle Resolution: Implemented HTML-based channel ID resolution for handles to bypass expensive Search API limits (saving 100 quota units per channel).
• 🔄 Real-Time Dataset Pushing: Pushes discovered and enriched channels query-by-query in real-time so that results appear on the console immediately.
• 🔧 Double-Encoding Bug Fix: Fixed a bug where non-ASCII handles (like Korean) failed to resolve due to double URL encoding.
• 📂 Apify Schema Alignment: Standardized .actor/input_schema.json directory layout.

Version 1.0.0 (2026-01-13)

• ✅ Initial release
• ✅ Web-based channel discovery with Playwright
• ✅ YouTube Data API v3 enrichment
• ✅ Advanced search filters (upload date, type, sort)
• ✅ Multi-query support with deduplication
• ✅ Query-level error isolation
• ✅ Environment variable support for API keys
• ✅ Up to 1000 results per query

📄 License

MIT License - See repository for details

🙏 Credits

Built with:

• Apify SDK - Actor framework
• Playwright - Web automation
• YouTube Data API v3 - Channel enrichment

---

Ready to discover YouTube channels? Click "Try it" and start exploring! 🚀