google-ads-transparency-center

Google Ads Transparency Center

Search Google Ads Transparency Center ad creative listings through Frevana.

Purpose

This skill is for finding Google Ads Transparency Center ad creative results.

Inputs:

• advertiser_id or text
• optional platform
• optional region
• optional next_page_token

Output:

• validated response JSON with Google Ads Transparency Center results
• the same validated JSON saved to a local file on every successful run

This skill validates that the response is JSON, saves it to disk, and returns it unchanged on stdout. Do not rewrite or reshape the returned data unless the user explicitly asks for a transformation.

What This Skill Needs

• user-provided advertiser_id, text, or next_page_token
• optional filters listed above
• FREVANA_TOKEN in the environment variables, or an explicit --token override for the current run
• curl
• bash
• python3

Execution Order

Use this flow so the request stays simple and reliable:

1. Confirm the user has provided an advertiser_id, text, or next_page_token.
2. Prefer the script over ad hoc curl commands.
3. Let the script read FREVANA_TOKEN first.
4. In interactive shell usage, if FREVANA_TOKEN is missing, the script may prompt for it.
5. In non-interactive or agent workflows, fail fast if the token is missing and tell the user to set FREVANA_TOKEN or pass --token explicitly.
6. Run the script once. It prints the validated JSON to stdout and saves the same JSON to a file.
7. Use the saved JSON file for any follow-up parsing or summarization instead of calling the search API again.
8. Return the validated response JSON, or summarize the relevant ad creatives if the user does not need the full payload.

Commands

Search by domain or text

bash <skill-path>/scripts/search_google_ads_transparency_center.sh \
  --text "apple.com"

--q and --query are accepted as aliases for --text.

Search by advertiser ID

bash <skill-path>/scripts/search_google_ads_transparency_center.sh \
  --advertiser-id "AR17828074650563772417"

--advertiser_id is accepted as an alias for --advertiser-id.

Search with filters

bash <skill-path>/scripts/search_google_ads_transparency_center.sh \
  --text "apple.com" \
  --platform YOUTUBE \
  --region 2840

Fetch the next page

bash <skill-path>/scripts/search_google_ads_transparency_center.sh \
  --text "apple.com" \
  --region 2840 \
  --next-page-token "CgoAP7zn5TAzVgIz..."

--next_page_token is accepted as an alias for --next-page-token.

Save response JSON to a specific file

bash <skill-path>/scripts/search_google_ads_transparency_center.sh \
  --text "apple.com" \
  --region 2840 \
  --output ./out/google-ads-transparency-center-result.json

Token override for the current run

bash <skill-path>/scripts/search_google_ads_transparency_center.sh \
  --text "apple.com" \
  --token "your bearer token"

Fixed Request Shape

The script sends this payload shape, omitting optional fields that were not provided:

{
  "advertiser_id": "AR17828074650563772417",
  "text": "apple.com",
  "platform": "YOUTUBE",
  "region": "2840",
  "next_page_token": "CgoAP7zn5TAzVgIz..."
}

Provide at least one of advertiser_id, text, or next_page_token. Do not invent advertiser IDs, region codes, platforms, or pagination tokens when the user did not provide them.

Response Shape

The API returns Frevana JSON. Common fields include:

• search_metadata
• search_parameters
• search_information.total_results
• ad_creatives
• pagination.next_page_token

Each ad_creatives[] item may include advertiser_id, advertiser, ad_creative_id, format, target_domain, image, link, width, height, first_shown, last_shown, details_link.

Output

• Success: the script validates that the response body is JSON, writes it to a file, prints the saved path to stderr, and prints the JSON to stdout
• Default file path: ./out/google-ads-transparency-center-<UTC timestamp>-<pid>.json
• With --output: the same JSON is written to the specified file path instead of the default path
• Failure: the script prints the response body or parsing error and exits non-zero

Notes

• Require at least one of --advertiser-id, --text, or --next-page-token.
• Use --text for domains or free-text Google Ads Transparency Center searches.
• Use --advertiser-id only when the user provides a Google advertiser ID such as AR17828074650563772417; do not guess it from a brand name.
• Use --next-page-token only for pagination from a prior response's pagination.next_page_token.
• Valid --platform values are PLAY, MAPS, SEARCH, SHOPPING, and YOUTUBE.
• The Frevana endpoint schema currently exposes advertiser_id, text, platform, region, and next_page_token. Do not pass unsupported passthrough fields such as engine, api_key, output, no_cache, async, zero_trace, political_ads, start_date, end_date, creative_format, or num.
• If curl is missing, stop and tell the user to install curl.
• If python3 is missing, stop and tell the user to install python3.
• Do not echo the Bearer token back to the user.
• Summarize ad creatives by advertiser, advertiser ID, creative ID, format, target domain, first/last shown, and links when available unless the user asks for raw JSON.

Example Prompts

Chinese

• "Check the ads for apple.com in the Google Ads Transparency Center"
• "Use advertiser_id AR17828074650563772417 to query ad creatives, region 2840"
• "Continue to the previous page of Google Ads Transparency Center results; the next_page_token is CgoAP7..."
• "Check the ads for apple.com on the YouTube platform and save the raw JSON"

English

• "Search Google Ads Transparency Center for ads from apple.com."
• "Look up ad creatives for advertiser_id AR17828074650563772417 in region 2840."
• "Fetch the next page of Google Ads Transparency Center results with this next_page_token."
• "Find ads for apple.com on YouTube and save the raw JSON."