Facebook Ad Library Scraper

Overview

The Facebook Ad Library Scraper is a powerful tool designed to extract ad data from the Facebook Ad Library. Whether you are a marketer, researcher, or business owner, this actor helps you gain insights into advertising strategies, creative trends, and competitor campaigns. It provides a reliable way to access public ad data for analysis and inspiration.

Features

• Comprehensive Ad Extraction: Retrieve ads from any Facebook page or keyword search.
• Flexible Filtering: Filter ads by active status, category (political, housing, employment, credit), and country.
• Detailed Data: Get rich data including ad copy, creative details, start dates, and more.
• Easy to Use: Supports both direct Ad Library URLs and Facebook Page URLs.

How to Use

You can use this scraper in two ways:

Method 1: Using a Facebook Page URL

If you want to scrape ads for a specific advertiser:

1. Enter the Facebook Page URL (e.g., https://www.facebook.com/Google/) into the Target URL field.
2. Configure the filters using the input fields:
   • Active Status: Choose between All, Active, or Inactive ads.
   • Ad Category: Select a specific category like Housing, Employment, or All.
   • Country: Specify the country to filter ads by (e.g., US, GB, BR).

Method 2: Using a Direct Ad Library Link

If you prefer to set up your search directly on Facebook:

1. Go to the Facebook Ad Library.
2. Perform your search and apply any desired filters (country, category, keywords).
3. Copy the URL from your browser's address bar.
4. Paste it into the Target URL field in the actor input.
   • Note: When using this method, the actor will prioritize the filters in the URL over the input parameters (except for maxResults).

Method 3: Using a Keyword Search

You can search for ads by keyword directly without needing a URL:

1. Enter your keyword (e.g., Gaming Chair) directly into the Target URL field.
2. The scraper will automatically detect that you've entered a keyword (not a URL) and search for ads containing those words.

Unordered Search (Default)

By default, keyword searches use unordered matching, which finds ads containing all the words in any order.

Example:

{
    "targetUrl": "Gaming Chair",
    "country": "US",
    "activeStatus": "active"
}

This will find ads that contain both "Gaming" and "Chair" anywhere in the ad.

Exact Phrase Search

To search for an exact phrase, wrap your keyword in double quotes ("):

Example:

{
    "targetUrl": "\"Gaming Chair\"",
    "country": "US",
    "activeStatus": "active"
}

This will only find ads that contain the exact phrase "Gaming Chair" in that order.

Tip: In JSON, you need to escape the double quotes with a backslash (\"). So "Gaming Chair" becomes \"Gaming Chair\" in your input.

Method 4: Using a Single Ad URL

If you have a direct link to a specific ad, you can scrape just that one ad:

1. Paste the Ad ID URL (e.g., https://www.facebook.com/ads/library/?id=123456789) into the Target URL field.
2. The scraper will extract details for that specific ad only.

Input Parameters

Parameter	Type	Description
Target URL	String	A Facebook Page URL, Ad Library search URL, or a keyword to search for ads.
Max Results	Number	The maximum number of ads to scrape.
Active Status	Select	Filter for Active, Inactive, or All ads.
Ad Category	Select	Filter by category (e.g., Political, Housing, Employment).
Country	Select	Filter ads by specific country code (e.g., US, CA, ALL).

Output

The scraper stores the results in a dataset, which can be downloaded in various formats (JSON, CSV, Excel, etc.). Each item represents an ad and contains details such as:

• Ad ID
• Ad Creative (Images/Videos)
• Ad Copy (Text)
• Start Date
• Publisher Platforms
• And more...

Error Responses

In addition to searching for ads, the scraper provides detailed error reporting in the dataset. If an error occurs (e.g., invalid URL, private page, or no ads found), the scraper will output a JSON object with an error field.

Common Error Examples:

1. No Ads Found

{
    "message": "No ads were found matching the provided search criteria.",
    "errorCode": "NO_ADS_FOUND",
    "url": "https://www.facebook.com/PageWithNoAds/",
    "timestamp": "2023-10-27T10:00:00.000Z"
}

2. Invalid URL

{
    "error": "Url is not valid",
    "errorCode": "INVALID_URL",
    "url": "https://www.facebook.com/invalid-path",
    "details": "Invalid URL structure."
}

3. Private Page / Login Required

{
    "error": "Private Page Detected",
    "errorCode": "PRIVATE_PAGE",
    "url": "https://www.facebook.com/private-group/",
    "details": "The target page is private or visible only to logged-in users..."
}

4. Critical Error

{
    "error": "Critical Error Message",
    "errorCode": "CRITICAL_ERROR",
    "url": "...",
    "details": "Stack trace or details..."
}