Find an advertiser by their website domain.

Args: domain: The domain to search for (e.g. "nike.com", "coinbase.com")

Returns: Advertiser info with advertiser_id, name, and ad_count — or null if not found.

Search for advertisers by keyword or company name.

Args: query: Search query (e.g. "Nike", "Coinbase", "crypto exchange")

Returns: List of matching advertisers with advertiser_id, name, region, and ad_count.

Get ads for an advertiser with decoded content.

Searches for the advertiser by name, fetches their ad creatives, and returns full details including decoded text ad content (headline, description, destination URL).

Args: advertiser_name: The advertiser's name (e.g. "Nike, Inc.", "Coinbase") count: Number of ads to retrieve (default 10, max 100)

Returns: List of ad details with format, date, and content fields.

Get full details for a specific ad creative.

Args: advertiser_id: The advertiser's ID (e.g. "AR05099026886533578753") creative_id: The creative/ad ID (e.g. "CR10813648716908961793")

Returns: Ad detail with format (text/image/video), last_shown date, and content. For text ads, content includes headline, description, and destination_url. For image ads, content includes image_url (a directly fetchable asset). For video ads, content includes video_id, video_url (YouTube), and the on-creative headline and button_label.

Compare active Google ad counts across a set of domains, one row each.

The competitor paid-surface question in one call: who is running ads, and how many. Rows come back in input order; sort by ad_count yourself.

Every row has a status. "ok" means an advertiser was found; "absent" means no advertiser is registered for that domain and IS a genuine zero; "blocked" means Google rate-limited the lookup and is NOT a zero; "error" is anything else. Rows flagged parent_entity resolved to a differently named advertiser (a parent company, a reseller, or a stranger whose ads mention the domain) — never cite those counts as the domain's own.

Args: domains: Up to 50 domains or URLs (e.g. ["nike.com", "adidas.com"]).

Returns: [{domain, status, advertiser_id, advertiser_name, ad_count, parent_entity, note}, ...]

Summarise one advertiser: format mix, copy sample, destinations.

Fetches a sample of the advertiser's creatives and aggregates them: counts and share by format (text/image/video), the last-shown date range, de-duplicated headlines, descriptions and CTA labels, and the hosts the ads send people to. Pure aggregation — read strategy into it yourself.

Args: advertiser: An advertiser id ("AR..."), a domain ("nike.com") or a name ("Nike Retail BV"). sample: Creatives to sample (default 50, max 100). Roughly one to two requests per creative.

Returns: {status, advertiser_id, advertiser_name, active_ads, region, sample: {sampled, by_format, format_share, last_shown, headlines, descriptions, cta_labels, destination_hosts, with_video, with_image}}

Download an ad's actual creative to local files.

Image ads are always saved at their original resolution, so the file you get back is the real creative — usable in a deck or a slide as-is. Video ads are downloaded and sampled into evenly spaced JPEG frames.

Args: advertiser_id: The advertiser's ID (e.g. "AR04139428671737823233") creative_id: The creative/ad ID (e.g. "CR01542648288744833025") out_dir: Directory to write into. Defaults to a fresh temp directory. frames: How many frames to sample from a video (default 8). width: Frame width in pixels, height follows aspect (default 320). Ignored when full_quality is set; pass 0 for native resolution. full_quality: Keep the best video stream and write frames at native resolution. Use for presentation; leave off for vision analysis.

Returns: {format, out_dir, files, ...}. Text ads carry no downloadable asset and return their decoded copy instead.

Download a whole advertiser's creatives into one folder, with a manifest.

This is the bulk path for collecting real ad examples — images at their original resolution, videos sampled to stills — so they can be dropped straight into a deck or a report. Each creative gets its own subfolder.

Args: advertiser_name: The advertiser's name (e.g. "Buildkite", "Vercel Inc.") out_dir: Directory to write into. Created if missing. count: How many creatives to pull (default 10, max 100). full_quality: Native-resolution assets, suitable for presentation. frames: Frames to sample per video creative (default 4).

Returns: {advertiser, out_dir, manifest_path, creatives: [...]} where each entry carries its format, local file paths, and any decoded ad copy.