JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 4
  • Score
    100M100P100Q51063F
  • License MIT

Meta Ad Library scraper with AI-powered competitive analysis using Apify and Gemini 2.0 Flash

Package Exports

  • meta-ads-scraper
  • meta-ads-scraper/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (meta-ads-scraper) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Meta Ads Scraper

A powerful TypeScript library for scraping Meta (Facebook) Ad Library data and performing AI-powered competitive analysis using Google's Gemini 2.0 Flash model.

Features

  • 🚀 Meta Ad Library Scraping: Extract ad data from Facebook's Ad Library using Apify
  • 🤖 AI-Powered Analysis: Analyze competitor ads with Google Gemini 2.0 Flash
  • 📊 Competitive Intelligence: Generate strategic insights and ad concepts
  • 🔄 Smart Caching: Reuse existing scraped data to save time and costs
  • 📝 TypeScript Support: Full type safety and IntelliSense support

Installation

npm install meta-ads-scraper

Prerequisites

You'll need API keys for:

  • Apify: For scraping Meta Ad Library data
  • Google Gemini: For AI analysis

Get your keys:

Quick Start

Basic Usage

import { MetaAdsScraper, GeminiAnalyzer, performCompetitiveAnalysis } from 'meta-ads-scraper';

// Set up your API keys
process.env.APIFY_TOKEN = 'your-apify-token';
process.env.GEMINI_API_KEY = 'your-gemini-api-key';

// Perform complete competitive analysis
const result = await performCompetitiveAnalysis({
  clientDetails: `
    Your company is a leading e-commerce platform specializing in 
    fast delivery and competitive pricing...
  `,
  competitors: [
    {
      name: 'Competitor 1',
      url: 'https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&search_type=page&view_all_page_id=123456789'
    },
    {
      name: 'Competitor 2', 
      url: 'https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&search_type=page&view_all_page_id=987654321'
    }
  ],
  scrapingOptions: {
    maxResults: 20,
    useExistingRun: true
  }
});

console.log('Analysis Results:', result);

Step-by-Step Usage

import { MetaAdsScraper, GeminiAnalyzer } from 'meta-ads-scraper';

// 1. Scrape ads
const scraper = new MetaAdsScraper(process.env.APIFY_TOKEN);
const ads = await scraper.getAds(competitorUrl, {
  maxResults: 10,
  useExistingRun: true
});

// 2. Analyze with AI
const analyzer = new GeminiAnalyzer(process.env.GEMINI_API_KEY);

// Restructure ads by company
const restructuredAds = await analyzer.restructureAds(ads);

// Analyze each company
const companyAnalysis = await analyzer.getTopIdeasPerCompany(
  'Company Name', 
  restructuredAds.text
);

// Generate industry insights
const industryAnalysis = await analyzer.industryWriteup([companyAnalysis]);

// Create ad concepts
const adConcepts = await analyzer.generateAdIdeas(
  [companyAnalysis],
  industryAnalysis,
  'Your company details...'
);

API Reference

Core Classes

MetaAdsScraper

Scrapes Meta Ad Library data using Apify.

const scraper = new MetaAdsScraper(apiToken?: string);

// Get ads from a Meta Ad Library URL
const ads = await scraper.getAds(url: string, options?: {
  maxResults?: number;
  useExistingRun?: boolean;
});

GeminiAnalyzer

Performs AI-powered analysis of scraped ad data.

const analyzer = new GeminiAnalyzer(apiKey?: string);

// Restructure raw ad data into organized format
const restructured = await analyzer.restructureAds(ads: MetaAdData[]);

// Extract company-specific data
const companyText = analyzer.extractCompanyText(text: string, companyName: string);

// Analyze a specific company
const analysis = await analyzer.getTopIdeasPerCompany(companyName: string, text: string);

// Generate industry insights
const industry = await analyzer.industryWriteup(analyses: CompanyAnalysisResult[]);

// Create ad concepts
const concepts = await analyzer.generateAdIdeas(
  companyAnalyses: CompanyAnalysisResult[],
  industryAnalysis: IndustryAnalysisResult,
  clientDetails: string
);

Main Function

performCompetitiveAnalysis(config: CompetitiveAnalysisConfig)

Performs a complete competitive analysis pipeline.

interface CompetitiveAnalysisConfig {
  clientDetails: string;
  competitors: Competitor[];
  scrapingOptions?: ScrapingOptions;
}

interface Competitor {
  name: string;
  url: string;
}

interface ScrapingOptions {
  maxResults?: number;
  useExistingRun?: boolean;
}

Types

interface MetaAdData {
  metadata: {
    page_name: string;
    ad_archive_id: string;
    scraped_at: string;
  };
  ad_content: {
    title: string;
    body: string;
    cta_text: string;
    cta_type: string;
    link_url: string;
    cards: Array<{
      title: string;
      body: string;
    }>;
  };
  distribution: {
    publisher_platform: string[];
  };
  status: {
    is_active: boolean;
  };
  performance: {
    impressions?: number;
    spend?: number;
    currency: string;
  };
}

interface CompetitiveAnalysisResult {
  clientDetails: string;
  competitors: Competitor[];
  totalAdsScraped: number;
  restructuredAds: string;
  companyAnalyses: CompanyAnalysisResult[];
  industryAnalysis: IndustryAnalysisResult;
  adConcepts: AdConceptResult;
  analysisMetadata: {
    timestamp: string;
    scrapingOptions?: ScrapingOptions;
    totalCompanies: number;
  };
}

Configuration

Environment Variables

# Required
APIFY_TOKEN=your-apify-token
GEMINI_API_KEY=your-gemini-api-key

# Optional
NODE_ENV=production

Meta Ad Library URLs

The scraper works with Meta Ad Library URLs in this format:

https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&search_type=page&view_all_page_id=PAGE_ID

Advanced Usage

Custom Analysis Pipeline

import { MetaAdsScraper, GeminiAnalyzer } from 'meta-ads-scraper';

async function customAnalysis() {
  const scraper = new MetaAdsScraper();
  const analyzer = new GeminiAnalyzer();
  
  // Scrape multiple competitors
  const allAds = [];
  for (const competitor of competitors) {
    const ads = await scraper.getAds(competitor.url);
    allAds.push(...ads);
  }
  
  // Custom analysis steps
  const restructured = await analyzer.restructureAds(allAds);
  
  // Process each company individually
  const analyses = [];
  for (const company of companies) {
    const companyText = analyzer.extractCompanyText(restructured.text, company);
    const analysis = await analyzer.getTopIdeasPerCompany(company, companyText);
    analyses.push(analysis);
  }
  
  return analyses;
}

Error Handling

try {
  const result = await performCompetitiveAnalysis(config);
  console.log('Analysis completed successfully');
} catch (error) {
  if (error.message.includes('API key')) {
    console.error('Invalid API key provided');
  } else if (error.message.includes('URL')) {
    console.error('Invalid Meta Ad Library URL');
  } else {
    console.error('Analysis failed:', error.message);
  }
}

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Changelog

v1.0.0

  • Initial release
  • Meta Ad Library scraping with Apify
  • AI-powered competitive analysis with Gemini 2.0 Flash
  • Complete TypeScript support
  • Smart caching and reuse of existing data