# Google Ads Transparency Ad

## Overview

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

## Description

Get one Google Ads Transparency creative by URL: dates, impressions, platforms, regions, and the text read from the preview image (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/ad' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### WebAPI Group creative in France

```json
{
  "url": "https://adstransparency.google.com/advertiser/AR10904289436120383489/creative/CR10927354991047868417?region=FR",
  "format": "text",
  "regions": [
    {
      "region": "FR",
      "platforms": [],
      "last_shown": null,
      "first_shown": null,
      "region_code": 2250,
      "impressions_max": null,
      "impressions_min": null
    }
  ],
  "video_id": null,
  "image_url": null,
  "platforms": [],
  "last_shown": null,
  "variations": [],
  "creative_id": "CR10927354991047868417",
  "first_shown": null,
  "image_width": null,
  "preview_url": null,
  "image_height": null,
  "advertiser_id": "AR10904289436120383489",
  "creative_text": null,
  "last_shown_at": null,
  "first_shown_at": null,
  "advertiser_name": "WebAPI Group",
  "impressions_max": null,
  "impressions_min": null
}
```

## Documentation

## Overview
Read one creative from the Google Ads Transparency Center. Pass the creative URL returned by search (`/advertiser/AR.../creative/CR...`). **2 credits** per call.

The response includes the advertiser, format, dates, impression range, platforms, regions, and `creative_text` read from the preview image.

## Quickstart
```
GET https://api.piloterr.com/v2/googleadstransparency/ad?query=https://adstransparency.google.com/advertiser/AR10904289436120383489/creative/CR10927354991047868417&region=FR
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Creative URL: `https://adstransparency.google.com/advertiser/AR.../creative/CR...` |
| `region` | string | no | ISO alpha-2. When the creative was shown there, that region is listed first |

## Response fields
| Field | Type | Description |
|---|---|---|
| `creative_id` / `advertiser_id` | string | `CR...` and `AR...` |
| `advertiser_name` | string \| null | Name on the creative. `null` when Google does not send it |
| `url` | string | Creative URL |
| `format` | string | `text`, `image`, or `video` |
| `image_url` / `image_width` / `image_height` | string \| number \| null | Preview image |
| `preview_url` | string \| null | Image, or the `content.js` preview |
| `video_id` | string \| null | YouTube id when the preview carries one |
| `first_shown_at` / `last_shown_at` | string \| null | ISO 8601. On a creative, `last_shown_at` is the last impression time |
| `first_shown` / `last_shown` | string \| null | `YYYY-MM-DD` |
| `impressions_min` / `impressions_max` | integer \| null | Google's impression range |
| `variations[]` | array | Preview images for the creative |
| `platforms[]` | array | `platform` (`search`, `youtube`, `play`, `maps`, `shopping`), `platform_code`, and impression bounds |
| `regions[]` | array | `region`, `region_code`, dates, impressions, and per-region platforms. The requested region is first |
| `creative_text` | object \| null | Text read from the preview image |
| `creative_text.business_name` | string \| null | Name above the display URL |
| `creative_text.display_url` | string \| null | URL shown on the ad (`www.` or `http`) |
| `creative_text.headline` | string \| null | Title under the URL, including a wrapped second line |
| `creative_text.description` | string \| null | Paragraph directly under the title |
| `creative_text.lines` | array | Every line read, in order, including `Sponsored` |

## Notes
- `creative_text` is filled from the preview image. A video preview that is a script, not an image, stays `null`.
- A bare domain such as `adidas.com` above `www.adidas.com/` is the business name. The `www.` line is the display URL.
- Sitelinks and buttons that sit below the paragraph stay in `lines` and are not copied into `description`.
- A domain or a search URL passed here returns `400`.

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing query, or a URL that is not a creative |
| `404` | Creative not found |
| `500` | The Transparency request failed |

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

## Main use cases
- Open a search card and read the headline, description, and display URL
- Compare impression ranges and platforms for one creative across countries
- Keep the raw `lines` when the layout is a banner rather than a search ad