Meta Ads Library SDK

A modern, type-safe TypeScript SDK for the Facebook/Meta Ads Library API with a fluent chainable interface.

Features

• 🔗 Fluent Chainable API - Build queries with an intuitive method chaining pattern
• 📦 Zero Dependencies - Uses native fetch (Node.js 18+)
• 🔒 Type-Safe - Full TypeScript support with comprehensive type definitions
• 📄 Pagination Support - Built-in async iteration for handling large result sets
• ⚡ Modern ESM & CJS - Supports both module systems
• 🛡️ Error Handling - Typed error classes for better error management

Installation

npm install meta-ads-library

yarn add meta-ads-library

pnpm add meta-ads-library

Requirements

• Node.js 18.0.0 or higher
• Facebook Access Token with Ads Library API access

Quick Start

import { AdsLibraryClient } from 'meta-ads-library';

const client = new AdsLibraryClient({
  accessToken: 'your-facebook-access-token',
});

// Search for ads using the fluent API
const response = await client
  .query()
  .inCountries(['US'])
  .withSearchTerms('coffee')
  .activeOnly()
  .withFields(['id', 'page_name', 'ad_creative_bodies', 'spend'])
  .limit(100)
  .execute();

console.log(response.data); // Array of ads

Getting an Access Token

1. Go to Meta for Developers
2. Create or select an app
3. Navigate to the Graph API Explorer
4. Generate a User Access Token
5. For production, use a long-lived token or implement OAuth flow

Note: The Ads Library API may require additional app review for full access depending on your use case.

Usage

Creating a Client

import { AdsLibraryClient, createClient } from 'meta-ads-library';

// Using the class
const client = new AdsLibraryClient({
  accessToken: 'your-token',
  apiVersion: 'v24.0',    // Optional, defaults to v24.0
  timeout: 30000,          // Optional, defaults to 30000ms
});

// Using the helper function
const client2 = createClient('your-token', {
  apiVersion: 'v24.0',
});

Fluent Query Builder

The SDK provides a fluent API for building queries:

const ads = await client
  .query()
  // Required: Set target countries
  .inCountries(['US', 'GB', 'CA'])
  
  // Search options
  .withSearchTerms('technology')        // Search by keywords
  .withExactPhrase('artificial intelligence')  // Exact phrase match
  .byPageIds(['123456789'])             // Search by Page IDs
  
  // Filters
  .ofType('ALL')                        // 'ALL' or 'POLITICAL_AND_ISSUE_ADS'
  .activeOnly()                         // Only active ads
  .inactiveOnly()                       // Only inactive ads
  .allStatuses()                        // Both active and inactive
  
  // Date filters
  .deliveredAfter('2024-01-01')
  .deliveredBefore('2024-12-31')
  .deliveredBetween('2024-01-01', '2024-06-30')
  
  // Additional filters
  .inRegions(['California', 'New York'])
  .inLanguages(['en', 'es'])
  .withMediaType('VIDEO')               // 'ALL', 'IMAGE', 'VIDEO', 'MEME', 'NONE'
  .onPlatforms(['FACEBOOK', 'INSTAGRAM'])
  .onFacebook()                         // Shortcut for Facebook only
  .onInstagram()                        // Shortcut for Instagram only
  .withAudienceSize(1000, 100000)       // Min and max audience size
  .withBylines(['Paid for by Example']) // Filter by disclaimers
  
  // Response options
  .withFields(['id', 'page_name', 'ad_creative_bodies', 'spend'])
  .withAllFields()                      // Request all available fields
  .limit(100)                           // Results per page (max 500)
  
  // Execute
  .execute();                           // Returns full response
  // OR
  .getAds();                            // Returns just the ads array

Available Fields

type AdField =
  | 'id'
  | 'ad_creation_time'
  | 'ad_creative_bodies'
  | 'ad_creative_link_captions'
  | 'ad_creative_link_descriptions'
  | 'ad_creative_link_titles'
  | 'ad_delivery_start_time'
  | 'ad_delivery_stop_time'
  | 'ad_snapshot_url'
  | 'age_country_gender_reach_breakdown'
  | 'beneficiary_payers'
  | 'br_total_reach'
  | 'bylines'
  | 'currency'
  | 'delivery_by_region'
  | 'demographic_distribution'
  | 'estimated_audience_size'
  | 'eu_total_reach'
  | 'impressions'
  | 'languages'
  | 'page_id'
  | 'page_name'
  | 'publisher_platforms'
  | 'spend'
  | 'target_ages'
  | 'target_gender'
  | 'target_locations'
  | 'total_reach_by_location';

Pagination

Manual Pagination

