Ads parser

Collects a company's ads from three transparency libraries through SearchApi.io, plus direct fetches of public LinkedIn Ad Library pages (no login needed).

Key: SEARCHAPI_KEY, from the environment or ~/.config/marketing-agent-kit/.env. Setup: connections/searchapi.md, or run the connect skill.

Engine docs: https://www.searchapi.io/docs/<engine-name-with-dashes>. Check an engine's parameters before using it for the first time. Only successful (HTTP 200) requests are billed; new accounts get 100 free requests.

Workflow

Create raw/ads/ in the working folder. Save every response as JSON with a meaningful name. Write the analysis from the raw files only — never from memory of what a response said.

1. LinkedIn Ad Library — the richest source, with traps

Read references/linkedin-ad-library.md before starting. It covers the companyIds trick, why a name search returns impostors, and when impressions are disclosed. Short version:

# keyword search — also returns ads BY OTHERS that mention the brand:
python3 ${CLAUDE_SKILL_DIR}/scripts/searchapi.py --engine linkedin_ad_library --out raw/ads/li-q.json q=<company>

# detail page for each ad id you found — public, no login. Save the HTML right away:
curl -s -A "Mozilla/5.0" "https://www.linkedin.com/ad-library/detail/<AD_ID>" -o raw/ads/li-detail-<AD_ID>.html
# or the structured version through SearchApi:
python3 ${CLAUDE_SKILL_DIR}/scripts/searchapi.py --engine linkedin_ad_library_ad_details --out raw/ads/li-ad-<AD_ID>.json ad_id=<AD_ID>

2. Google Ads Transparency Center

# find the advertiser id first:
python3 ${CLAUDE_SKILL_DIR}/scripts/searchapi.py --engine google_ads_transparency_center_advertiser_search --out raw/ads/g-adv.json q=<company>
# then the creatives:
python3 ${CLAUDE_SKILL_DIR}/scripts/searchapi.py --engine google_ads_transparency_center --out raw/ads/g-1.json advertiser_id=AR...

Creative previews are images that carry the exact ad texts. Save them and transcribe the texts verbatim in the analysis. Link each creative to its page: https://adstransparency.google.com/advertiser/<ADVERTISER_ID>/creative/<CREATIVE_ID>.

3. Meta Ad Library

python3 ${CLAUDE_SKILL_DIR}/scripts/searchapi.py --engine meta_ad_library --out raw/ads/meta-q.json q=<company>
# find the page id by name, if you don't have it:
python3 ${CLAUDE_SKILL_DIR}/scripts/searchapi.py --engine meta_ad_library_page_search --out raw/ads/meta-pages.json q=<company>
# confirm the page is really theirs before attributing ads (same-name pages are common):
python3 ${CLAUDE_SKILL_DIR}/scripts/searchapi.py --engine meta_ad_library_page_info --out raw/ads/meta-page.json page_id=<ID>

Meta sorts by impressions by default, not by date — pass sort_by if you need the newest first. Zero ads is a finding, not a failure. State it explicitly — it tells you where the company does not look for its audience.

Reporting rules

• Every ad in the report links to its library page. Every date is labelled ("Ran from … to …").
• Impressions only where the library actually discloses them; otherwise write "the library does not disclose this". LinkedIn discloses impressions, run dates and targeting only for ads shown in the EU — outside the EU those fields are simply missing.
• No budget or spend estimates. Libraries don't disclose spend for ordinary commercial ads (Meta's spend fields are filled for political and social-issue ads), and third-party dollar estimates (including Ahrefs paid-traffic cost) are unreliable. Quote a spend figure only if the library itself shows it; otherwise say it isn't disclosed.
• No comparisons of ad volume between competitors unless explicitly requested.
• Job ads are a hiring signal, not demand generation — analyse them separately.
• Separate the company's own ads from third-party ads that merely mention the brand. A keyword search returns both; the third-party ones are a separate signal (who compares themselves to the brand, who rides on it).

Adapt it

• If you track the same competitors every month, keep their LinkedIn companyIds, Google advertiser ids and Meta page ids in a small competitors.json next to your reports. Lookups are the slow, error-prone part.
• Video ads: libraries give the cover image and text, not the file. If you need what is said in the video, download what the library exposes and transcribe it with Whisper.