---
license: apache-2.0
title: Facebook Ad Analytics
sdk: docker
emoji: 📊
colorFrom: green
colorTo: blue
pinned: true
short_description: facebook-ad-analytics
---
# Facebook Ad Analytics

A comprehensive tool for scraping, analyzing, and visualizing Facebook ads using AI and machine learning.

## Features
- **Ad Scraping**: Scrape Facebook ads using Selenium.
- **Sentiment Analysis**: Analyze ad sentiment using AI (Hugging Face Transformers).
- **Image Analysis**: Extract text from images (OCR) and detect objects using YOLOv4.
- **Compliance Reporting**: Generate compliance reports and anonymize ads.
- **Predictive Analytics**: Forecast ad performance using machine learning.
- **Google Ads Analysis**: Scrape and analyze Google Search and Display ads.

## Requirements
- Python 3.9+
- PostgreSQL (recommended for production)
- Redis (for Celery task queue)
- Tesseract OCR

## Setup

### Quick Setup
1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/facebook-ad-analytics.git
   cd facebook-ad-analytics
   ```

2. Run the setup script:
   ```bash
   python setup.py
   ```

3. Update the `.env` file with your settings.

4. Run the application:
   ```bash
   python manage.py run
   ```

### Manual Setup
1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/facebook-ad-analytics.git
   cd facebook-ad-analytics
   ```

2. Create a virtual environment and install dependencies:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   ```

3. Copy the example environment file and update it:
   ```bash
   cp .env.example .env
   # Edit .env with your settings
   ```

4. Initialize the database:
   ```bash
   python manage.py init-db
   ```

5. Download YOLOv4 models:
   ```bash
   mkdir -p app/models
   wget https://github.com/AlexeyAB/darknet/releases/download/darknet_yolo_v3_optimal/yolov4.weights -O app/models/yolov4.weights
   wget https://raw.githubusercontent.com/AlexeyAB/darknet/master/cfg/yolov4.cfg -O app/models/yolov4.cfg
   ```

6. Run the application:
   ```bash
   python manage.py run
   ```

## Docker Deployment
For production deployment, use Docker Compose:

```bash
# Set environment variables in .env file first
docker-compose up -d
```

If you don't have a .env file, default development values will be used, but you should create one for production.

## Troubleshooting

### Missing Dependencies
If you encounter errors about missing dependencies, run the dependency checker:

```bash
python check_dependencies.py
```

This will identify any missing packages. You can install them with:

```bash
pip install -r requirements.txt
```

### Common Issues

#### ModuleNotFoundError: No module named 'ratelimit'
This error occurs when the ratelimit package is missing. Install it with:

```bash
pip install ratelimit
```

#### AI Model Warnings
Warnings about missing PyTorch, TensorFlow, or Flax are normal if you don't need the full AI capabilities. For full functionality, install:

```bash
pip install torch==2.0.1
```

#### Docker Startup Issues
If you encounter issues with Docker startup:

1. Check Docker logs for detailed error messages:
   ```bash
   docker-compose logs web
   ```

2. Try rebuilding the Docker image:
   ```bash
   docker-compose build --no-cache web
   docker-compose up -d
   ```

3. If you see syntax errors with parentheses in the command, the issue has been fixed in the latest version by removing the parentheses from the gunicorn command.

4. Ensure all required packages are in requirements.txt:
   ```bash
   # Check if ratelimit is in requirements.txt
   grep ratelimit requirements.txt
   
   # If not, add it
   echo "ratelimit==2.2.1" >> requirements.txt
   ```

## Testing
Run the test suite:
```bash
python manage.py test
```

## API Documentation
The API endpoints are available at `/api/v1/` and include:
- `/api/v1/ads` - List and create ads
- `/api/v1/ads/<id>` - Get, update, or delete an ad
- `/api/v1/analyze` - Analyze ad content

## License
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.