const response = await client
  .query()
  .inCountries(['US'])
  .withSearchTerms('coffee')
  .limit(100)
  .execute();

// Check for next page
if (response.paging?.cursors?.after) {
  const nextPage = await client
    .query()
    .inCountries(['US'])
    .withSearchTerms('coffee')
    .limit(100)
    .after(response.paging.cursors.after)
    .execute();
}

Async Iteration (Recommended for Large Datasets)

// Iterate through all results
for await (const ad of client.query()
  .inCountries(['US'])
  .withSearchTerms('coffee')
  .iterate({ maxResults: 1000, delayMs: 100 })) {
  console.log(ad.page_name);
}

// Or fetch all at once (careful with memory)
const allAds = await client
  .query()
  .inCountries(['US'])
  .withSearchTerms('coffee')
  .fetchAll({ maxResults: 500 });

Using Raw Parameters

const response = await client.search({
  ad_reached_countries: ['US'],
  search_terms: 'coffee',
  ad_active_status: 'ACTIVE',
  ad_type: 'ALL',
  fields: ['id', 'page_name', 'ad_creative_bodies'],
  limit: 100,
});

Error Handling

import {
  AdsLibraryClient,
  ApiRequestError,
  ValidationError,
  NetworkError,
} from 'meta-ads-library';

try {
  const ads = await client
    .query()
    .inCountries(['US'])
    .withSearchTerms('coffee')
    .execute();
} catch (error) {
  if (error instanceof ApiRequestError) {
    // API returned an error
    console.error('API Error:', error.message);
    console.error('Error Code:', error.code);
    console.error('Error Type:', error.type);
  } else if (error instanceof ValidationError) {
    // Invalid parameters
    console.error('Validation Error:', error.message);
  } else if (error instanceof NetworkError) {
    // Network issues (timeout, connection, etc.)
    console.error('Network Error:', error.message);
  }
}

Standalone Query Builder

You can also use the QueryBuilder separately:

import { QueryBuilder } from 'meta-ads-library';

const builder = new QueryBuilder()
  .inCountries(['US'])
  .withSearchTerms('technology')
  .activeOnly();

// Clone and modify
const euBuilder = builder.clone().inCountries(['DE', 'FR']);

// Get params without executing
const params = builder.build();
console.log(params);

API Reference

AdsLibraryClient

| Method | Description | |--------|-------------| | query() | Creates a new chainable query builder | | search(params) | Execute a search with raw parameters | | fetchNextPage(cursor, params) | Fetch the next page of results | | iterate(params, options) | Async generator for all results | | fetchAll(params, options) | Fetch all results as an array |

ChainableQuery Methods

| Method | Description | |--------|-------------| | inCountries(countries) | Set target countries (required) | | withSearchTerms(terms) | Search by keywords | | withExactPhrase(phrase) | Search for exact phrase | | byPageIds(pageIds) | Search by Page IDs | | ofType(type) | Set ad type filter | | activeOnly() | Only active ads | | inactiveOnly() | Only inactive ads | | deliveredAfter(date) | Filter by min date | | deliveredBefore(date) | Filter by max date | | withFields(fields) | Select response fields | | limit(count) | Set results per page | | execute() | Execute and return response | | getAds() | Execute and return ads array | | iterate(options) | Async iterate through all | | fetchAll(options) | Fetch all as array | | first() | Get first result | | count(options) | Count total results |

Regional Availability

| Ad Type | Availability | |---------|--------------| | POLITICAL_AND_ISSUE_ADS | Worldwide | | ALL | EU and UK only |

Rate Limits

The Ads Library API has rate limits. Consider:

• Using delayMs option when iterating
• Implementing retry logic with exponential backoff
• Caching results when appropriate

TypeScript Support

This package is written in TypeScript and provides full type definitions:

import type {
  Ad,
  AdsLibraryResponse,
  AdsLibraryQueryParams,
  AdField,
  InsightsRangeValue,
} from 'meta-ads-library';

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Disclaimer

This is an unofficial SDK and is not affiliated with, endorsed by, or in any way officially connected with Meta Platforms, Inc. (formerly Facebook, Inc.) or any of its subsidiaries or affiliates.

The official Meta/Facebook website can be found at https://www.facebook.com. The names "Facebook," "Meta," and related trademarks are registered trademarks of Meta Platforms, Inc.

By using this SDK, you agree to:

• Comply with Meta's Terms of Service
• Comply with Meta Platform Terms
• Comply with Ad Library API Terms
• Use the data responsibly and in accordance with applicable laws

The authors of this package are not responsible for any misuse or any violations of Meta's terms of service.

License

MIT ©

Links

• Facebook Ad Library
• Ad Library API Documentation
• Meta for Developers
• Graph API Explorer