openclaw/ad-intelligence

Ad Intelligence Skill

A two-phase competitive ad intelligence skill for marketing companies and ecommerce owners to research how competitors run ads across Meta, Google, and LinkedIn.

---

Quick Reference: What Data Is Available

| Field | Meta (FB/IG) | Google Transparency | LinkedIn | |---|---|---|---| | Ad copy / headline | ✅ Both phases | ✅ Both phases | ✅ Both phases | | Creative (image/video URL) | ✅ Both phases | ✅ Both phases | ✅ Both phases | | Ad format type | ✅ Both phases | ✅ Both phases | ✅ Both phases | | Date first/last shown | ✅ Both phases | ✅ Both phases | ✅ Both phases | | Platform / placements | ✅ Both phases | ✅ (Google Search, YT, Display, etc.) | ✅ Both phases | | Active / inactive status | ✅ Both phases | ✅ Both phases | ✅ Both phases | | CTA button | ✅ Phase 1 scrape | ❌ | ✅ Both phases | | Destination / landing URL | ✅ Both phases | ✅ Both phases | ✅ Both phases | | Total ads running | ✅ Phase 2 | ✅ Phase 2 | ✅ Phase 2 | | Impression range | ✅ Phase 2 (EU/political only) | ❌ | ✅ Phase 2 (some scrapers) | | Spend range | ✅ Phase 2 (EU/political only) | ❌ | ❌ | | Demographic breakdown | ✅ Phase 2 (EU only) | ❌ | ❌ | | Targeting info | ❌ | ❌ | ✅ Phase 2 (partial — language, location) | | Advertiser ID | ✅ Phase 2 | ✅ Phase 2 | ✅ Phase 2 |

⚠️ No platform exposes: exact spend, CTR, conversion rates, ROAS, or detailed audience targeting.

---

Workflow

Step 1: Understand the Request

Gather from the user (ask if not provided):

• Competitor name or domain (e.g., "Nike" or "nike.com")
• Target platform(s): Meta / Google / LinkedIn (default: all three)
• Phase: Phase 1 (quick, no API keys) or Phase 2 (deeper, requires API keys)
• Country/region filter (optional, e.g., "US", "IN", "EU")
• Date range (optional, e.g., "last 30 days")
• Ad format filter (optional: image / video / carousel / text)

If the user hasn't said which phase they want, ask. If they're just exploring, start with Phase 1.

---

Step 2: Execute the Right Phase

Read the platform reference files for code, endpoints, and examples:

• Meta: references/meta.md
• Google: references/google.md
• LinkedIn: references/linkedin.md

Each reference contains:

• Phase 1: Python scraping code (no API key needed)
• Phase 2a: Official/free API instructions
• Phase 2b: Third-party paid API options (SerpAPI, SearchAPI, Adyntel, Apify)
• Sample output JSON
• Known limitations

---

Step 3: Format the Output

Always deliver both:

A. Human-Readable Summary Report

## Ad Intelligence Report: [Company Name]
**Platforms Searched:** Meta, Google, LinkedIn
**Date:** [today]
**Phase:** 1 (Scrape) / 2 (API)
**Country:** [region]

### 📊 Overview
- Total ads found: X
- Active ads: X | Inactive: X
- Formats: X% image, X% video, X% carousel

### 🎯 Platform Breakdown
[Per platform: count, date range, notable trends]

### ✍️ Creative Themes & Messaging Patterns
[Summarize recurring hooks, CTAs, offers, tone]

### 📅 Recency & Cadence
[How often they post new ads, seasonal patterns]

### ⚠️ Data Limitations
[Note what wasn't available and why]

B. Raw Structured Data (JSON)

Return normalized JSON with this schema for each ad:

{
  "platform": "meta|google|linkedin",
  "ad_id": "string",
  "advertiser_name": "string",
  "advertiser_page_url": "string",
  "status": "active|inactive",
  "format": "image|video|carousel|text|document",
  "headline": "string|null",
  "body_text": "string|null",
  "cta_text": "string|null",
  "destination_url": "string|null",
  "creative_url": "string|null",
  "platforms_served": ["facebook", "instagram", "messenger"],
  "date_first_shown": "YYYY-MM-DD|null",
  "date_last_shown": "YYYY-MM-DD|null",
  "country": "string|null",
  "spend_range": "string|null",
  "impression_range": "string|null",
  "targeting_summary": "string|null",
  "source_phase": 1
}

---

Step 4: Provide Next Steps

After presenting results, always suggest:

• Which Phase 2 option would give more depth for this use case
• What API keys/accounts are needed to upgrade
• Whether the data is sufficient or the user should broaden/narrow their search

---

Important Limitations to Always Communicate

1. No private performance data: CTR, conversions, ROAS, exact spend — these are never public.
2. Meta API geographic restriction: The official Meta Ad Library API only returns impression/spend data for EU-delivered ads and political/social cause ads globally. For general ecommerce ads in non-EU regions, Phase 1 scraping often gives broader coverage.
3. Google has no official public API: All Google Transparency Center data is accessed via scraping (Phase 1) or third-party wrappers like SerpAPI/SearchAPI (Phase 2).
4. LinkedIn targeting data is partial: Only language and location hints are sometimes visible — not job title, seniority, or company size targeting.
5. Rate limits apply: All platforms rate-limit requests. Use pagination and add delays (1–2s between calls).

---

Phase Decision Guide

| Situation | Recommended Phase | |---|---| | Quick competitive overview | Phase 1 | | No API keys available | Phase 1 | | Need date-range filtering | Phase 2 | | EU market + want spend/impressions | Phase 2 (official Meta API) | | Need 500+ ads at scale | Phase 2 (paid third-party API) | | B2B competitor research on LinkedIn | Phase 2 | | Need creative image/video downloads | Phase 2 |

---

Reference Files

• references/meta.md — Meta (Facebook/Instagram) scraping + API code
• references/google.md — Google Ads Transparency scraping + SerpAPI/SearchAPI
• references/linkedin.md — LinkedIn Ad Library scraping + third-party APIs