🎯 Google Ads Transparency API Scraper

The most robust and reliable way to scrape Google Ads Transparency Center data. Effortlessly search for ads by domain, advertiser, or keyword and extract creative details including images, videos, and text.

---

✨ Features

• 🔍 Comprehensive Search: Search ads by Domain (e.g., google.com) or Advertiser ID.
• 🌍 Global Coverage: Support for searching ads in specific countries (e.g., US, CA, UK).
• 🎞️ Multiple Formats: Filter by Image, Video, or Text usage.
• 📄 Pagination: Automatically handles pagination to retrieve up to thousands of ads.
• ⚡ Super Fast: Built with FastAPI and optimized for speed and high concurrency.
• 🛡️ Resilience: Intelligent retry logic and caching to handle rate limits and ensure success.

---

🚀 Usage

Input Parameters

Parameter	Type	Default	Description
searchType	String	"domain"	Required. One of: "domain", "advertiser_id", "creative_details".
domain	String	-	Required if searchType is "domain". The domain to search ads for (e.g., nike.com).
advertiserId	String	-	Required if searchType is "advertiser_id" or "creative_details".
creativeId	String	-	Required if searchType is "creative_details".
countryCode	String	"US"	Two-letter country code (e.g., US, GB, CA, DE).
format	String	"ALL"	Filter ad format: "ALL", "IMAGE", "VIDEO", "TEXT".
limit	Integer	40	Number of results per page (Max 40 per request, handled automatically by actor paginator).
maxPages	Integer	1	Maximum number of pages to scrape. Each page contains up to 40 ads.
startPeriod	String	-	Start date (YYYY-MM-DD). Only for advertiser_id search.
endPeriod	String	-	End date (YYYY-MM-DD). Only for advertiser_id search.

Example Input

1. Search by Domain (Most Common)

Scrape the first 120 image ads for nike.com in the US.

{
    "searchType": "domain",
    "domain": "nike.com",
    "countryCode": "US",
    "format": "IMAGE",
    "limit": 40,
    "maxPages": 3
}

2. Search by Advertiser ID

Filter ads by a specific time range.

{
    "searchType": "advertiser_id",
    "advertiserId": "AR1234567890",
    "startPeriod": "2024-01-01",
    "endPeriod": "2024-02-01",
    "maxPages": 5
}

3. Get Creative Details

Fetch detailed metadata for a specific ad creative.

{
    "searchType": "creative_details",
    "advertiserId": "AR1234567890",
    "creativeId": "CR0987654321"
}

---

📦 Output Structure

The actor stores results in the default Apify Dataset. Each item usually represents one ad creative.

{
    "advertiser_id": "AR15743419998638669825",
    "advertiser_name": "Google LLC",
    "creative_id": "CR11090006764426559489",
    "original_url": "https://adstransparency.google.com/advertiser/AR15743419998638669825/creative/CR11090006764426559489?region=US",
    "variants": [
        {
            "content": "<div...>...</div>",
            "image": "https://tpc.googlesyndication.com/simgad/...",
            "format": "Image"
        }
    ],
    "start": "2024-03-15",
    "last_seen": "2024-03-20",
    "format_type": "Image"
}

---

🧑‍💻 programmatic Usage (Python Client)

You can easily run this actor using the Apify Python Client.

$pip install apify-client

from apify_client import ApifyClient

# Initialize the client with your API token
client = ApifyClient("YOUR_APIFY_TOKEN")

# Prepare the Actor input
run_input = {
    "searchType": "domain",
    "domain": "airbnb.com",
    "countryCode": "US",
    "maxPages": 2,
}

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

# Fetch and print Actor results from the run's dataset (if the run was successful)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

🔗 Resources

• Google Ads Transparency Center: https://adstransparency.google.com/
• Apify SDK: https://docs.apify.com/sdk/python
• FastAPI: https://fastapi.tiangolo.com/