Google Ad Library Company Ads
Google Ads Transparency Center creative inventory can be enumerated from a selected advertiser ID or company domain and narrowed by public query filters. Creative identifiers and source URLs are the most dependable list-level values because per-ad detail enrichment is disabled for this operation.
Features
- Advertiser or domain starting pointProvide at least one Google advertiser ID or company domain; when both are present, the upstream source defines how they intersect.
- Validated inventory filtersNarrow the public creative index by topic, region, date window, Google surface, or text, image, and video format values.
- Cursor-based collectionFollow provider cursors in 40-record pages and stop at the requested 40–2,000 result limit, the final page, an empty page, or an invalid repeated cursor.
- Stable ad recordsReturn the shared normalized ad shape while preserving null and empty list-level detail fields instead of inventing creative enrichment.
Parameters
| Parameters | Required | Description |
|---|---|---|
domain | Required (at least one) | Company website domain such as lululemon.com. At least one of domain or advertiser_id is required; domain matching can span more than one advertiser record. |
advertiser_id | Required (at least one) | Google Transparency Center advertiser identifier, typically beginning with AR. At least one of advertiser_id or domain is required. |
topic | Optional | Optional public source topic filter: all or political. Filter behavior and coverage remain source-defined. |
region | Optional | Optional region code such as US, forwarded as public query context rather than a complete targeting definition. |
start_date | Optional | Optional inclusive source date filter in YYYY-MM-DD format. It cannot be later than end_date when both dates are supplied. |
end_date | Optional | Optional source date filter in YYYY-MM-DD format. It cannot be earlier than start_date when both dates are supplied. |
platform | Optional | Optional Google surface: google_maps, google_play, google_search, google_shopping, or youtube. |
format | Optional | Optional creative format: text, image, or video. Similar creative variations can still appear as separate records. |
results_limit | Optional | Maximum stored creative records. Defaults to 40 and accepts integers from 40 through 2,000 in multiples of 40. |
How to Use
Submit one structured advertiser inventory request, follow its asynchronous task, and use returned creative URLs for selective detail retrieval.
- Choose an advertiser_id or domain; add only filters that belong to the comparison or collection question.
- Set results_limit to 40–2,000 in multiples of 40, then POST the request to /v1/google-ad-library/company-ads.
- Poll /v1/tasks/{task_id} until the task succeeds or fails, then page through stored task results if needed.
- Treat IDs and creative URLs as index records; send selected URLs to the separate ad detail operation when richer fields are required.
curl -X POST "https://api.socq.ai/v1/google-ad-library/company-ads" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"advertiser_id":"AR01614014350098432001","region":"US","format":"video","results_limit":80}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and select creative URLs for detail retrievalBest Use Cases
- Build a selective detail queue: Enumerate creative IDs and public URLs for one advertiser, then choose only relevant records for richer detail requests.
- Compare observable format mixes: Count returned text, image, and video index records across consistent identifiers, filters, limits, and collection windows.
- Review disclosed delivery windows: Identify creative records returned under comparable date, region, topic, or Google-surface filters without treating them as private targeting data.
Pro Tips
- Prefer a verified advertiser_id over a broad domain when the intended Transparency Center entity is already known.
- Keep identifiers, filters, results_limit, and collection dates consistent when comparing creative inventories over time.
- Expect text, dates, destination, impressions, and media to be null or empty at list level because get_ad_details is always false.
- Treat a successful empty result as no usable creative under the submitted identifiers and filters at that time, not proof that the company never advertised.
Related APIs
Use these APIs when you need a different type of public Google Ad Library data.
- Google Ad Library Ad API — Retrieve one known public Transparency Center creative by URL with advertiser, copy, media, delivery, region, format, destination, and impression fields.
- Google Ad Library Advertiser Search API — Discover public Transparency Center advertiser candidates by query and optional region with identity, website, logo, region, and available ad-count fields.