Google ad API

Get a Google ad's details

curl --request POST \
  --url https://api.stophy.dev/v1/google/ads/ad \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "adUrl": "<string>",
  "adId": "<string>",
  "advertiserId": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({adUrl: '<string>', adId: '<string>', advertiserId: '<string>'})
};

fetch('https://api.stophy.dev/v1/google/ads/ad', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.stophy.dev/v1/google/ads/ad"

payload = {
    "adUrl": "<string>",
    "adId": "<string>",
    "advertiserId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "data": {
    "adUrl": "<string>",
    "advertiserUrl": "<string>",
    "format": "text",
    "variations": [
      {
        "previewUrl": "<string>",
        "imageUrl": "<string>",
        "videoUrl": "<string>"
      }
    ],
    "regions": [
      {
        "country": "<string>",
        "firstShownAt": "2023-11-07T05:31:56Z",
        "lastShownAt": "2023-11-07T05:31:56Z",
        "impressionsMin": 0,
        "impressionsMax": 0
      }
    ],
    "targetingIncluded": [
      "<string>"
    ],
    "targetingExcluded": [
      "<string>"
    ],
    "adId": "<string>",
    "advertiserId": "<string>",
    "advertiserName": "<string>",
    "domain": "<string>",
    "firstShownAt": "2023-11-07T05:31:56Z",
    "lastShownAt": "2023-11-07T05:31:56Z",
    "daysShown": 0,
    "previewUrl": "<string>",
    "imageUrl": "<string>",
    "advertiserCountry": "<string>",
    "advertiserIsVerified": true,
    "paidBy": "<string>",
    "impressionsMin": 0,
    "impressionsMax": 0
  },
  "creditsUsed": 123,
  "requestId": "<string>"
}

{
  "success": false,
  "error": {
    "code": "cliSessionCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123,
    "requiredCredits": 123,
    "availableCredits": 123,
    "billingUrl": "https://stophy.dev/billing"
  }
}

{
  "success": false,
  "error": {
    "code": "cliSessionCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123,
    "requiredCredits": 123,
    "availableCredits": 123,
    "billingUrl": "https://stophy.dev/billing"
  }
}

POST

google

ads

Get a Google ad's details

curl --request POST \
  --url https://api.stophy.dev/v1/google/ads/ad \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "adUrl": "<string>",
  "adId": "<string>",
  "advertiserId": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({adUrl: '<string>', adId: '<string>', advertiserId: '<string>'})
};

fetch('https://api.stophy.dev/v1/google/ads/ad', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.stophy.dev/v1/google/ads/ad"

payload = {
    "adUrl": "<string>",
    "adId": "<string>",
    "advertiserId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "data": {
    "adUrl": "<string>",
    "advertiserUrl": "<string>",
    "format": "text",
    "variations": [
      {
        "previewUrl": "<string>",
        "imageUrl": "<string>",
        "videoUrl": "<string>"
      }
    ],
    "regions": [
      {
        "country": "<string>",
        "firstShownAt": "2023-11-07T05:31:56Z",
        "lastShownAt": "2023-11-07T05:31:56Z",
        "impressionsMin": 0,
        "impressionsMax": 0
      }
    ],
    "targetingIncluded": [
      "<string>"
    ],
    "targetingExcluded": [
      "<string>"
    ],
    "adId": "<string>",
    "advertiserId": "<string>",
    "advertiserName": "<string>",
    "domain": "<string>",
    "firstShownAt": "2023-11-07T05:31:56Z",
    "lastShownAt": "2023-11-07T05:31:56Z",
    "daysShown": 0,
    "previewUrl": "<string>",
    "imageUrl": "<string>",
    "advertiserCountry": "<string>",
    "advertiserIsVerified": true,
    "paidBy": "<string>",
    "impressionsMin": 0,
    "impressionsMax": 0
  },
  "creditsUsed": 123,
  "requestId": "<string>"
}

{
  "success": false,
  "error": {
    "code": "cliSessionCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123,
    "requiredCredits": 123,
    "availableCredits": 123,
    "billingUrl": "https://stophy.dev/billing"
  }
}

{
  "success": false,
  "error": {
    "code": "cliSessionCompleted",
    "message": "<string>",
    "retryable": true,
    "requestId": "<string>",
    "retryAfterSeconds": 123,
    "requiredCredits": 123,
    "availableCredits": 123,
    "billingUrl": "https://stophy.dev/billing"
  }
}

Returns a Google ad’s details. The ad is identified by its URL or ID.

Request

Exactly one of adUrl or adId is required. A request that sets both, or none, fails with invalidRequest.

import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.ads.ad({ adUrl: "https://adstransparency.google.com/advertiser/AR18378488041124659201/creative/CR12345678901234567890" });
console.log(result.data);

from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.ads.ad(ad_url="https://adstransparency.google.com/advertiser/AR18378488041124659201/creative/CR12345678901234567890")
print(result["data"])

curl -X POST https://api.stophy.dev/v1/google/ads/ad \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"adUrl":"https://adstransparency.google.com/advertiser/AR18378488041124659201/creative/CR12345678901234567890"}'

stophy google ads ad --adUrl https://adstransparency.google.com/advertiser/AR18378488041124659201/creative/CR12345678901234567890

Response

If successful, the response body contains the standard envelope. data contains the ad’s advertiser, format and creative, and the countries it ran in. The following example is a real response, truncated: each list shows one item and long strings are cut.

{
  "success": true,
  "data": {
    "adId": "CR00462730911658541057",
    "adUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR00462730911658541057",
    "advertiserId": "AR16735076323512287233",
    "advertiserName": "Nike, Inc.",
    "advertiserUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233",
    "format": "text",
    "lastShownAt": "2026-10-05T20:27:35.000Z",
    "imageUrl": "https://tpc.googlesyndication.com/archive/simgad/5743239130676952852",
    "advertiserCountry": "US",
    "advertiserIsVerified": true,
    "paidBy": "Nike, Inc.",
    "variations": [
      {
        "imageUrl": "https://tpc.googlesyndication.com/archive/simgad/5743239130676952852"
      }
    ],
    "regions": [
      {
        "country": "US",
        "lastShownAt": "2026-09-01T00:00:00.000Z"
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}

Field	Type	Description
`lastShownAt`	string (ISO 8601)	The last day the ad was shown.
`paidBy`	string	The entity that paid for the ad.

For every field, see the response schema on this page.

Optional parameters

Parameter	Type	Description
`advertiserId`	string	Advertiser id, such as `AR18378488041124659201`. Requires `adId`. A link already has it.

Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

Pagination

This method is not paginated. A single request returns the complete result.

Google ads search: Accepts the advertiserId as advertiser. Searches ads in the Google ads library.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

adUrl

string

Link to the Google Ads Transparency ad, like https://adstransparency.google.com/advertiser/AR18378488041124659201/creative/CR12345678901234567890. Send this or adId.

adId

string

Google Ads Transparency ad id, like CR12345678901234567890. Send this or adUrl.

advertiserId

string

Advertiser id like AR18378488041124659201. Send it with adId; adUrl already has it.

Response

The data, and the credits this call used.

success

any

required

data

object

required

Show child attributes

creditsUsed

integer

required

requestId

string

required

Using the API

Catalog

Account

Search and AI answers

Video

Social

Places and travel

Jobs

Shopping

Apps

Real estate

Ads

Request

Response

Optional parameters

Billing

Authorizations

Body

Response

​Request

​Response

​Optional parameters

​Billing

​Pagination

​Related methods

Authorizations

Body

Response

Request

Response

Optional parameters

Billing

Pagination

Related methods