{"id":"meta-ad-scraper","name":"meta-ad-scraper","summary":"Metaの広告ライブラリ(Facebook、Instagram、Messenger、Threads、WhatsApp)から競合広告をスクレイピングできます。","body":"# Meta Ad Library Scraper\n\nScrape ads from Meta's Ad Library using the Apify `apify/facebook-ads-scraper` actor. Covers Facebook, Instagram, Messenger, Threads, and WhatsApp.\n\n## Quick Start\n\nRequires `APIFY_API_TOKEN` env var (or `--token` flag). Install dependency: `pip install requests`.\n\n```bash\n# Search ads by company name\npython3 skills/meta-ad-scraper/scripts/search_meta_ads.py \\\n  --company \"Nike\"\n\n# Search with country filter\npython3 skills/meta-ad-scraper/scripts/search_meta_ads.py \\\n  --company \"Shopify\" --country US\n\n# Search by keyword (broader than company name)\npython3 skills/meta-ad-scraper/scripts/search_meta_ads.py \\\n  --company \"project management software\"\n\n# Limit results\npython3 skills/meta-ad-scraper/scripts/search_meta_ads.py \\\n  --company \"HubSpot\" --max-ads 20\n\n# Search by Facebook Page URL directly\npython3 skills/meta-ad-scraper/scripts/search_meta_ads.py \\\n  --page-url \"https://www.facebook.com/nike\"\n\n# Only active ads (default), or all ads\npython3 skills/meta-ad-scraper/scripts/search_meta_ads.py \\\n  --company \"Salesforce\" --ad-status all\n\n# Human-readable summary\npython3 skills/meta-ad-scraper/scripts/search_meta_ads.py \\\n  --company \"Stripe\" --output summary\n```\n\n## How It Works\n\n1. Takes a company name, keyword, or Facebook Page URL\n2. Constructs a Meta Ad Library URL with the search query and filters\n3. Calls the Apify `apify/facebook-ads-scraper` actor via REST API\n4. Polls until the run completes, then fetches the dataset\n5. Parses and outputs ad data as JSON or human-readable summary\n\n## Resolving Company Name → Ads\n\nThe script handles the advertiser lookup automatically:\n- **Company name**: Constructs a search URL like `facebook.com/ads/library/?q=CompanyName` — the Apify actor searches Meta's Ad Library for matching advertisers\n- **Page URL**: If you have the Facebook Page URL, pass it via `--page-url` for exact matching\n- **Domain**: You can also pass a domain and the script will search for it\n\nNo need to manually find Page IDs. The Apify actor resolves the search internally.\n\n## CLI Reference\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--company` | *required** | Company name or keyword to search |\n| `--page-url` | none | Facebook Page URL for exact advertiser match |\n| `--country` | ALL | 2-letter country code (US, GB, DE, etc.) or ALL |\n| `--ad-status` | active | `active` or `all` (includes inactive) |\n| `--max-ads` | 50 | Maximum number of ads to return |\n| `--output` | json | Output format: `json` or `summary` |\n| `--token` | env var | Apify token (prefer `APIFY_API_TOKEN` env var) |\n| `--timeout` | 300 | Max seconds to wait for the Apify run |\n\n*Either `--company` or `--page-url` is required.\n\n## Output Fields\n\nEach ad in the output contains:\n\n```json\n{\n  \"ad_id\": \"123456789\",\n  \"page_name\": \"Nike\",\n  \"page_id\": \"123456789\",\n  \"ad_text\": \"Just Do It. Shop the latest...\",\n  \"ad_creative_link_title\": \"Nike.com\",\n  \"ad_creative_link_description\": \"Free shipping on orders...\",\n  \"ad_creative_link_url\": \"https://nike.com/...\",\n  \"image_url\": \"https://...\",\n  \"video_url\": \"https://...\",\n  \"ad_delivery_start_time\": \"2026-01-15\",\n  \"ad_delivery_stop_time\": null,\n  \"currency\": \"USD\",\n  \"spend_lower\": 100,\n  \"spend_upper\": 499,\n  \"impressions_lower\": 1000,\n  \"impressions_upper\": 4999,\n  \"platforms\": [\"facebook\", \"instagram\"],\n  \"status\": \"ACTIVE\"\n}\n```\n\n## Cost\n\n~$5 per 1,000 ads scraped on Apify Free plan. Paid plans are cheaper ($3.40-$5/1K).\n\n## Common Workflows\n\n### 1. Competitor Ad Research\n\n```bash\npython3 skills/meta-ad-scraper/scripts/search_meta_ads.py \\\n  --company \"Competitor Name\" --country US --max-ads 100 --output summary\n```\n\n### 2. Industry Ad Landscape\n\n```bash\n# Search by keyword to see all advertisers in a space\npython3 skills/meta-ad-scraper/scripts/search_meta_ads.py \\\n  --company \"CRM software\" --max-ads 50\n```\n\n### 3. Compare Multiple Competitors\n\nRun the script multiple times for each competitor and compare creative approaches, messaging, and spend ranges.\n\n## Important Notes\n\n- **EU/UK ads are most complete**: Meta archives all ads shown in EU/UK. For US-only ads, coverage may be limited to political/issue ads.\n- **Active vs All**: By default only active ads are returned. Use `--ad-status all` to include historical ads.\n- **Rate limits**: Apify handles rate limiting internally. For large scrapes, increase `--timeout`.\n\n## Configuration\n\nSee `references/apify-config.md` for detailed API configuration, token setup, and rate limits.","author":"@gooseworks-ai","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/gooseworks-ai/goose-skills/tree/main/skills/ads/capabilities/meta-ad-scraper","license":"MIT","category":"document","lang":"en","tokens":1181,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"scripts/search_meta_ads.py","size":8297,"sha256":"eabf642c7a5345aee420d8005a9ee16cf2d20fcecbdd983baf3a9a8d250feaa4"},{"path":"skill.meta.json","size":248,"sha256":"ec0963bbced18d095c56c1fb339324de4c3b604fe74ad63feb2e05cd2aa8d8df"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[{"code":"net.endpoints","kind":"exfiltration","excerpt":"api.apify.com, api.gooseworks.ai, nike.com, www.facebook.com","message":"bundled scripts reach 4 external host(s)","severity":"warn"}],"scannedAt":"2026-08-22","hasScripts":true,"networkEndpoints":["api.apify.com","api.gooseworks.ai","nike.com","www.facebook.com"]}}