# Google Ads Transparency API | Ad Library for Marketing Agents (`johnvc/google-ads-transparency-api`) Actor List any advertiser's ads from the Google Ads Transparency Center as structured JSON: ad format, first and last shown dates, total days running, and a preview link. Competitor ad library for growth teams, agencies, and AI marketing agents. Pay per ad, MCP-ready. - **URL**: https://apify.com/johnvc/google-ads-transparency-api.md - **Developed by:** [John](https://apify.com/johnvc) (community) - **Categories:** Lead generation, AI, MCP servers - **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $0.01 / 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Google Ads Transparency API | Competitor Ad Library for Marketing Agents List any advertiser's ads from the Google Ads Transparency Center as clean structured JSON. Give the API an advertiser ID and get back the ads they are running, each with its format, the dates it was first and last shown, the total days it has run, and a preview link. It is a competitor ad library for growth teams, agencies, and AI marketing agents, the kind of competitive intelligence tools like SpyFu and SEMrush charge a subscription for, available pay-as-you-go. ### What you get One row per ad: - `advertiser` and `advertiser_id` - `ad_creative_id` and `format` (text, image, or video) - `first_shown` and `last_shown` (timestamps) and `total_days_shown` - `link` to a preview of the creative, and a `details_link` to the ad on the Transparency Center ### Use cases - Build a competitor ad library and watch what creatives a rival runs - Track how long an ad has been running (long run time signals a winner) - Audit a brand's video vs image vs text ad mix over time - Feed an AI marketing agent a competitor's live ads for creative analysis - Monitor several advertisers at once and diff their libraries on a schedule ### Input | Field | Type | Description | |-------|------|-------------| | `advertiserId` | string | A single advertiser ID, the AR... code in a Google Ads Transparency Center URL (e.g. `AR01614014350098432001`). Provide this, `advertiserIds`, or both. | | `advertiserIds` | array of strings | A batch of advertiser IDs to fetch in one run. Merged with `advertiserId` and de-duplicated. | | `region` | string | Optional region filter. Leave blank to include ads shown anywhere. | | `maxResultsPerAdvertiser` | integer | Ads per advertiser. Default 50, maximum 500. | To get an advertiser ID, open the advertiser on the Google Ads Transparency Center; the AR... code is in the URL. #### Example input ```json { "advertiserId": "AR01614014350098432001", "maxResultsPerAdvertiser": 50 } ```` ### Sample output ```json { "result_type": "ad", "advertiser_id": "AR01614014350098432001", "position": 1, "ad_creative_id": "CR08181256642625536001", "advertiser": "lululemon athletica canada inc.", "format": "video", "first_shown": 1731000000, "last_shown": 1748700000, "total_days_shown": 204, "link": "https://displayads-formats.googleusercontent.com/ads/preview/...", "details_link": "https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR08181256642625536001" } ``` ### Pricing Pay-per-result: a small `actor_start` fee plus a per-ad charge. The per-ad price scales down with your Apify plan. | Plan | Per ad | Start fee | |---|---|---| | Free | $0.003 | $0.001 | | Bronze | $0.0025 | $0.001 | | Silver | $0.002 | $0.001 | | Gold | $0.0017 | $0.001 | You only pay for the ads you receive. No monthly minimum. ### How to get started 1. Open [Google Ads Transparency API on the Apify Store](https://apify.com/johnvc/google-ads-transparency-api?fpr=9n7kx3). 2. Enter an `advertiserId` (or a `advertiserIds` list). 3. Set `maxResultsPerAdvertiser`, then run the Actor. 4. Export the dataset as JSON, CSV, or Excel, or pull it from the API. Prefer code? See [johnvc's GitHub for setup guides and code examples](https://github.com/johnisanerd/ApifyPublicData). ### Run from the API ```bash curl -X POST "https://api.apify.com/v2/acts/johnvc~google-ads-transparency-api/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"advertiserId":"AR01614014350098432001","maxResultsPerAdvertiser":25}' ``` ### 🔌 Use this API from Claude (MCP) This Actor is compatible with the Model Context Protocol (MCP), so AI agents can call it as a tool. Add it through the hosted Apify MCP server using this Actor-specific URL: https://mcp.apify.com/?tools=actors,docs,johnvc/google-ads-transparency-api If you run agents from [Claude Code](https://claude.ai/referral/uIlpa7nPLg) (free trial) or [Claude Cowork](https://claude.ai/referral/uIlpa7nPLg) (free trial), add the Apify MCP server and ask it to "pull this competitor's ad library and summarize their creative strategy." Setup walkthrough: https://www.youtube.com/watch?v=jREWahDGhJM Apify MCP integration docs: https://docs.apify.com/platform/integrations/mcp #### MCP setup, step by step Visual setup guides for each client (source and more assets: [ApifyPublicData on GitHub](https://github.com/johnisanerd/ApifyPublicData)): **[Claude Cowork Desktop](https://claude.ai/referral/uIlpa7nPLg)** (free trial) ![Apify MCP install screenshot for the Cowork desktop app](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_claude_desktop.png) **[Claude Code](https://claude.ai/referral/uIlpa7nPLg)** (free trial) ![Apify MCP install screenshot for the Code CLI](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_claude_code.png) **Claude (website)** ![Install in Claude website](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_claude_ai.png) **Cursor** ![Install in Cursor](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_cursor.png) **ChatGPT** ![Install in ChatGPT](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_ChatGPT.png) ### FAQ **What is an advertiser ID?** It is the AR... code that identifies an advertiser on the Google Ads Transparency Center. Open the advertiser there and copy the code from the URL. **How many ads come back?** Up to `maxResultsPerAdvertiser` (default 50). The Actor paginates an advertiser's library for you. **Can I track several competitors at once?** Yes. Pass an `advertiserIds` list; each is fetched independently. **Does it include the ad preview?** Yes. Each ad has a `link` to a preview of the creative and a `details_link` to the ad on the Transparency Center. ### n8n integration Available as an n8n community node, **[n8n-nodes-google-ads-transparency-api](https://www.npmjs.com/package/n8n-nodes-google-ads-transparency-api)**. In n8n: Settings, Community Nodes, install `n8n-nodes-google-ads-transparency-api`, then use it in any workflow (it also works as an AI Agent tool). ### Featured Tasks Ready-to-run examples that show this API solving a specific problem. Each opens its own setup so you can run it on your account in one click. - [Spy on a Competitor's Google Ads](https://apify.com/johnvc/google-ads-transparency-api/examples/spy-on-competitor-google-ads?fpr=9n7kx3) - See every Google ad a competitor is running: ad format, first and last shown dates, total days running, and a link to each ad on the Transparency Center. - [Monitor a Political Advertiser's Google Ads](https://apify.com/johnvc/google-ads-transparency-api/examples/political-advertiser-google-ads?fpr=9n7kx3) - Pull a political advertiser's Google ads from the Transparency Center: ad format, first and last shown dates, total days running, and a link to each ad. - [Export an advertiser's Google ads to CSV](https://apify.com/johnvc/google-ads-transparency-api/examples/export-advertiser-google-ads-to-csv?fpr=9n7kx3) - Export every ad an advertiser runs in the Google Ads Transparency Center to CSV. - [Track how long a competitor's ads have run](https://apify.com/johnvc/google-ads-transparency-api/examples/track-competitor-ad-duration?fpr=9n7kx3) - Track how long each of a competitor's Google ads has run. - [Audit an advertiser's Google ad creatives](https://apify.com/johnvc/google-ads-transparency-api/examples/audit-advertiser-google-ad-creatives?fpr=9n7kx3) - Audit every ad creative an advertiser runs on Google. Last Updated: 2026.06.21 # Actor input Schema ## `advertiserId` (type: `string`): Enter a single advertiser ID. This is the AR... code in a Google Ads Transparency Center advertiser URL, for example 'AR01614014350098432001' (from adstransparency.google.com/advertiser/AR01614014350098432001). Provide this, `advertiserIds`, or both. ## `advertiserIds` (type: `array`): Provide a list of advertiser IDs (AR... codes) to fetch in one run. Merged with `advertiserId` and de-duplicated. ## `region` (type: `string`): Optionally limit ads to a region. Leave blank to include ads shown anywhere. Use a Google ads region code when targeting a specific country. ## `maxResultsPerAdvertiser` (type: `integer`): How many ads to return per advertiser. The Actor paginates as needed, then stops early when an advertiser runs out of ads. Default 50, maximum 500. ## Actor input object example ```json { "advertiserId": "AR01614014350098432001", "maxResultsPerAdvertiser": 50 } ``` # Actor output Schema ## `results` (type: `string`): All ad rows stored in the default dataset, one item per ad. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "advertiserId": "AR01614014350098432001" }; // Run the Actor and wait for it to finish const run = await client.actor("johnvc/google-ads-transparency-api").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "advertiserId": "AR01614014350098432001" } # Run the Actor and wait for it to finish run = client.actor("johnvc/google-ads-transparency-api").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "advertiserId": "AR01614014350098432001" }' | apify call johnvc/google-ads-transparency-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=johnvc/google-ads-transparency-api", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Ads Transparency API | Ad Library for Marketing Agents", "description": "List any advertiser's ads from the Google Ads Transparency Center as structured JSON: ad format, first and last shown dates, total days running, and a preview link. Competitor ad library for growth teams, agencies, and AI marketing agents. Pay per ad, MCP-ready.", "version": "0.0", "x-build-id": "UuFfb4hA6g0ohP5Gq" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/johnvc~google-ads-transparency-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-johnvc-google-ads-transparency-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/johnvc~google-ads-transparency-api/runs": { "post": { "operationId": "runs-sync-johnvc-google-ads-transparency-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/johnvc~google-ads-transparency-api/run-sync": { "post": { "operationId": "run-sync-johnvc-google-ads-transparency-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "advertiserId": { "title": "Advertiser ID", "type": "string", "description": "Enter a single advertiser ID. This is the AR... code in a Google Ads Transparency Center advertiser URL, for example 'AR01614014350098432001' (from adstransparency.google.com/advertiser/AR01614014350098432001). Provide this, `advertiserIds`, or both." }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "Provide a list of advertiser IDs (AR... codes) to fetch in one run. Merged with `advertiserId` and de-duplicated.", "items": { "type": "string" } }, "region": { "title": "Region", "type": "string", "description": "Optionally limit ads to a region. Leave blank to include ads shown anywhere. Use a Google ads region code when targeting a specific country." }, "maxResultsPerAdvertiser": { "title": "Maximum Ads Per Advertiser", "minimum": 1, "maximum": 500, "type": "integer", "description": "How many ads to return per advertiser. The Actor paginates as needed, then stops early when an advertiser runs out of ads. Default 50, maximum 500.", "default": 50 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```