# Google Ads Transparency Scraper (`shashankms2580/google-ads-transparency-scraper`) Actor

Scrapes Google’s Ad Transparency Center with image/video extraction, OCR, and multi-region support. Includes presets, cost preview, and enterprise features. Fair pricing: usage-based for ads, domains, and runs.

- **URL**: https://apify.com/shashankms2580/google-ads-transparency-scraper.md
- **Developed by:** [Shashank Shankar](https://apify.com/shashankms2580) (community)
- **Categories:** Automation, SEO tools, Lead generation
- **Security:** Limited permissions
- **Stats:** 138 total users, 0 monthly users, 100.0% runs succeeded, 5 bookmarks
- **User rating**: 1.49 out of 5 stars

## Pricing

from $0.90 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Google Ads Transparency Scraper - Enhanced

Professional Ad Intelligence Platform with Smart Presets & Enterprise Features

Transform your ad monitoring from basic scraping to professional intelligence gathering with our enhanced platform featuring smart presets, cost calculator, and enterprise-grade UI.

### 🌟 What's New in Enhanced Version

#### 🚀 Smart Configuration Presets

- **⚡ Quick Start**: Perfect for beginners - fast, lightweight, cost-effective
- **🔍 Competitive Analysis**: Comprehensive analysis for agencies and marketers
- **🔑 Keyword Monitoring**: Content-focused monitoring with OCR and filtering
- **⚙️ Custom**: Full control for advanced users

#### 💰 Real-Time Cost Calculator

- **Processing Time Estimates**: Per-target and total processing time
- **Cost Multipliers**: Relative cost estimates for different configurations
- **Resource Requirements**: Memory and CPU requirements
- **Optimization Tips**: Personalized recommendations for better performance

#### 🎨 Enhanced Visual Interface

- **Professional UI**: Buttons, toggles, dropdowns instead of JSON
- **Comprehensive Help**: Tooltips and guidance for every option
- **Smart Defaults**: Automatic configuration based on preset selection
- **Real-Time Validation**: Instant feedback and error checking

### 🔧 Technical Features

#### Core Capabilities

- **Target Processing**: Domains, advertiser IDs, full URLs
- **Mode Selection**: LITE (fast) vs FULL (comprehensive)
- **OCR Integration**: Text extraction from images with confidence scoring
- **Advanced Filtering**: Regions, dates, media types, keywords
- **Performance Control**: Configurable concurrency (1-50 targets)
- **Delta Mode**: Only process new ads since last run

#### Architecture Improvements

- **Playwright Integration**: Modern browser automation for stability
- **Scalable Concurrency**: Handle 1-50 targets simultaneously
- **Robust Error Handling**: Graceful failures with comprehensive logging
- **Resource Optimization**: Efficient memory and CPU usage
- **Session Management**: Rotating User-Agents and headers

### 📊 Performance & Cost

#### 💰 Transparent Pricing Structure

Our enhanced actor uses a hybrid Pay-Per-Event (PPE) + Pay-Per-Result (PPR) model for fair and predictable pricing:

##### PPE Events (Per Run)

| Event | Description | Price |
|-------|-------------|-------|
| run_start | Pre-flight validation, concurrency orchestration, presets loading | $5.00 |
| country_processing | Per-region processing, deduplication, compliance logic | $0.50 per country (capped at $15.00) |

##### PPR Events (Per Result)

| Event | Description | Price |
|-------|-------------|-------|
| lite_processing | Metadata only (advertiser, regions, text copy, links) | $0.006 per ad ($6 per 1,000 ads) |
| full_processing | Everything in LITE + creative download and OCR | $0.012 per ad ($12 per 1,000 ads) |

#### Pricing Examples

| Scenario | Mode | Targets | Regions | Est. Ads | Total Cost |
|----------|------|---------|---------|----------|------------|
| Basic Monitoring | LITE | 5 | US | 50 | $5.00 + $0.30 = $5.30 |
| Competitive Analysis | FULL | 10 | US, CA, IN | 100 | $5.00 + $1.20 + $1.50 = $7.70 |
| Global Brand Audit | FULL | 20 | 15 regions | 200 | $5.00 + $2.40 + $7.50 = $14.90 |

#### Processing Times by Preset

| Preset | Mode | OCR | Time per Target | Cost Multiplier |
|--------|------|-----|-----------------|-----------------|
| Quick Start | LITE | ❌ | 20s | 1.0x |
| Competitive Analysis | FULL | ✅ | 98s | 4.75x |
| Keyword Monitoring | FULL | ✅ | 90s | 4.32x |
| Custom | Variable | Variable | Variable | Variable |

#### Resource Requirements

| Preset | Memory | CPU Cores | Best For |
|--------|--------|-----------|----------|
| Quick Start | 1,500 MB | 5.0 | Beginners, basic monitoring |
| Competitive Analysis | 8,125 MB | 35.0 | Agencies, detailed analysis |
| Keyword Monitoring | 6,500 MB | 28.0 | Brand monitoring, content analysis |

### 💡 Cost Optimization Tips

#### Reduce Costs:

- Use LITE mode for basic monitoring (50% cheaper than FULL)
- Limit regions to essential markets (each region adds $0.50)
- Enable delta mode to skip already-processed ads
- Set maxCost to prevent unexpected charges

#### Maximize Value:

- FULL mode provides OCR text extraction and enhanced metadata
- Multiple regions give comprehensive market coverage
- Keyword filtering makes OCR processing more valuable
- Batch processing reduces per-run overhead costs

### ⚙️ Technical Specifications

#### Resource Allocation

| Component | Build | Runtime |
|-----------|-------|---------|
| Memory | 8 GB | 16 GB |
| Timeout | 15 min | 8 hours |
| Concurrency | N/A | 1-100 targets |
| CPU Cores | 4 | 8+ |

#### Performance Features

- **Scalable Architecture**: Handle 1-100 targets simultaneously
- **Memory Optimization**: Efficient resource usage for large datasets
- **Extended Runtime**: Up to 8 hours for comprehensive audits
- **Concurrency Control**: Configurable from 1 to 100 parallel targets

### 🚀 Quick Start Guide

#### Option 1: Use a Preset (Recommended)

1. **Choose a Preset**: Select from Quick Start, Competitive Analysis, or Keyword Monitoring
2. **Add Your Targets**: Enter domains, advertiser IDs, or URLs
3. **Click Run**: The actor automatically configures optimal settings

#### Option 2: Custom Configuration

1. **Select Custom Preset**
2. **Configure Each Setting** based on your needs
3. **Review Cost Estimates** before running
4. **Click Run** with your optimized configuration

### ❓ Billing FAQ

**Q: How much will my run cost?**
A: Use the cost preview feature! It shows estimated costs before charging. Base cost is $5.00 + $0.50 per region + $0.006-$0.012 per ad.

**Q: What if I exceed my budget?**
A: Set maxCost in your input. The actor will abort before charging if estimated cost exceeds your limit.

**Q: Why do I pay per region?**
A: Each region requires separate page visits and processing. We only bill for regions you actually process.

**Q: Can I get a refund for failed runs?**
A: We only charge for successful processing. Failed runs only incur the $5.00 run_start fee.

**Q: How does delta mode save money?**
A: Delta mode skips ads you've already processed, reducing PPR charges while maintaining data freshness.

### 🎯 Use Cases

#### For Beginners

- **Quick Start Preset**: Basic monitoring and basic analysis
- **5-10 targets**: Start small and scale up
- **US region only**: Focus on primary market
- **Delta mode**: Save costs with incremental processing

#### For Agencies

- **Competitive Analysis Preset**: Comprehensive competitor monitoring
- **Multiple regions**: Cover global markets
- **FULL mode**: Detailed creative analysis
- **OCR enabled**: Content analysis and keyword filtering

#### For Brand Managers

- **Keyword Monitoring Preset**: Brand mention tracking
- **Include/exclude keywords**: Focus on relevant content
- **Regular monitoring**: Set up ongoing brand protection
- **Content analysis**: Understand competitive positioning

### 📈 Output Data

#### Enhanced Schema

- **Basic Information**: Ad ID, advertiser details, source URLs
- **Geographic & Temporal**: Regions, first seen, last seen
- **Content & Media**: Media types, text copy, image/video URLs
- **OCR & Analysis**: Extracted text, confidence scores, engine info
- **Processing Info**: Mode used, targets matched, collection timestamp

#### Output Formats

- **Dataset**: Best for Apify integration and web interface
- **CSV**: Perfect for Excel analysis and team sharing
- **JSONL**: Ideal for API integration and programmatic processing

### 🔍 Advanced Features

#### Smart Preset Application

- **Automatic Configuration**: Presets set optimal defaults
- **User Override**: Your settings take precedence
- **Compatibility Validation**: Warnings for incompatible configurations
- **Intelligent Merging**: Smart combination of preset and user settings

#### Cost Optimization

- **Real-Time Estimates**: Processing time and cost calculations
- **Efficiency Scoring**: Performance ratings (Excellent, Good, Fair)
- **Optimization Tips**: Personalized recommendations
- **Resource Planning**: Memory and CPU requirements upfront

#### Error Handling & Validation

- **Input Validation**: Real-time checking of all parameters
- **Graceful Failures**: Individual target failures don't crash the run
- **Comprehensive Logging**: Detailed progress tracking and error reporting
- **User Guidance**: Clear error messages and resolution suggestions

### 💡 Best Practices

#### Performance Optimization

- **Use Presets**: Start with recommended configurations
- **Enable Delta Mode**: Only process new ads for ongoing monitoring
- **Limit Regions**: Focus on essential markets
- **Start Small**: Begin with fewer targets and scale up

#### Cost Management

- **Choose LITE Mode**: When detailed analysis isn't needed
- **Disable OCR**: If text extraction isn't required
- **Use Request Limits**: For testing and cost control
- **Monitor Estimates**: Use built-in cost calculator

#### Data Quality

- **Validate Targets**: Ensure domains and URLs are correct
- **Use Keywords**: Make OCR processing more valuable
- **Regular Monitoring**: Set up ongoing tracking schedules
- **Review Results**: Analyze output for insights and improvements

### 🚨 Troubleshooting

#### Common Issues

- **"No results found"**: Check target validity and filter settings
- **"Processing failed"**: Verify internet connection and reduce concurrency
- **"High costs"**: Switch to LITE mode or disable OCR
- **"Slow processing"**: Increase concurrency or use LITE mode

#### Performance Issues

- **Memory errors**: Reduce concurrency or use LITE mode
- **Slow processing**: Check concurrency settings and resource limits
- **High error rates**: Verify target accessibility and reduce load

### 📚 Documentation & Support

#### User Resources

- **User Guide**: Comprehensive documentation for all features
- **Deployment Checklist**: Step-by-step production deployment
- **Best Practices**: Optimization tips and cost management
- **Troubleshooting**: Common issues and solutions

#### Technical Resources

- **API Reference**: Input/output schema documentation
- **Performance Metrics**: Processing times and resource requirements
- **Error Codes**: Detailed error descriptions and resolutions
- **Integration Guide**: Apify platform integration

### 🎉 What You've Accomplished

Your enhanced Google Ads Transparency Scraper now provides:

- **Professional UI**: Enterprise-grade interface with comprehensive guidance
- **Smart Automation**: One-click presets for common use cases
- **Cost Transparency**: Real-time estimates and optimization tips
- **Scalable Architecture**: Production-ready infrastructure
- **Competitive Advantage**: Features that match or exceed top-tier solutions

### 🚀 Ready for Production!

This enhanced actor is production-ready and provides exceptional value for:

- **Marketing Agencies**: Comprehensive competitive intelligence
- **Brand Managers**: Brand monitoring and content analysis
- **Market Researchers**: Ad trend analysis and campaign tracking
- **Business Analysts**: Competitive positioning and market insights

Start with a preset, experiment with custom configurations, and discover the power of automated ad intelligence! 🎯

***

**Built with ❤️ by Shashank Shankar**

**Version**: 2.0.0\
**Last Updated**: August 2024\
**Status**: Production Ready 🚀

**Contact**: shashank.m.s2580@gmail.com

# Actor input Schema

## `preset` (type: `string`):

Choose a preset configuration to get started quickly

## `targets` (type: `array`):

Enter domains, advertiser IDs, or URLs

## `region` (type: `string`):

Select the region where ads were shown. Use 'AL' for worldwide coverage (region=anywhere)

## `platform` (type: `string`):

Select specific platform or 'all' for all platforms. Maps=MAPS, Search=SEARCH, Shopping=SHOPPING, YouTube=YOUTUBE

## `timePeriod` (type: `string`):

Select the time period for ad search. 'All Time' gives maximum coverage, custom dates will be used if specified below

## `startDate` (type: `string`):

Custom start date (YYYY-MM-DD format). Leave empty to use time period preset

## `endDate` (type: `string`):

Custom end date (YYYY-MM-DD format). Leave empty to use time period preset

## `mode` (type: `string`):

LITE mode is fast and cost-effective, FULL mode provides comprehensive analysis

## `ocrEnabled` (type: `boolean`):

Extract text from images using OCR

## `keywords` (type: `object`):

Only include creatives whose OCR text matches these include/exclude keywords

## `maxConcurrency` (type: `integer`):

Number of targets to process simultaneously (1-50)

## `deltaSinceLastRun` (type: `boolean`):

Only process new ads since last run

## `outputFormat` (type: `string`):

Choose how you want to receive your data

## Actor input object example

```json
{
  "preset": "quick_start",
  "targets": [
    "example.com"
  ],
  "region": "US",
  "platform": "all",
  "timePeriod": "all_time",
  "mode": "LITE",
  "ocrEnabled": false,
  "keywords": {
    "include": [],
    "exclude": []
  },
  "maxConcurrency": 20,
  "deltaSinceLastRun": true,
  "outputFormat": "dataset"
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "targets": [
        "example.com"
    ],
    "keywords": {
        "include": [],
        "exclude": []
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("shashankms2580/google-ads-transparency-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "targets": ["example.com"],
    "keywords": {
        "include": [],
        "exclude": [],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("shashankms2580/google-ads-transparency-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "targets": [
    "example.com"
  ],
  "keywords": {
    "include": [],
    "exclude": []
  }
}' |
apify call shashankms2580/google-ads-transparency-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,shashankms2580/google-ads-transparency-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/zB0rjv0Wf9gyguGSV/builds/70adYT88wGRQbfr6w/openapi.json
