{"id":"9b995d7f-f598-4dfa-986f-3fea55bfc34c","slug":"adstransparency-google-com-api","name":"adstransparency.google.com API","description":"Search for advertisers and their advertisements to view ad copy, creative formats, advertiser details, geographic targeting, and active date ranges across Google's ad ecosystem. Access detailed information about specific ads including direct links and comprehensive advertiser profiles all in one place.","front_facing_description":"Search for advertisers and their advertisements to view ad copy, creative formats, advertiser details, geographic targeting, and active date ranges across Google's ad ecosystem. Access detailed information about specific ads including direct links and comprehensive advertiser profiles all in one place.","source_url":"https://adstransparency.google.com/?region=US","is_authenticated":false,"canonical_scraper_id":"d6e80fcd-e869-4af2-a31b-71a4ce7ca355","apis":[{"method":"GET","endpoint_name":"search_advertisers","description":"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.","input_params":{"limit":{"type":"integer","required":false,"description":"Maximum number of advertiser suggestions to return (max 20)","default":10,"domain":{"kind":"enum","values":["5","10","20"],"generator":{"type":"enum_pick","strategy":"first"}}},"query":{"type":"string","required":true,"description":"Advertiser name to search for","domain":{"kind":"open","generator":{"type":"static","value":"Nike"}}},"region":{"type":"string","required":false,"description":"2-letter country code (e.g. US, GB, DE, FR, IT, ES, JP, BR, IN, CA, AU)","default":"US","domain":{"kind":"open","generator":{"type":"static","value":"US"}}}},"return_schema":{"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"}},"initiates_session":false,"price":2,"verification":{"assertions":[{"path":"$.status","op":"equals","value":"success"},{"path":"$.data.advertisers","op":"array_min_len","value":1}],"empty_is_valid":false,"recipe_version":1}},{"method":"GET","endpoint_name":"search_ads","description":"Search for ad creatives by advertiser name or advertiser ID. Automatically finds the best-matching advertiser (by ad count) when searching by name. Supports cursor-based pagination via next_page_token. Returns ad summaries including format, text, image URL, and date ranges.","input_params":{"limit":{"type":"integer","required":false,"description":"Number of ads to return per page (max 40)","default":20,"domain":{"kind":"enum","values":["10","5","20"],"generator":{"type":"enum_pick","strategy":"first"}}},"query":{"type":"string","required":false,"description":"Advertiser name to search for. Either query or advertiser_id is required.","domain":{"kind":"open","generator":{"type":"static","value":"Apple"}}},"region":{"type":"string","required":false,"description":"2-letter country code to filter ads by region","default":"US","domain":{"kind":"open","generator":{"type":"static","value":"US"}}},"page_token":{"type":"string","required":false,"description":"Pagination token from a previous response's next_page_token field"},"advertiser_id":{"type":"string","required":false,"description":"Direct advertiser ID (e.g. AR16735076323512287233). Skips advertiser lookup when provided.","domain":{"kind":"derived","generator":{"path":"$.data.advertisers[0].advertiser_id","type":"derived","from_endpoint":"search_advertisers"}}}},"return_schema":{"type":"object","fields":{"ads":"array of ad summary objects with creative_id, format, ad_text, ad_image_url, first_shown, last_shown, ad_link","query":"string - the search query used","total":"integer - number of ads returned in this page","region":"string - 2-letter country code used","advertiser_id":"string - resolved advertiser ID","advertiser_name":"string - resolved advertiser name","next_page_token":"string or null - token for fetching the next page"},"sample":{"data":{"ads":[{"format":"image","ad_link":"https://adstransparency.google.com/advertiser/AR15992851274060005377/creative/CR09465060480939720705","ad_text":"<img src=\"https://tpc.googlesyndication.com/archive/simgad/3020873071780687244\" height=\"200\" width=\"381\">","last_shown":"2026-06-11","creative_id":"CR09465060480939720705","first_shown":"2025-09-22","ad_image_url":"https://tpc.googlesyndication.com/archive/simgad/3020873071780687244","advertiser_id":"AR15992851274060005377","ad_preview_url":"","advertiser_name":"Apple Inc."}],"query":"Apple","total":1,"region":"US","advertiser_id":"AR15992851274060005377","advertiser_name":"Apple Inc.","next_page_token":"CgoAP7zmsDfKnUITEhD5Iw9MN7WRQPO6AyAAAAAAGgn8+HNT+C9uFC8="},"status":"success"}},"initiates_session":false,"price":5,"verification":{"assertions":[{"path":"$.status","op":"equals","value":"success"},{"path":"$.data.ads","op":"exists"}],"empty_is_valid":true,"recipe_version":1}},{"method":"GET","endpoint_name":"get_ad_details","description":"Get detailed information about a specific ad creative, including all ad variants, regions where it was shown, and advertiser legal name. Requires both advertiser_id and creative_id, typically obtained from a search_ads result.","input_params":{"region":{"type":"string","required":false,"description":"2-letter country code","default":"US","domain":{"kind":"open","generator":{"type":"static","value":"US"}}},"creative_id":{"type":"string","required":true,"description":"Creative ID (e.g. CR02693044172193005569)","domain":{"kind":"derived","generator":{"path":"$.data.ads[0].creative_id","type":"derived","from_endpoint":"search_ads"}}},"advertiser_id":{"type":"string","required":true,"description":"Advertiser ID (e.g. AR16735076323512287233)","domain":{"kind":"derived","generator":{"path":"$.data.advertiser_id","type":"derived","from_endpoint":"search_ads"}}}},"return_schema":{"type":"object","fields":{"format":"string - ad format (image, text, or video)","ad_link":"string - direct link to view the ad on Google Ads Transparency Center","ad_text":"string - ad content text or HTML markup","regions":"array of 2-letter country codes where the ad was shown","last_shown":"string - date the ad was last shown (YYYY-MM-DD)","creative_id":"string - creative ID","first_shown":"string - date the ad was first shown (YYYY-MM-DD), may be empty","ad_image_url":"string - direct URL to ad image if applicable","advertiser_id":"string - advertiser ID","ad_preview_urls":"array of preview URLs for the ad creative","advertiser_name":"string - advertiser display name","advertiser_country":"string - 2-letter country code of the advertiser","advertiser_legal_name":"string - legal name of the advertiser"},"sample":{"data":{"format":"image","ad_link":"https://adstransparency.google.com/advertiser/AR15992851274060005377/creative/CR09465060480939720705","ad_text":"<img src=\"https://tpc.googlesyndication.com/archive/simgad/3020873071780687244\" height=\"200\" width=\"381\">","regions":["US","GB","DE"],"last_shown":"2026-06-11","creative_id":"CR09465060480939720705","first_shown":"","ad_image_url":"https://tpc.googlesyndication.com/archive/simgad/3020873071780687244","advertiser_id":"AR15992851274060005377","ad_preview_urls":[],"advertiser_name":"Apple Inc.","advertiser_country":"US","advertiser_legal_name":"Apple Inc."},"status":"success"}},"initiates_session":false,"price":10,"verification":{"assertions":[{"path":"$.status","op":"equals","value":"success"},{"path":"$.data.creative_id","op":"not_null"}],"empty_is_valid":false,"recipe_version":1}}],"sample_inputs":{"search_ads":{"limit":"5","query":"Apple","region":"US","advertiser_id":"AR18100938063227125761"},"get_ad_details":{"region":"US","creative_id":"CR01865271294124097537","advertiser_id":"AR15992851274060005377"},"search_advertisers":{"limit":"5","query":"Nike","region":"US"}},"prefill_inputs":{"search_advertisers":{"limit":"5","query":"Nike","region":"US"},"search_ads":{"limit":"10","query":"Apple","region":"US"},"get_ad_details":{"region":"US"}},"last_verified_at":"2026-10-29T22:00:26.052344+00:00","endpoint_health":[{"endpoint_name":"search_advertisers","status":"healthy","last_checked_at":"2026-10-29T22:00:26.052344+00:00","last_verified_at":"2026-10-29T22:00:26.052344+00:00","recent_runs":[{"at":"2026-10-29T22:00:26.052344+00:00","status":"healthy"},{"at":"2026-10-22T19:04:25.738171+00:00","status":"healthy"},{"at":"2026-10-15T10:01:52.887774+00:00","status":"healthy"},{"at":"2026-10-08T10:00:53.153372+00:00","status":"healthy"},{"at":"2026-10-01T09:03:53.799784+00:00","status":"healthy"}]},{"endpoint_name":"search_ads","status":"healthy","last_checked_at":"2026-10-29T22:00:26.052344+00:00","last_verified_at":"2026-10-29T22:00:26.052344+00:00","recent_runs":[{"at":"2026-10-29T22:00:26.052344+00:00","status":"healthy"},{"at":"2026-10-22T19:04:25.738171+00:00","status":"healthy"},{"at":"2026-10-15T10:01:52.887774+00:00","status":"healthy"},{"at":"2026-10-08T10:00:53.153372+00:00","status":"healthy"},{"at":"2026-10-01T09:03:53.799784+00:00","status":"healthy"}]},{"endpoint_name":"get_ad_details","status":"healthy","last_checked_at":"2026-10-29T22:00:26.052344+00:00","last_verified_at":"2026-10-29T22:00:26.052344+00:00","recent_runs":[{"at":"2026-10-29T22:00:26.052344+00:00","status":"healthy"},{"at":"2026-10-22T19:04:25.738171+00:00","status":"healthy"},{"at":"2026-10-15T10:01:52.887774+00:00","status":"healthy"},{"at":"2026-10-08T10:00:53.153372+00:00","status":"healthy"},{"at":"2026-10-01T09:03:53.799784+00:00","status":"healthy"}]}],"sdk_usage_example":{"code":"\"\"\"Google Ads Transparency Center — discover advertisers and inspect their ad creatives.\"\"\"\nfrom parse_apis.google_ads_transparency_center_api import (\n    GoogleAdsTransparency, AdFormat, AdNotFound\n)\n\nclient = GoogleAdsTransparency()\n\n# Search for advertisers by name — single-page result, capped by limit.\nfor advertiser in client.advertisers.search(query=\"Nike\", limit=5):\n    print(advertiser.name, advertiser.ad_count, advertiser.country)\n\n# Drill into one advertiser's ads via the sub-resource.\nadvertiser = client.advertisers.search(query=\"Apple\", limit=1).first()\nif advertiser:\n    for ad in advertiser.ads.list(region=\"US\", limit=3):\n        print(ad.creative_id, ad.format, ad.last_shown)\n\n    # Get full details on the first ad.\n    ad = advertiser.ads.list(limit=1).first()\n    if ad:\n        try:\n            detail = ad.details()\n            print(detail.advertiser_legal_name, detail.regions, detail.ad_link)\n        except AdNotFound as exc:\n            print(f\"Ad removed: {exc.creative_id}\")\n\nprint(\"exercised: advertisers.search / advertiser.ads.list / ad.details\")\n","shape":"parse_sdk","endpoints":["search_advertisers","search_ads","get_ad_details"],"has_session":false,"hover_map":[{"line":9,"col":4,"len":10,"label":"advertiser: Advertiser","kind":"variable"},{"line":13,"col":0,"len":10,"label":"advertiser: Advertiser","kind":"variable"},{"line":14,"col":3,"len":10,"label":"advertiser: Advertiser","kind":"variable"},{"line":6,"col":9,"len":21,"label":"GoogleAdsTransparency — API client","kind":"class"},{"line":9,"col":37,"len":6,"label":"search() → List[Advertiser]","kind":"method"},{"line":15,"col":8,"len":2,"label":"ad: AdSummary","kind":"variable"},{"line":19,"col":4,"len":2,"label":"ad: AdSummary","kind":"variable"},{"line":20,"col":7,"len":2,"label":"ad: AdSummary","kind":"variable"},{"line":10,"col":21,"len":4,"label":"name: str","kind":"field"},{"line":10,"col":38,"len":8,"label":"ad_count: int","kind":"field"},{"line":10,"col":59,"len":7,"label":"country: str","kind":"field"},{"line":15,"col":29,"len":4,"label":"list() → List[AdSummary]","kind":"method"},{"line":10,"col":10,"len":10,"label":"advertiser: Advertiser","kind":"variable"},{"line":10,"col":27,"len":10,"label":"advertiser: Advertiser","kind":"variable"},{"line":10,"col":48,"len":10,"label":"advertiser: Advertiser","kind":"variable"},{"line":13,"col":32,"len":6,"label":"search() → List[Advertiser]","kind":"method"},{"line":16,"col":17,"len":11,"label":"creative_id: str","kind":"field"},{"line":16,"col":33,"len":6,"label":"format: AdFormat","kind":"field"},{"line":16,"col":44,"len":10,"label":"last_shown: str","kind":"field"},{"line":22,"col":12,"len":6,"label":"detail: Ad","kind":"variable"},{"line":24,"col":15,"len":10,"label":"AdNotFound — error (404): The advertiser_id/creative_id combination does not exist or has been removed","kind":"error"},{"line":15,"col":14,"len":10,"label":"advertiser: Advertiser","kind":"variable"},{"line":16,"col":14,"len":2,"label":"ad: AdSummary","kind":"variable"},{"line":16,"col":30,"len":2,"label":"ad: AdSummary","kind":"variable"},{"line":16,"col":41,"len":2,"label":"ad: AdSummary","kind":"variable"},{"line":19,"col":24,"len":4,"label":"list() → List[AdSummary]","kind":"method"},{"line":22,"col":24,"len":7,"label":"details() → Ad","kind":"method"},{"line":23,"col":25,"len":21,"label":"advertiser_legal_name: str","kind":"field"},{"line":23,"col":55,"len":7,"label":"regions: List[str]","kind":"field"},{"line":23,"col":71,"len":7,"label":"ad_link: url","kind":"field"},{"line":22,"col":21,"len":2,"label":"ad: AdSummary","kind":"variable"},{"line":23,"col":18,"len":6,"label":"detail: Ad","kind":"variable"},{"line":23,"col":48,"len":6,"label":"detail: Ad","kind":"variable"},{"line":23,"col":64,"len":6,"label":"detail: Ad","kind":"variable"},{"line":19,"col":9,"len":10,"label":"advertiser: Advertiser","kind":"variable"},{"line":25,"col":33,"len":3,"label":"exc: AdNotFound","kind":"variable"}]},"sdk_delivery_state":"legacy","summary":"Search Google Ads Transparency Center for advertisers and their ad creatives. Extract ad text/copy, format, advertiser info, date ranges, regions, and direct links to ads.","updated_at":"2026-08-28T16:04:10.022823+00:00","user_variants":[],"latest_version":6,"user_status":null,"user_scraper_id":null,"contributes_to_marketplace":true,"pinned_version":null,"seo_content":{"faqs":[{"a":"Google does not publish an official public API for the Ads Transparency Center at adstransparency.google.com. The center is a consumer-facing web interface. This Parse API surfaces the same data programmatically.","q":"Does Google Ads Transparency Center have an official developer API?"},{"a":"Each response includes a `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.","q":"How does pagination work in the `search_ads` endpoint?"},{"a":"The `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.","q":"Does `search_ads` cover all regions, or is filtering required?"},{"a":"Not currently. The API covers advertiser identity, creative content, ad formats, date ranges, and geographic regions. Spend amounts, impression volumes, and audience targeting segments are not included in any of the three endpoints. You can fork this API on Parse and revise it to add an endpoint if that data becomes available from the source.","q":"Does the API expose spend data, impression counts, or demographic targeting breakdowns?"},{"a":"Yes. The `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.","q":"Can I retrieve ads for an advertiser I find only by partial name?"}],"keywords":["google ads transparency center API","ad creative search API","advertiser lookup API","google ad copy scraper API","ad transparency data API","competitor ad monitoring API","google ads date range API","ad format extraction API","advertiser ID lookup API","regional ad targeting data API","ad preview URL API","google political ads API","ad text extraction API","brand ad history API"],"use_cases":["Track competitor ad copy changes over time using `first_shown` and `last_shown` date fields from `search_ads`.","Map geographic ad distribution for a brand by collecting `regions` arrays from `get_ad_details`.","Build an advertiser directory by iterating `search_advertisers` across multiple markets with different `region` values.","Monitor when specific creatives go live or stop running by polling `last_shown` for a fixed `creative_id`.","Audit ad formats (image, text, video) used by a category of advertisers via the `format` field in `search_ads` results.","Collect direct ad preview links using `ad_link` and `ad_preview_urls` for manual review workflows.","Research political or sensitive-category advertisers by querying known brand names and paginating their full creative history."],"meta_title":"Google Ads Transparency Center API","generated_at":"2026-05-21T21:30:15.831387+00:00","lead_paragraph":"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.","schema_version":2,"meta_description":"Search Google Ads Transparency Center for advertisers and ad creatives. Extract ad copy, formats, date ranges, regions, and direct ad links via 3 endpoints.","primary_category":"b2b_directory","long_description_md":"## Advertiser Search\n\nThe `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.\n\n## Ad Creative Search and Pagination\n\nThe `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.\n\n## Ad Detail\n\nThe `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.","generated_with_model":"global.anthropic.claude-sonnet-4-6","secondary_categories":["news_media","government_public"]},"primary_category":"b2b_directory","secondary_categories":["news_media","government_public"],"access_requirements":[]}