🎯 Meta Brand Ad Scraper

A powerful Apify actor that scrapes detailed ad information from Meta's Ad Library for brands, pages, and keyword searches.

✨ Features

• Multiple Search Types:

  • Page-based search (by Facebook Page ID)
  • Keyword exact phrase search
  • Keyword unordered search
  • Regular keyword search

• Comprehensive Data Collection:

  • 📊 Performance metrics (spend, impressions, reach)
  • 📝 Ad content (body, titles, links, media)
  • 🎯 Distribution data (platforms, countries)
  • 📅 Timing information (start/end dates)
  • 🔍 Page metadata (categories, entity type)
  • 📈 Additional metrics (AAA eligibility, reshare status)

• Smart Features:

  • Automatic rate limiting
  • Retry mechanism with exponential backoff
  • Detailed logging
  • Progress tracking
  • Error handling

🚀 Quick Start

Input Format

{
    "adLibraryUrl": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=ALL&view_all_page_id=123456789",
    "maxResults": 200
}

Input Parameters

Parameter	Type	Required	Description
adLibraryUrl	string	Yes	Meta Ad Library URL to scrape
maxResults	integer	No	Maximum number of ads to scrape (default: 100)

Output Structure

{
    "summary": {
        "totalAds": 100,
        "searchType": "page",
        "identifier": "123456789",
        "adLibraryUrl": "https://www.facebook.com/ads/library/...",
        "urlParams": {
            "status": "ALL",
            "country": "ALL",
            "media_type": "all",
            "ad_type": "all"
        },
        "totalSpend": 5000.00,
        "totalImpressions": 100000,
        "uniquePlatforms": ["Facebook", "Instagram"]
    },
    "data": {
        "ads": [
            {
                "metadata": { ... },
                "ad_content": { ... },
                "timing": { ... },
                "performance": { ... },
                "distribution": { ... },
                "status": { ... },
                "additional_info": { ... }
            }
        ]
    }
}

🛠️ Development

Prerequisites

• Python 3.9+
• Apify CLI
• Docker (for containerized development)

Local Setup

1. Install Dependencies

$pip install -r requirements.txt

2. Run Tests

$python -m src.test_scraper

3. Run Locally

$apify run

Deployment

Deploy to Apify platform:

$apify push

🔧 Configuration

URL Parameters

The actor supports various URL parameters:

Parameter	Description	Default
active_status	Ad status filter	ALL
country	Target country	ALL
media_type	Media type filter	all
ad_type	Ad type filter	all
is_targeted_country	Country targeting	false

⚡ Performance

• Rate Limiting: Automatic handling of Meta's rate limits
• Retry Logic: Up to 3 retries with exponential backoff
• Error Handling: Comprehensive error catching and reporting
• Progress Tracking: Real-time progress updates

📝 License

MIT License - feel free to use this actor for your projects!

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Support

For support, please open an issue in the repository or contact the maintainers.