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)
• Advanced Filters: 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: false
  • Set to true to get subscriber counts, video counts, and detailed metadata
  • Note: YouTube API is pre-configured. No API key needed!

📤 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

Good news: YouTube Data API v3 is pre-configured for this Actor!

Simply set useYoutubeApi: true in your input to get:

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

No API key required from you - it's already set up and ready to use!

Performance Note

• Without API enrichment: ~20-50 channels per 10 seconds (fastest)
• With API enrichment: ~50 channels per API call batch (slightly slower but much richer data)

⚙️ 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.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! 🚀