Facebook Ad Library Scraper

Scrape ads from Facebook Ads Library search results and Facebook pages with zero null values and comprehensive data enrichment.

Features

• Keyword & Page Search: Search Facebook Ad Library by keywords or specific Facebook Page URLs.
• Zero Null Enforced Output: Automatically maps original raw data variations (snake_case, nested snapshot objects) and replaces missing or null values with non-null defaults.
• Rich Media & Ad Metadata: Extracts ad copy, media URLs (images & videos), start/end dates, CTA destination URLs, spend ranges, impressions, and target demographics.
• Dual Logging: Automatically exports validated datasets to JSON and CSV formats while logging validation/runtime errors to log files.

Extracted Data Schema

Field Name	Type	Description
adArchiveID	String	Unique Facebook Ad Archive ID
pageId	String	Facebook Page ID of advertiser
pageName	String	Advertiser / Page Name
publisherPlatform	Array	Platforms where ad runs (facebook, instagram, etc.)
adCopy	String	Ad creative caption / body text
mediaUrls	Array	List of image/video creative URLs
mediaType	String	Creative format (Image or Video)
startDate	String	Ad delivery start timestamp
endDate	String	Ad delivery stop timestamp or Active / Ongoing
isActive	Boolean	Whether ad is currently active
ctaType	String	Call to Action button label
ctaDestinationUrl	String	Landing page URL
spend	Object	Estimated ad spend range
impressions	Object	Estimated impressions range
targetDemographics	Array	Age, gender, and location targeting

Input Example

{
  "searchTerms": ["ecommerce", "software"],
  "countryCode": "ALL",
  "maxAds": 50,
  "activeStatus": "active"
}

How to Run Locally

$npm start

Runs the actor locally, populates storage/datasets/default/, applies strict data quality validation, and writes cleaned outputs to outputs/facebook-ad-library-scraper_success.json.