📱 Facebook Ads Scraper Pro - Ad Library Intelligence Transform Facebook's Ad Library into actionable business intelligence with comprehensive ad data extraction, media downloads, and competitive analysis across all Meta platforms. Perfect for digital marketers, competitive researchers, and agencies who need deep insights into advertising strategies without manual browsing complexity. --- ## 🚀 Key Benefits & Use Cases ### 🎯 For Digital Marketers - Analyze competitor ad strategies with complete creative archives and targeting data - Track campaign performance trends and identify winning ad formats - Build comprehensive competitive intelligence databases with historical data ### 🏢 For Agencies & Consultants - Generate client reports with competitor analysis and market insights - Discover high-performing ad creatives for inspiration and benchmarking - Monitor industry trends and advertising spend patterns across sectors ### 📊 For Market Researchers - Study advertising trends across countries, languages, and demographics - Analyze political and issue-based advertising patterns with compliance data - Track brand messaging evolution and campaign lifecycle analysis --- ## 🔎 Complete Ad Intelligence Extraction ### 📹 Ad Creative Data - Content: Ad text, title, caption, CTA buttons with direct links - Media: High-quality images, videos (HD/SD), thumbnails with direct URLs - Targeting: Countries, platforms, audience demographics - Performance: Page engagement metrics, campaign duration ### 📱 Multi-Platform Coverage - Facebook: Main feed ads, stories, marketplace listings - Instagram: Feed posts, stories, reels, shopping ads - Audience Network: Third-party app and website placements - Messenger: Chat-based advertising and sponsored messages ### 📊 Advanced Filtering & Analytics - Date Ranges: Historical data with custom periods - Content Types: Video, image, carousel, collection formats - Ad Categories: General, political, housing, employment, financial services - Status Tracking: Active, inactive, or comprehensive ad lifecycle data --- ## ⚙️ Configuration Options ### 🔍 Search & Discovery Target specific ads using multiple strategies: json { "searchQueries": [ "digital marketing", "fitness app", "cryptocurrency", "Black Friday deals" ], "maxResultsPerQuery": 100, "proxyConfig": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] } } ### 🛡️ Proxy Configuration (Required) #### 🔒 proxyConfig (Object) - Required: Yes - Proxy configuration is mandatory for reliable scraping - useApifyProxy: Set to true for Apify platform proxy usage - apifyProxyGroups: Recommended ["RESIDENTIAL"] for best results - apifyProxyCountry: Optional country targeting for proxy servers 📋 Example configurations: json { "proxyConfig": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "US" } } ### 🌍 Geographic & Language Targeting #### 🗺️ countries (String) * Default: "ALL" (All countries) * Options: Single ISO 2-letter code (e.g., "US", "CA", "FR") or "ALL" * Use Case: Focus on a single market or run globally ### 🎯 Advanced Filtering Options #### 📱 platforms (Array) - Options: - FACEBOOK: Main Facebook feed advertising - INSTAGRAM: Instagram stories, feed, and shopping - AUDIENCE_NETWORK: Third-party app placements #### 📂 ad_category (String) - Options: - "UNKNOWN": General commercial advertising - "EMPLOYMENT": Job and recruitment campaigns - "POLITICAL_AND_ISSUE_ADS": Political and issue-based campaigns - "HOUSING": Real estate advertisements - "CREDIT": Financial services offerings #### 🎨 media_type (String) - Options: - "video": Video campaigns only - "image": Static image advertisements #### 📊 is_active (Boolean) - Default: false - Options: - true: Currently running advertisements - false: Ended or paused campaigns ### 📅 Date Range Filtering #### 📅 start_date (String) - Format: "YYYY-MM-DD" - Purpose: Campaign start date - Use Case: Historical trend analysis and campaign lifecycle tracking #### 📅 end_date (String) - Format: "YYYY-MM-DD" - Purpose: Campaign end date - Use Case: Recent campaign focus and time-bound analysis --- ## 📊 Rich Data Output Structure ### 📹 Complete Ad Data Structure json { "id": "625695519983453", "page_id": "283160151552048", "ad_url": "https://www.facebook.com/ads/library/?id=625695519983453", "text": "👉🏻 Commentez ou envoyez les lettres \"LS\" en message privé pour en savoir plus", "title": "", "caption": "www.instagram.com", "link_url": "https://www.instagram.com/", "cta_text": "Send message", "media": { "type": "video", "primary_thumbnail": "https://scontent.ftlm1-2.fna.fbcdn.net/v/t39.35426-6/...", "images": [], "videos": [ { "video_hd_url": "https://video.ftlm1-2.fna.fbcdn.net/v/t42.1790-2/...", "video_preview_image_url": "https://scontent.ftlm1-2.fna.fbcdn.net/...", "video_sd_url": "https://video.ftlm1-2.fna.fbcdn.net/v/t42.1790-2/...", "watermarked_video_hd_url": "", "watermarked_video_sd_url": "" } ] }, "additional_assets": { "images": [], "links": [], "texts": [], "videos": [] }, "page_name": "Institut Libre Serein", "page_url": "https://facebook.com/61558937875201", "page_profile_picture_url": "https://scontent.ftlm1-2.fna.fbcdn.net/...", "page_likes": 337, "start_date": "2025-01-09", "end_date": "2025-01-13", "is_active": false, "platforms": ["INSTAGRAM"], "countries": [], "ad_category": "UNKNOWN", "page_category": "School", "scraped_at": "2025-08-18T14:01:46.335Z", "contains_sensitive_content": false, "result_index": 1, "search_query": "digital marketing" } ### 🎨 Media Assets Structure #### Video Media json { "media": { "type": "video", "primary_thumbnail": "https://scontent.ftlm1-2.fna.fbcdn.net/...", "videos": [ { "video_hd_url": "https://video.ftlm1-2.fna.fbcdn.net/...", "video_sd_url": "https://video.ftlm1-2.fna.fbcdn.net/...", "video_preview_image_url": "https://scontent.ftlm1-2.fna.fbcdn.net/...", "watermarked_video_hd_url": "", "watermarked_video_sd_url": "" } ] } } #### Image Media json { "media": { "type": "image", "primary_thumbnail": "https://scontent.ftlm1-1.fna.fbcdn.net/...", "images": [ { "original_image_url": "https://scontent.ftlm1-1.fna.fbcdn.net/...", "resized_image_url": "https://scontent.ftlm1-1.fna.fbcdn.net/...", "watermarked_resized_image_url": "", "image_crops": [] } ] } } ### 📊 Additional Assets Structure json { "additional_assets": { "images": [ { "original_image_url": "https://scontent.ftlm1-2.fna.fbcdn.net/...", "resized_image_url": "https://scontent.ftlm1-2.fna.fbcdn.net/...", "watermarked_resized_image_url": null, "image_crops": [] } ], "links": [ "https://mission-personal.de/datenschutz/", "https://mission-personal.de/" ], "texts": [ "Redakteur (m/w/d) für Steuerrecht gesucht!", "Wir freuen uns, Dich kennenzulernen!", "Full name", "Phone number", "Email" ], "videos": [] } } ### 🏢 Page Information json { "page_name": "Institut Libre Serein", "page_url": "https://facebook.com/61558937875201", "page_profile_picture_url": "https://scontent.ftlm1-2.fna.fbcdn.net/...", "page_likes": 337, "page_category": "School" } ### ⏱️ Campaign Timeline & Metadata json { "start_date": "2025-01-09", "end_date": "2025-01-13", "is_active": false, "scraped_at": "2025-08-18T14:01:46.335Z", "result_index": 1, "search_query": "digital marketing" } --- ## 🎯 Configuration Examples ### Basic Competitor Analysis json { "searchQueries": ["Nike", "Adidas", "fitness wear"], "maxResultsPerQuery": 50, "countries": "US", "platforms": ["FACEBOOK", "INSTAGRAM"], "is_active": true, "proxyConfig": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] } } ### Video Campaign Research json { "searchQueries": ["online course", "education platform"], "maxResultsPerQuery": 100, "media_type": "video", "platforms": ["FACEBOOK", "INSTAGRAM"], "is_active": false, "proxyConfig": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "US" } } ### Employment Advertising Analysis json { "activeStatus": "ALL", "adType": "POLITICAL_AND_ISSUE_ADS", "contentLanguages": [ "es", "fr", "it", "ja", "de" ], "countries": "ALL", "endDate": "2025-09-28", "maxResultsPerQuery": 200, "mediaType": "IMAGE", "proxyConfig": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] }, "publisherPlatforms": [ "FACEBOOK", "AUDIENCE_NETWORK", "THREADS", "MESSENGER" ], "searchQueries": [ "remote work", "software engineer" ], "startDate": "2025-09-26" } --- ## 🔄 Advanced Features ### 🚀 Performance & Reliability - Smart Rate Limiting: Automatic throttling to respect Facebook's API limits - Error Recovery: Robust retry mechanisms for network interruptions - Progress Tracking: Real-time monitoring of scraping progress with result indexing - Data Validation: Automatic quality checks and duplicate prevention - 🛡️ Proxy Support: Advanced session management with automatic rotation for enhanced reliability ### 📊 Data Processing & Export - Multiple Formats: JSON, CSV, Excel-compatible exports - Rich Metadata: Complete ad lifecycle and targeting information - Media Preservation: Direct access URLs for all creative assets (HD/SD videos, original/resized images) - Historical Tracking: Time-series data with precise scraping timestamps ### 🎨 Creative Asset Management - Multi-Format Support: Both video and image campaigns - Quality Options: HD and SD video URLs, original and resized images - Watermark Handling: Separate URLs for watermarked and clean content - Thumbnail Generation: Preview images for all video content ### 🛡️ Compliance & Ethics - Public Data Only: Accesses Facebook's public Ad Library exclusively - Rate Limit Respect: Built-in delays to prevent service disruption - Terms Compliance: Follows Facebook's terms of service and API guidelines - Privacy Protection: No personal data collection, includes sensitivity flags --- ## 🛠️ Data Field Reference ### Core Ad Fields - id: Unique Facebook ad identifier - page_id: Facebook page identifier for the advertiser - ad_url: Direct link to the ad in Facebook's Ad Library - text: Main ad copy/body text - title: Ad headline (may be empty) - caption: Additional caption text - link_url: Destination URL when users click the ad - cta_text: Call-to-action button text ### Media & Assets - media.type: "video" or "image" - media.primary_thumbnail: Main preview image URL - media.videos[].video_hd_url: High-definition video URL - media.videos[].video_sd_url: Standard-definition video URL - media.images[].original_image_url: Full-resolution image URL - media.images[].resized_image_url: Optimized image URL ### Page Information - page_name: Advertiser's page name - page_url: Facebook page URL - page_profile_picture_url: Page profile image - page_likes: Number of page likes/followers - page_category: Business category (e.g., "School", "Business") ### Campaign Data - start_date: Campaign start date (YYYY-MM-DD) - end_date: Campaign end date (YYYY-MM-DD) - is_active: Current campaign status (true/false) - platforms: Array of platforms where ad runs - countries: Array of targeted countries (may be empty for global) - ad_category: Ad category classification ### Metadata - scraped_at: Timestamp when data was collected - result_index: Position in search results - search_query: Original search term used - contains_sensitive_content: Sensitivity flag (boolean) --- ## 🛠️ Troubleshooting ### Search Issues - No results: Try broader keywords or check spelling - Limited data: Increase maxResultsPerQuery or expand date ranges - Missing recent ads: Facebook may have indexing delays ### 🔒 Proxy Issues - Connection errors: Ensure proxy configuration is correct - Slow performance: Try different proxy groups (RESIDENTIAL) - Region restrictions: Use apifyProxyCountry for specific country requirements ### Geographic Filtering - Empty countries String: Use "ALL" (All countries) for global targeting - Wrong country codes: Use ISO 2-letter codes (US, not USA) - Missing regional ads: Some ads may not be available in all regions ### Media Access - Missing media URLs: Some ads may have expired or restricted media - Empty video arrays: Check if media.type is "video" - Broken links: Media URLs may expire after some time ### Performance Optimization - Large datasets: Use date ranges to limit scope - Memory issues: Reduce maxResultsPerQuery for bulk operations - Timeout errors: Enable proxy configuration for better reliability --- ## 📈 Business Intelligence Applications ### 🎯 Competitive Intelligence - Ad Strategy Analysis: Track competitor creative strategies using text, title, and media data - Platform Presence: Monitor competitor activity across platforms array - Campaign Duration: Analyze campaign lengths using start_date and end_date ### 🚀 Campaign Optimization - Creative Inspiration: Download high-quality assets using media.videos and media.images URLs - CTA Analysis: Study effective call-to-action strategies via cta_text field - Performance Benchmarking: Compare page engagement using page_likes data ### 📊 Market Research - Industry Trends: Filter by page_category and ad_category for sector analysis - Geographic Patterns: Analyze regional strategies using countries targeting data - Content Evolution: Track messaging changes over time using scraped_at timestamps --- ## 🤝 Support & Resources ### Getting Help - 📧 Email: fridaytechnolog@gmail.com - 🐙 GitHub: DZ-ABDLHAKIM - 🐦 Twitter: @DZ_45Omar - 🔧 Apify: dz_omar ### ⚖️ Legal & Compliance - Public Data Access: Only processes publicly available Facebook Ad Library data - Rate Limiting: Respects Facebook's service limits and terms of use - Data Protection: No storage of personal information or unauthorized data collection - Commercial Use: Suitable for business intelligence and research applications ---