Google APIadstransparency.google.com ↗
Search Google Ads Transparency Center for advertisers and ad creatives. Extract ad copy, formats, date ranges, regions, and direct ad links via 3 endpoints.
What is the Google API?
This API provides structured access to Google Ads Transparency Center data across 3 endpoints, letting you search advertisers by name, retrieve their ad creatives with text and image URLs, and fetch per-creative detail including regions served and date ranges. The search_ads endpoint resolves an advertiser name to an ID automatically and returns paginated results with fields like ad_text, first_shown, last_shown, format, and ad_link — no manual lookup required.
curl -X GET 'https://api.parse.bot/scraper/d6e80fcd-e869-4af2-a31b-71a4ce7ca355/search_advertisers?limit=5&query=Nike®ion=US' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace adstransparency-google-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Google Ads Transparency Center — discover advertisers and inspect their ad creatives."""
from parse_apis.google_ads_transparency_center_api import (
GoogleAdsTransparency, AdFormat, AdNotFound
)
client = GoogleAdsTransparency()
# Search for advertisers by name — single-page result, capped by limit.
for advertiser in client.advertisers.search(query="Nike", limit=5):
print(advertiser.name, advertiser.ad_count, advertiser.country)
# Drill into one advertiser's ads via the sub-resource.
advertiser = client.advertisers.search(query="Apple", limit=1).first()
if advertiser:
for ad in advertiser.ads.list(region="US", limit=3):
print(ad.creative_id, ad.format, ad.last_shown)
# Get full details on the first ad.
ad = advertiser.ads.list(limit=1).first()
if ad:
try:
detail = ad.details()
print(detail.advertiser_legal_name, detail.regions, detail.ad_link)
except AdNotFound as exc:
print(f"Ad removed: {exc.creative_id}")
print("exercised: advertisers.search / advertiser.ads.list / ad.details")
Search for advertisers by name. Returns a list of matching advertisers with their IDs, countries, and ad counts. Use the advertiser_id from results to navigate to their ads via the ads sub-resource.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of advertiser suggestions to return (max 20) |
| queryrequired | string | Advertiser name to search for |
| region | string | 2-letter country code (e.g. US, GB, DE, FR, IT, ES, JP, BR, IN, CA, AU) |
{
"type": "object",
"fields": {
"query": "string - the search query used",
"total": "integer - number of advertisers returned",
"region": "string - 2-letter country code used for filtering",
"advertisers": "array of advertiser objects with name, advertiser_id, country, and ad_count"
},
"sample": {
"data": {
"query": "Nike",
"total": 1,
"region": "US",
"advertisers": [
{
"name": "Nike, Inc.",
"country": "US",
"ad_count": "10000",
"advertiser_id": "AR16735076323512287233"
}
]
},
"status": "success"
}
}About the Google API
Advertiser Search
The search_advertisers endpoint accepts a query string and an optional region (2-letter country code) to return up to 20 matching advertiser records. Each result includes advertiser_id, country, ad_count, and the canonical name. The advertiser_id values returned here are the inputs that power the other two endpoints, so this is the natural starting point when you know only a brand name.
Ad Creative Search and Pagination
The search_ads endpoint accepts either a query string or a direct advertiser_id. When given a name, it selects the best match by highest ad_count, so you can skip a manual search_advertisers call for common cases. Each ad record in the ads array includes creative_id, format (image, text, or video), ad_text, ad_image_url, first_shown, last_shown, and ad_link. Pages are controlled by limit (up to 40) and cursor-based page_token / next_page_token — iterate through next_page_token values until it returns null to exhaust a full advertiser history.
Ad Detail
The get_ad_details endpoint takes a creative_id and advertiser_id and returns the full record for a single creative: all ad variants via ad_preview_urls, every regions country code where the ad ran, the advertiser's legal name, and both first_shown and last_shown dates. This is the right call when you need geographic distribution or variant previews beyond what the search listing provides.
The Google API is a managed, monitored endpoint for adstransparency.google.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when adstransparency.google.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official adstransparency.google.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track competitor ad copy changes over time using
first_shownandlast_showndate fields fromsearch_ads. - Map geographic ad distribution for a brand by collecting
regionsarrays fromget_ad_details. - Build an advertiser directory by iterating
search_advertisersacross multiple markets with differentregionvalues. - Monitor when specific creatives go live or stop running by polling
last_shownfor a fixedcreative_id. - Audit ad formats (image, text, video) used by a category of advertisers via the
formatfield insearch_adsresults. - Collect direct ad preview links using
ad_linkandad_preview_urlsfor manual review workflows. - Research political or sensitive-category advertisers by querying known brand names and paginating their full creative history.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Google Ads Transparency Center have an official developer API?+
How does pagination work in the `search_ads` endpoint?+
next_page_token field. Pass that value as the page_token parameter on your next request, keeping the same advertiser_id or query and region. When next_page_token is null, you have reached the last page. The limit parameter controls page size up to a maximum of 40 ads per call.Does `search_ads` cover all regions, or is filtering required?+
region parameter is optional. Omitting it returns ads without regional filtering, but the transparency center's coverage varies — some advertisers have ads only in specific markets. Passing a region code narrows results to ads shown in that country. If an advertiser ran ads in multiple regions, you may see different creative sets by querying each region separately.Does the API expose spend data, impression counts, or demographic targeting breakdowns?+
Can I retrieve ads for an advertiser I find only by partial name?+
search_advertisers endpoint performs a name search and returns multiple candidates with their ad_count values, so you can inspect matches before committing to one advertiser_id. Alternatively, passing a partial name directly to search_ads will automatically select the candidate with the highest ad_count, which is often the intended advertiser but may not always be the right one for uncommon brand names.