google-ad-scraper

Google Ads Transparency Scraper

Scrape ads from Google's Ads Transparency Center using the Apify xtech/google-ad-transparency-scraper actor. Covers Search, YouTube, Display, and Gmail ads.

Quick Start

Requires APIFY_API_TOKEN env var (or --token flag). Install dependency: pip install requests.

# Search by company name (auto-resolves advertiser ID)
python3 skills/google-ad-scraper/scripts/search_google_ads.py \
  --company "Nike"

# Search by domain (more precise)
python3 skills/google-ad-scraper/scripts/search_google_ads.py \
  --domain "nike.com"

Direct advertiser ID (skip lookup step)

python3 skills/google-ad-scraper/scripts/search_google_ads.py
--advertiser-id "AR13129532367502835713"

With region filter

python3 skills/google-ad-scraper/scripts/search_google_ads.py
--company "Shopify" --region US

Limit results

python3 skills/google-ad-scraper/scripts/search_google_ads.py
--domain "hubspot.com" --max-ads 30

Human-readable summary

python3 skills/google-ad-scraper/scripts/search_google_ads.py
--company "Stripe" --output summary

## How It Works

1. **Advertiser Resolution** (if no `--advertiser-id` provided):
   - Takes company name or domain
   - Searches Google Ads Transparency Center using Apify's web-scraper (Puppeteer)
   - Extracts advertiser ID(s) from search results (format: `AR` + 20 digits)
2. **Ad Scraping**:
   - Constructs transparency center URL for the advertiser
   - Calls the Apify `xtech/google-ad-transparency-scraper` actor
   - Polls until complete, fetches dataset
3. **Output**: Returns ads as JSON or human-readable summary

## Advertiser ID Resolution

The script handles the name → ID lookup automatically:

- **By domain** (`--domain nike.com`): Searches `adstransparency.google.com/?domain=nike.com`. Most reliable method.
- **By name** (`--company "Nike"`): Searches `adstransparency.google.com/?text=Nike`. May return multiple matches.
- **Direct ID** (`--advertiser-id AR...`): Skips lookup entirely. Use when you already have the ID.

### Finding the Advertiser ID Manually

If auto-resolution fails:
1. Go to https://adstransparency.google.com
2. Search for the company
3. Click on the advertiser
4. Copy the ID from the URL: `https://adstransparency.google.com/advertiser/AR17828074650563772417`
5. Pass it via `--advertiser-id AR17828074650563772417`

## CLI Reference

| Flag | Default | Description |
|------|---------|-------------|
| `--company` | none | Company name to search |
| `--domain` | none | Company domain (e.g. nike.com) — more precise |
| `--advertiser-id` | none | Google Ads advertiser ID(s), comma-separated (skips lookup) |
| `--region` | anywhere | Region filter (US, GB, DE, etc. or "anywhere") |
| `--max-ads` | 50 | Maximum number of ads to return |
| `--output` | json | Output format: `json` or `summary` |
| `--token` | env var | Apify token (prefer `APIFY_API_TOKEN` env var) |
| `--timeout` | 300 | Max seconds to wait for Apify run |

At least one of `--company`, `--domain`, or `--advertiser-id` is required.

## Output Fields

Each ad in the output may contain (varies by ad format):

```json
{
  "advertiser_name": "Nike, Inc.",
  "advertiser_id": "AR13129532367502835713",
  "ad_format": "TEXT",
  "headline": "Nike.com - Official Site",
  "description": "Shop the latest Nike shoes, clothing...",
  "display_url": "nike.com",
  "destination_url": "https://www.nike.com/",
  "region": "United States",
  "last_shown": "2026-02-20",
  "first_shown": "2026-01-15",
  "image_url": "https://...",
  "video_url": "https://..."
}

Cost

• Advertiser lookup: ~$0.05 (one web-scraper page)
• Ad scraping: Varies by actor pricing, typically a few cents per advertiser

Common Workflows

1. Competitor Ad Research

python3 skills/google-ad-scraper/scripts/search_google_ads.py \
  --domain "competitor.com" --max-ads 100 --output summary

2. Compare Multiple Competitors

# Get IDs first, then scrape in one run
python3 skills/google-ad-scraper/scripts/search_google_ads.py \
  --advertiser-id "AR111,AR222,AR333" --max-ads 50

3. Regional Ad Targeting Analysis

# See what ads run in specific regions
python3 skills/google-ad-scraper/scripts/search_google_ads.py \
  --domain "shopify.com" --region US --output summary

python3 skills/google-ad-scraper/scripts/search_google_ads.py \
  --domain "shopify.com" --region GB --output summary

Limitations

• Advertiser ID lookup uses Puppeteer-based web scraping of Google's SPA. It may occasionally fail — use --domain for best results or provide --advertiser-id directly.
• Ad coverage: Google only shows ads from verified advertisers. Some smaller advertisers may not appear.
• Historical data: The Transparency Center primarily shows recently active ads.

Configuration

See references/apify-config.md for detailed API configuration, token setup, and rate limits.