# Google Ads Library (`smacient/google-ads-library`) Actor

Search any brand's Google ads by name or domain. Get structured ad data - formats, dates, decoded copy, and image URLs. Filter by country, platform, and date. Competitive intelligence at $1 per 1,000 ads.

- **URL**: https://apify.com/smacient/google-ads-library.md
- **Developed by:** [Tacheon Digital](https://apify.com/smacient) (community)
- **Categories:** AI, Automation, E-commerce
- **Stats:** 5 total users, 4 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 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

---

## README

## Google Ads Library

Search and extract Google ads for any advertiser. Find who is advertising, what they are saying, and how long their campaigns have been running. Works for Search, Shopping, YouTube, Maps, and Display ads across every country.

Two modes: find an advertiser by brand name or domain, then pull their full ad inventory.

---

### Pricing

| Action | Cost |
|--------|------|
| Advertiser search | $1 per 1000 searches |
| Ad results | $1 per 1,000 ads |

No monthly fee. Pay only for what you use.

---

### What you get per ad

| Field | Description |
|-------|-------------|
| `advertiser_id` | Unique advertiser identifier |
| `advertiser_name` | Registered advertiser name |
| `creative_id` | Unique ad creative ID |
| `format` | IMAGE, VIDEO, or TEXT |
| `status` | ACTIVE, RECENTLY_ACTIVE, or INACTIVE |
| `is_active` | true if ad ran in the last 3 days |
| `first_shown` | Date the ad first appeared |
| `last_shown` | Date the ad was last shown |
| `days_shown` | Total days the ad has run |
| `days_since_last_shown` | Days since it last ran |
| `headline` | Ad headline (where available) |
| `description` | Ad description text |
| `cta` | Call-to-action text |
| `destination_url` | Landing page domain |
| `display_url` | Display URL shown in the ad |
| `image_url` | Direct image URL for display creatives |
| `image_width` / `image_height` | Image dimensions |
| `transparency_url` | Link to view the ad publicly |

---

### Modes

#### Find Advertiser

Search by brand name or domain and get a list of matching advertisers with their IDs, ad counts, and verified status. Results are sorted by ad volume so the most active advertiser appears first.

```json
{
  "mode": "find_advertiser",
  "advertisers": ["Tanishq", "nalli.com"],
  "maxResults": 10
}
````

Use this first to find the correct advertiser ID before running a full ad scrape.

#### Scrape Ads

Fetch all ads for one or more advertisers. Pass a name, domain, or advertiser ID directly.

```json
{
  "mode": "scrape_ads",
  "advertisers": ["AR16478616112506863617"],
  "region": "IN",
  "datePreset": "LAST_30_DAYS",
  "maxAdsPerAdvertiser": 200,
  "includeInactive": false
}
```

***

### Input reference

#### Advertisers

Pass brand names, domains, or IDs. Mix freely.

```json
"advertisers": [
  "Tanishq",
  "nalli.com",
  "AR16478616112506863617"
]
```

#### Region

ISO country code or `anywhere` for global results.

Examples: `IN`, `US`, `GB`, `AE`, `SG`, `AU`, `DE`

#### Platform

| Value | Platform |
|-------|----------|
| ALL | All platforms (default) |
| SEARCH | Google Search |
| SHOPPING | Google Shopping |
| YOUTUBE | YouTube |
| MAPS | Google Maps |
| PLAY | Google Play |

#### Date range

| Value | Range |
|-------|-------|
| ANY\_TIME | All time (default) |
| LAST\_7\_DAYS | Last 7 days |
| LAST\_30\_DAYS | Last 30 days |
| TODAY | Today only |
| YESTERDAY | Yesterday only |

Or use `startDate` and `endDate` in YYYY-MM-DD format for a custom range.

#### Other options

| Option | Default | Description |
|--------|---------|-------------|
| `maxAdsPerAdvertiser` | 0 (unlimited) | Cap results per advertiser |
| `includeInactive` | true | Set false for active ads only |
| `decodeAdContent` | true | Decode headline and description from ad encoding |

***

### Example runs

**Active ads for a competitor right now:**

```json
{
  "mode": "scrape_ads",
  "advertisers": ["nalli.com"],
  "region": "IN",
  "datePreset": "LAST_7_DAYS",
  "includeInactive": false
}
```

**Bulk sweep across multiple brands:**

```json
{
  "mode": "scrape_ads",
  "advertisers": [
    "Tanishq",
    "Kalyan Jewellers",
    "Malabar Gold",
    "PNG Jewellers",
    "Joyalukkas"
  ],
  "region": "IN",
  "datePreset": "LAST_30_DAYS",
  "maxAdsPerAdvertiser": 100
}
```

**YouTube video ads only:**

```json
{
  "mode": "scrape_ads",
  "advertisers": ["samsung.com"],
  "platform": "YOUTUBE",
  "formats": ["VIDEO"],
  "region": "anywhere"
}
```

**Find the right advertiser before scraping:**

```json
{
  "mode": "find_advertiser",
  "advertisers": ["Pothys"],
  "maxResults": 5
}
```

***

### Output example

```json
{
  "advertiser_id": "AR16478616112506863617",
  "advertiser_name": "POTHYS SWARNA MAHAL PRIVATE LIMITED",
  "creative_id": "CR06718390446600486913",
  "format": "TEXT",
  "status": "ACTIVE",
  "is_active": true,
  "first_shown": "2024-10-02",
  "last_shown": "2026-04-18",
  "days_shown": 536,
  "days_since_last_shown": 1,
  "headline": "Rush to our Store today",
  "description": "25% off on MC on Antique Silver Articles and 0% MC on Plain Silver Articles",
  "cta": "Contact us",
  "destination_url": "pothysswarnamahal.com",
  "transparency_url": "https://adstransparency.google.com/advertiser/AR16478616112506863617/creative/CR06718390446600486913?region=IN"
}
```

***

### Notes

Ad text (headline, description, CTA) is available for roughly 10 to 15 percent of ads. These are Search ads with fixed copy. Responsive and video ads assemble their text dynamically on Google's side and the copy is not publicly accessible. For those ads, the `transparency_url` field links directly to a viewable version of the ad.

Image ads include a direct `image_url` to the creative hosted on Google's CDN.

Data is sourced from public ad records that advertisers are required to make available. Coverage goes back to 2018.

# Actor input Schema

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

Find Advertiser: search by brand name or domain to get the advertiser ID.

Scrape Ads: fetch all ads for a known advertiser ID, name, or domain.

## `advertisers` (type: `array`):

Find Advertiser mode: enter brand names (e.g. 'Nike', 'Tanishq') or domains (e.g. 'nalli.com').

Scrape Ads mode: enter AR IDs (e.g. 'AR16478616112506863617'), brand names, or domains.

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

How many advertiser matches to return per brand search. Only used in Find Advertiser mode.

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

ISO alpha-2 country code (e.g. IN, US, GB) or 'anywhere' for global results.

## `datePreset` (type: `string`):

Filter ads by when they were last shown.

## `formats` (type: `array`):

Filter by format. Leave empty for all formats.

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

Filter by Google platform.

## `includeInactive` (type: `boolean`):

Include ads last shown within 14 days.

## `maxAdsPerAdvertiser` (type: `integer`):

Maximum ads to fetch per advertiser. 0 = unlimited.

## `decodeAdContent` (type: `boolean`):

Decode headline, description and CTA from text ads where available.

## Actor input object example

```json
{
  "mode": "scrape_ads",
  "advertisers": [
    "AR16478616112506863617"
  ],
  "maxResults": 10,
  "region": "anywhere",
  "datePreset": "LAST_7_DAYS",
  "formats": [],
  "platform": "ALL",
  "includeInactive": true,
  "maxAdsPerAdvertiser": 50,
  "decodeAdContent": true
}
```

# 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 = {
    "mode": "scrape_ads",
    "advertisers": [
        "AR16478616112506863617"
    ],
    "maxResults": 10,
    "region": "anywhere",
    "datePreset": "LAST_7_DAYS",
    "formats": [],
    "platform": "ALL",
    "includeInactive": true,
    "maxAdsPerAdvertiser": 50,
    "decodeAdContent": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("smacient/google-ads-library").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 = {
    "mode": "scrape_ads",
    "advertisers": ["AR16478616112506863617"],
    "maxResults": 10,
    "region": "anywhere",
    "datePreset": "LAST_7_DAYS",
    "formats": [],
    "platform": "ALL",
    "includeInactive": True,
    "maxAdsPerAdvertiser": 50,
    "decodeAdContent": True,
}

# Run the Actor and wait for it to finish
run = client.actor("smacient/google-ads-library").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 '{
  "mode": "scrape_ads",
  "advertisers": [
    "AR16478616112506863617"
  ],
  "maxResults": 10,
  "region": "anywhere",
  "datePreset": "LAST_7_DAYS",
  "formats": [],
  "platform": "ALL",
  "includeInactive": true,
  "maxAdsPerAdvertiser": 50,
  "decodeAdContent": true
}' |
apify call smacient/google-ads-library --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=smacient/google-ads-library",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Google Ads Library",
        "description": "Search any brand's Google ads by name or domain. Get structured ad data - formats, dates, decoded copy, and image URLs. Filter by country, platform, and date. Competitive intelligence at $1 per 1,000 ads.",
        "version": "0.0",
        "x-build-id": "uMf8f6IvHgMvR376d"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/smacient~google-ads-library/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-smacient-google-ads-library",
                "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/smacient~google-ads-library/runs": {
            "post": {
                "operationId": "runs-sync-smacient-google-ads-library",
                "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/smacient~google-ads-library/run-sync": {
            "post": {
                "operationId": "run-sync-smacient-google-ads-library",
                "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",
                "required": [
                    "advertisers"
                ],
                "properties": {
                    "mode": {
                        "title": "What do you want to do?",
                        "enum": [
                            "find_advertiser",
                            "scrape_ads"
                        ],
                        "type": "string",
                        "description": "Find Advertiser: search by brand name or domain to get the advertiser ID.\n\nScrape Ads: fetch all ads for a known advertiser ID, name, or domain.",
                        "default": "scrape_ads"
                    },
                    "advertisers": {
                        "title": "Brand names, domains, or advertiser IDs",
                        "type": "array",
                        "description": "Find Advertiser mode: enter brand names (e.g. 'Nike', 'Tanishq') or domains (e.g. 'nalli.com').\n\nScrape Ads mode: enter AR IDs (e.g. 'AR16478616112506863617'), brand names, or domains.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxResults": {
                        "title": "Max results per search",
                        "minimum": 1,
                        "maximum": 50,
                        "type": "integer",
                        "description": "How many advertiser matches to return per brand search. Only used in Find Advertiser mode.",
                        "default": 10
                    },
                    "region": {
                        "title": "Region",
                        "type": "string",
                        "description": "ISO alpha-2 country code (e.g. IN, US, GB) or 'anywhere' for global results.",
                        "default": "anywhere"
                    },
                    "datePreset": {
                        "title": "Date Range",
                        "enum": [
                            "ANY_TIME",
                            "LAST_7_DAYS",
                            "LAST_30_DAYS",
                            "TODAY",
                            "YESTERDAY"
                        ],
                        "type": "string",
                        "description": "Filter ads by when they were last shown.",
                        "default": "LAST_7_DAYS"
                    },
                    "formats": {
                        "title": "Ad Formats",
                        "type": "array",
                        "description": "Filter by format. Leave empty for all formats.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "TEXT",
                                "IMAGE",
                                "VIDEO"
                            ]
                        },
                        "default": []
                    },
                    "platform": {
                        "title": "Platform",
                        "enum": [
                            "ALL",
                            "SEARCH",
                            "SHOPPING",
                            "PLAY",
                            "MAPS",
                            "YOUTUBE"
                        ],
                        "type": "string",
                        "description": "Filter by Google platform.",
                        "default": "ALL"
                    },
                    "includeInactive": {
                        "title": "Include Inactive Ads",
                        "type": "boolean",
                        "description": "Include ads last shown within 14 days.",
                        "default": true
                    },
                    "maxAdsPerAdvertiser": {
                        "title": "Max Ads Per Advertiser",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Maximum ads to fetch per advertiser. 0 = unlimited.",
                        "default": 50
                    },
                    "decodeAdContent": {
                        "title": "Decode Ad Content",
                        "type": "boolean",
                        "description": "Decode headline, description and CTA from text ads where available.",
                        "default": true
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```