Facebook Ads Library Scraper

A powerful, automated CLI tool for scraping Facebook's Ad Library with infinite scroll support and intelligent ad detection.

🚀 Quick Start

Install globally (Recommended)

npm install -g facebook-ads-scraper

# Run the scraper
facebook-ads-scraper --query "health" --country US

# Or use the shorter alias
ads-scraper -q "covid" -c BR -m 5

Install locally

npm install facebook-ads-scraper

# Run with npx
npx facebook-ads-scraper --query "health"

Features

• 🔍 Smart Infinite Scrolling: Automatically detects when Facebook loads more content
• 📊 Flexible Filtering: Collect ads with minimum copy counts
• 💾 Auto-Saving: Progress saved every N ads automatically
• 🎯 Multiple Formats: Export to JSON, CSV, or Excel
• 🐳 Docker Ready: Easy deployment anywhere
• 🔄 Crash Recovery: Handles Facebook errors and browser crashes
• 📈 Progress Tracking: Real-time statistics and progress updates
• 🌍 Global CLI: Install once, use anywhere

Usage

Command Line Options

facebook-ads-scraper [OPTIONS]

Options:
  -q, --query <text>        Search query (required)
  -c, --country <code>      Country code (default: US)
  -m, --min-ads <number>    Minimum ad copies (default: 2)
  -d, --delay <ms>          Scroll delay in milliseconds (default: 2000)
  --headless <bool>         Run browser in headless mode (default: true)
  -o, --output <path>       Output directory (default: ./data)
  -s, --save-interval <num> Save progress every N ads (default: 10)
  -f, --format <type>       Output format: json, csv, excel (default: json)
  -h, --help               Show help message

Interactive Mode

# Start interactive setup
facebook-ads-scraper --interactive

# Or just run without arguments
facebook-ads-scraper

Examples

# Basic usage
facebook-ads-scraper --query "health" --country US

# Advanced usage
facebook-ads-scraper -q "covid" -c BR -m 5 --headless false

# Export to Excel
facebook-ads-scraper -q "election" -f excel

# Custom output directory
facebook-ads-scraper -q "pharma" -o ./my-data

Environment Variables

SEARCH_QUERY="health"        # Default search query
COUNTRY="US"                 # Default country code
MIN_AD_COUNT=2              # Default minimum ad count
SCROLL_DELAY=2000           # Default scroll delay
HEADLESS=true               # Default headless mode
OUTPUT_FORMAT=json          # Default output format
OUTPUT_DIR=./data           # Default output directory
SAVE_INTERVAL=10            # Default save interval

Output Formats

JSON (Default)

{
  "exportDate": "2025-07-28T17:33:26.274Z",
  "sessionId": "1753723589333",
  "totalAds": 13,
  "ads": [
    {
      "id": "lib_1429109191464340",
      "timestamp": "2025-07-28T17:27:05.775Z",
      "adCount": 2,
      "libraryId": "1429109191464340",
      "adLink": "https://www.facebook.com/ads/library/?id=1429109191464340&country=US",
      "text": "...",
      "images": ["..."],
      "advertiser": "..."
    }
  ]
}

CSV

• Comma-separated values for Excel import
• Includes all ad metadata

Excel

• Professional XLSX format
• Multiple worksheets (Summary + Ads Data)
• Auto-sized columns

Configuration

Search Queries

• Health: "health", "medical", "pharma"
• Politics: "election", "candidate", "campaign"
• Products: "brand", "product", "service"

Countries

• US: United States
• BR: Brazil
• GB: United Kingdom
• CA: Canada
• And many more...

Country Parameter in Ad Links

The scraper now includes the country parameter in generated ad links to maintain search context:

• Ad links automatically include the country parameter used in the search
• Example: https://www.facebook.com/ads/library/?id=123456789012345&country=BR
• This ensures users are taken to the correct country-specific version when clicking ad links
• Works with both CLI scraper and browser extension

Minimum Ad Counts

• 1: All ads (most comprehensive)
• 2: Ads with 2+ copies (default)
• 5: Popular ads only
• 10: Very popular ads

Advanced Features

Infinite Scroll Detection

The scraper intelligently detects when Facebook's infinite scroll is loading more content:

• Monitors page height changes
• Detects loading indicators
• Waits for content to settle
• Only stops when truly exhausted

Crash Recovery

• Handles Facebook "Aw, Snap!" errors
• Recovers from browser crashes
• Continues from where it left off
• Preserves collected data

Memory Management

• Processes elements in batches
• Garbage collection optimization
• Memory usage monitoring
• Prevents memory leaks

Docker Deployment

Quick Docker Run

# Build and run
docker build -t facebook-ads-scraper .
docker run --rm -v $(pwd)/data:/app/data facebook-ads-scraper --query "health"

Docker Compose

version: '3.8'
services:
  scraper:
    build: .
    volumes:
      - ./data:/app/data
    environment:
      - SEARCH_QUERY=health
      - COUNTRY=US

Troubleshooting

Common Issues

1. No ads collected

   • Try different search query
   • Lower minimum ad count
   • Check country selection

2. Browser crashes

   • Increase scroll delay
   • Run in headless mode
   • Check internet connection

3. Installation issues

   # Reinstall globally
   npm uninstall -g facebook-ads-scraper
   npm install -g facebook-ads-scraper
      
   # Install browsers
   facebook-ads-scraper --install-browsers

Debug Mode

# Run with debug output
facebook-ads-scraper --query "test" --headless false

# Check version
facebook-ads-scraper --version

Development

Local Development

# Clone repository
git clone https://github.com/yourusername/facebook-ads-scraper.git
cd facebook-ads-scraper

# Install dependencies
npm install

# Install browsers
npm run install-browsers

# Run locally
npm start -- --query "health"

Project Structure

facebook-ads-scraper/
├── scraper/           # Main scraper code
│   ├── index.js      # Core scraper logic
│   ├── cli.js        # CLI interface
│   └── config.js     # Configuration
├── extension/         # Chrome extension
├── package.json       # NPM package config
└── README.md         # This file

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📧 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: GitHub Wiki

Legal Notice

This tool is for educational and research purposes. Users must comply with:

• Facebook's Terms of Service
• Applicable data protection laws (GDPR, CCPA, etc.)
• Rate limiting and respectful scraping practices

Always review and respect the target website's robots.txt and terms of service.