Return the Google Ad Library ads for a single advertiser, given an advertiser id, an Ad Library advertiser URL, or an advertiser name. Accepts the same region, format, surface and date filters as a brand search. Use this rather than search-ads once you hold an advertiser id: it skips the name-resolution step, so there is no risk of the wrong registered advertiser being matched.

POST /advertiser-ads Ads

https://api.fetchlayer.dev/google-ad-library/advertiser-ads

OpenAPI JSON

Headers

Authorization string required

Bearer token — your FetchLayer API key.

Parameters

advertiser string required

Advertiser id, an Ad Library advertiser URL, or an advertiser name. An id or URL is exact; a name is resolved first and may match the wrong advertiser.

region string optional

Two-letter country code, or ANYWHERE. (default: ANYWHERE)

regions string[] optional

Several countries at once (max 20). Overrides region.

adFormat string optional

text, image, or video. Google publishes one format per ad.

surfaces string[] optional

Restrict to the Google surfaces the ad ran on: search, youtube, shopping, maps, play.

shownAfter string optional

Only ads shown on or after this YYYY-MM-DD date.

shownBefore string optional

Only ads shown on or before this YYYY-MM-DD date.

limit number optional

Maximum ads returned (max 2000), or -1 for everything available. (default: 30)

pages number optional

Pages of results to collect in one request (max 100), or -1 for the maximum allowed.

cursor string optional

Resume from a previous response's nextCursor.

delayMs number optional

Milliseconds to wait between pages (max 30000).

sortBy string optional

first_shown, days_shown, or none.

sortDirection string optional

asc or desc.

Response Fields

advertiser-ads

Get every ad one advertiser runs

advertiserId string

The resolved advertiser id.

advertiserName string

The advertiser name Google publishes.

ads object[]

The matching ads.

ads[].adId string

Ad id — the handle for ad-detail and ad-media, which also need the advertiserId.

ads[].adLibraryUrl string

Public Google Ad Library permalink for this ad.

ads[].advertiserId string

Advertiser running the ad.

ads[].advertiserName string

Advertiser name as Google publishes it.

ads[].format string

text, image, or video.

ads[].firstShownDate string

First day the ad was seen, as YYYY-MM-DD.

ads[].daysShown number

Days the ad was actually shown. Approximate, and lower than the span between its first and last day whenever the ad paused.

ads[].domain string

The advertiser's website, when Google reports it.

ads[].regions object[]

Countries the ad ran in with the last date seen in each. Populated on a single-ad lookup; empty on a listing.

ads[].variations object[]

Each version of the creative. Google publishes ads as pictures of the rendered ad, not as separate headline and body text — see the note on ad-detail.

ads[].variationCount number

How many creative versions the ad carries.

ads[].previewImageUrl string

First picture of the ad across its versions, for a quick preview.

filters object

The filters this request actually ran with, after defaults were applied.

adCount number

Number of ads in this response.

approximateTotal object

Roughly how many ads match in total, as a { min, max } range. Google publishes counts as ranges, never exact figures.

pagesScraped number

Pages actually walked. Each page counts as one request against your plan.

pagesRequested number

Pages the request asked for, which can exceed pagesScraped when the listing ran out.

nextCursor string

Pass back as cursor to continue, or null when the listing is exhausted.

hasNextPage boolean

Whether more results are available beyond this response.

notes string[]

Caveats about this particular result — a walk that stopped short, or a listing that may be incomplete. Read it before treating a result set as the whole picture.

Request

curl -X POST "https://api.fetchlayer.dev/google-ad-library/advertiser-ads" \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"advertiser":"AR01234567890123456789","region":"US","pages":3}'

Response

{
  "advertiserId": "AR01234567890123456789",
  "advertiserName": "Nike, Inc.",
  "adCount": 84,
  "pagesScraped": 3,
  "pagesRequested": 3,
  "hasNextPage": true,
  "nextCursor": "eyJwYWdlIjozfQ",
  "ads": [],
  "notes": []
}

{
  "error": "Invalid API key"
}