# Google Ads Transparency Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/googleadstransparency/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/googleadstransparency-search |

## Description

Search the Google Ads Transparency Center by domain, advertiser, region, format, platform, and date. Returns creative cards and pagination (2 credits).

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/googleadstransparency/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### WebAPI Group advertiser in France

```json
{
  "results": [
    {
      "url": "https://adstransparency.google.com/advertiser/AR10904289436120383489/creative/CR10927354991047868417?region=FR",
      "domain": "webapi.group",
      "format": "text",
      "image_url": null,
      "creative_id": "CR10927354991047868417",
      "image_width": null,
      "preview_url": null,
      "image_height": null,
      "advertiser_id": "AR10904289436120383489",
      "last_shown_at": null,
      "first_shown_at": null,
      "advertiser_name": "WebAPI Group"
    }
  ],
  "pagination": {
    "next": null,
    "page": 1,
    "per_page": 40,
    "total_pages": null,
    "total_results": null,
    "total_results_max": null,
    "total_results_min": null
  }
}
```

## Documentation

## Overview
Search the Google Ads Transparency Center. Pass a **domain** (`webapi.group`), an **advertiser name** (`WebAPI Group`), an **advertiser id** (`AR10904289436120383489`), or a **full Transparency URL**. **2 credits** per call.

Each card includes the creative id, advertiser, format, preview image, and the first and last time the ad was shown. Pagination is `{ results, pagination }`. Open `results[].url` with the ad endpoint to read the creative, including the text on the image.

## Quickstart
```
GET https://api.piloterr.com/v2/googleadstransparency/search?query=webapi.group&region=FR
GET https://api.piloterr.com/v2/googleadstransparency/search?query=https://adstransparency.google.com/advertiser/AR10904289436120383489&region=FR
GET https://api.piloterr.com/v2/googleadstransparency/search?query=AR10904289436120383489&region=FR
GET https://api.piloterr.com/v2/googleadstransparency/search?query=WebAPI%20Group&region=FR
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Domain name (`webapi.group`), advertiser name, `AR` id, or full advertiser URL (`/advertiser/AR...`) |
| `domain` | string | no | Domain filter. Overrides the domain parsed from `query` |
| `advertiser_id` | string | no | Advertiser id (`AR` followed by digits) |
| `region` | string | no | ISO alpha-2 (`FR`, `US`), `anywhere`, or a region code (`2250`, `250`). Omitted means no region filter |
| `format` | string | no | `text`, `image`, or `video` |
| `platform` | string | no | Comma-separated: `play`, `maps`, `search`, `shopping`, `youtube` |
| `preset_date` | string | no | `today`, `yesterday`, `last_7_days`, `last_30_days`. French labels such as `7 derniers jours` are accepted |
| `start_date` / `end_date` | string | no | Inclusive dates, `YYYY-MM-DD` or `YYYYMMDD` |
| `topic` | string | no | `commercial` (default), `political`, `shopping`, `travel_hotel`, `local_services` |
| `page` | integer | no | Page number, 1 to 20. Default: `1` |
| `per_page` | integer | no | Page size, 1 to 100. Default: `40` |
| `cursor` | string | no | Opaque cursor from `pagination.next`. Required to reproduce a later page exactly |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results[]` | array | Creative cards |
| `results[].creative_id` / `advertiser_id` | string | `CR...` and `AR...` |
| `results[].advertiser_name` | string \| null | Name shown by Google |
| `results[].domain` | string \| null | Matched domain |
| `results[].url` | string | Creative URL. Pass it to the ad endpoint |
| `results[].format` | string | `text`, `image`, or `video` |
| `results[].image_url` / `image_width` / `image_height` | string \| number \| null | Preview image |
| `results[].preview_url` | string \| null | Image, or a `content.js` preview when Google does not send an image |
| `results[].first_shown_at` / `last_shown_at` | string \| null | ISO 8601 |
| `pagination.page` / `per_page` | integer | Current page and page size |
| `pagination.total_results` / `total_pages` | integer \| null | Set when Google reports an exact count |
| `pagination.total_results_min` / `total_results_max` | integer \| null | Count range. Equal values mean the total is exact |
| `pagination.next` | string \| null | Next page URL, or `null` on the last page |

## Notes
- A bare name such as `WebAPI Group` is resolved to one advertiser. A bare brand that matches a domain, such as `webapi`, is resolved to that domain.
- `WebAPI Group` is not `webapi.group`. The name lookup and the domain lookup are different searches.
- Dates you send are inclusive. `start_date` and `end_date` on the same day return that day.
- `format`, `platform`, and `topic` are lowercase in the response.
- A creative URL passed to search returns `400`. Use the ad endpoint.
- An empty result returns `404`, not an empty `200`.

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing target, creative URL, unknown region, format, platform, topic, or date |
| `404` | No creatives for these filters |
| `500` | The Transparency request failed |

## Related endpoints
- [Google Ads Transparency Ad](https://www.piloterr.com/library/googleadstransparency-ad)

## Main use cases
- List every creative a domain has run in one country
- Split text, image, and video ads, then open each card
- Compare today, the last 7 days, and the last 30 days