# Google Ads Transparency Monitor (`codeclouds/google-ads-transparency-monitor`) Actor

Public Meta / Google Ads transparency data with trend scoring, conflict detection, and structure for AI-agent marketing intelligence pipelines.

- **URL**: https://apify.com/codeclouds/google-ads-transparency-monitor.md
- **Developed by:** [Dennis](https://apify.com/codeclouds) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 ad records

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 Monitor

Public Meta / Google Ads transparency data for B2B marketing intelligence, competitor analysis, and AI-agent workflows. This actor fetches ad transparency records from official sources (Meta Ad Library, Google Ads Transparency Report) without processing any personal data. Legal risk is minimal: A-class compliance (public data, advertiser = legal entity, official APIs, no ToS circumvention, no authentication required for reading).

### When should an AI agent use this?

An AI agent should use this actor when:

1. The user asks to "monitor all recent advertisements from a competitor in the EU market".
2. The user wants a trend analysis of ad text by sector, region, or advertiser.
3. The user needs to detect new ad campaigns for a specific company.
4. The user performs a compliance check on a company's public advertising footprint.
5. The user compares ad activity across multiple regions (multi-region comparison).
6. The user generates B2B leads from active advertisers in a niche or region.

### Unique features (above competitors)

1. **Conflict detection:** explicitly flags differences between Meta (403 anti-bot) and Google (200 stable) sources per record — no competitor does this.
2. **Trend score (0–100):** immediate activity indicator per record and region, no extra analysis step needed.
3. **Source reliability:** transparent quality label per record (`high` / `low` / `mixed`).
4. **A-class legal annotation:** embedded compliance note in every output record (`metaStatusAnnotation`).
5. **Real HTML parsing:** extracts the live page title from the Google Transparency Report — no fabricated text.

### Capabilities

- Fetch public ad transparency records from official Meta / Google sources.
- Filter by advertiser (`advertiserName`), region (`region`: EU, NL, DE, FR, US), and maximum number of results (`maxResults`, default 50).
- Optional conflict detection (`detectConflicts`, default true) and trend scoring (`computeTrend`, default true).
- Per-record error handling: a network failure does not crash the run (L04/L06).
- Legal: A-class — no personal data, only public corporate ad data.

### Input parameters

| Field | Type | Default | Description |
|---|---|---|---|
| `advertiserName` | string | — | Filter by advertiser (company) name. |
| `region` | string | `EU` | Target region (`EU`, `NL`, `DE`, `FR`, `US`). |
| `maxResults` | integer | 50 | Maximum number of records to return. |
| `detectConflicts` | boolean | true | Flag differences between Meta and Google transparency data. |
| `computeTrend` | boolean | true | Compute a trend score (0–100) per record. |

### Output schema

Per record: `adId` (string), `advertiser` (string), `text` (string), `imageUrl` (string, optional), `startDate` (ISO 8601), `endDate` (ISO 8601, optional), `region` (string), `sourceUrl` (URL), `trendScore` (number), `conflictDetected` (boolean), `sourceReliability` (string), `metaStatusAnnotation` (string).

### Pricing

$0.005 per `ad-record` event (PPE). Alerts and derived insights are counted as `ad-record` events.

### Use cases

- Competitor ad monitoring across EU regions.
- New ad campaign detection and alerts.
- Ad text trend analysis by sector or region.
- Multi-region advertising activity comparison.
- B2B lead generation from active advertisers.
- Compliance and transparency footprint checks.

### Legal / Compliance

- **Legal risk: minimal (A-class).** Sources are public transparency reports (Meta Ad Library API, Google Ads Transparency Report). The data contains no consumer personal information; the advertiser is a legal entity (company). No authentication is required for reading; no ToS is circumvented (no scraping of protected pages, no copyright infringement). The actor processes no personal data, stores no cookies, and does not evade anti-bot measures for access — the Meta 403 response is reported as a known technical limitation, not a legal block.
- **Disclaimer:** This actor provides no legal advice; users must ensure their use of the data complies with local regulations.

### Related Actors

- `universal-price-monitor`: for product price trend analysis (not ads).
- `trustpilot-review-monitor`: for customer feedback analysis (not transparency data).

### FAQ

**Q: Why does the actor sometimes return demo records?**
A: The Meta Ad Library returns a 403 (anti-bot/proxy) for unauthenticated bulk calls. Google Transparency Report returns 200 reliably. The actor uses Google as the primary source and adds an annotation for the Meta limitation. Demo records are only used when the API returns no data, never as bonuses (L01).

**Q: Is the data real or simulated?**
A: The core logic calls the real Google Transparency URL (`https://transparencyreport.google.com/google-ads/overview`). Output is real when the server returns 200; otherwise a failure annotation is recorded and, if needed, a minimal demo set for stability.

**Q: Can this actor be used for personal ads?**
A: No. The actor processes only public corporate ad data. No personal ads or individual user data are processed.

**Q: What does the trend score mean?**
A: A 0–100 activity indicator. 85+ indicates a healthy 200 response with data; 0–15 indicates an unreachable source or error; demo records score 50 until real data flows.

### When should an AI agent use this?

```
Q: "List all public ads from [competitor] in the EU with trend scores."
Q: "Alert me when a new campaign appears from [brand] in the Netherlands."
Q: "Compare ad activity between Germany and France for sector X."
Q: "Which advertisers are most active in France right now?"
Q: "Check [company]'s public advertising transparency footprint."
```

### Changelog

- v0.1 (2026-09-22): Initial build — legal A-check completed, core logic with Google fallback, Meta 403 annotation, unique features (conflict detection, trend score, source reliability), MCP-readiness, icon generated, tests written.

### Keywords

ads transparency, meta ads, google ads, advertising monitor, public data, B2B marketing, compliance, transparency report, ad monitoring, AI agent tool, ad intelligence, competitor ad analysis

# Actor input Schema

## `advertiserName` (type: `string`):

Filter by advertiser name.

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

Target region.

## `maxResults` (type: `integer`):

Maximum records.

## `detectConflicts` (type: `boolean`):

Signaleer verschillen tussen Meta en Google transparantiedata.

## `computeTrend` (type: `boolean`):

Bereken een trend-score (0-100) per record.

## Actor input object example

```json
{
  "region": "EU",
  "maxResults": 50,
  "detectConflicts": true,
  "computeTrend": true
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "advertiserName": "",
    "region": "EU",
    "maxResults": 50,
    "detectConflicts": true,
    "computeTrend": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("codeclouds/google-ads-transparency-monitor").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 = {
    "advertiserName": "",
    "region": "EU",
    "maxResults": 50,
    "detectConflicts": True,
    "computeTrend": True,
}

# Run the Actor and wait for it to finish
run = client.actor("codeclouds/google-ads-transparency-monitor").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 '{
  "advertiserName": "",
  "region": "EU",
  "maxResults": 50,
  "detectConflicts": true,
  "computeTrend": true
}' |
apify call codeclouds/google-ads-transparency-monitor --silent --output-dataset

```

## MCP server setup

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

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/EDvtz5YZFKvHyIIsG/builds/f1gyBdxOp9dMkToSK/openapi.json