Full adlibrary API Documentation and Implementation Guide

// Major markets
"targetLocation": "US"    // United States
"targetLocation": "CA"    // Canada  
"targetLocation": "GB"    // United Kingdom
"targetLocation": "DE"    // Germany
"targetLocation": "FR"    // France
"targetLocation": "IT"    // Italy
"targetLocation": "ES"    // Spain
"targetLocation": "NL"    // Netherlands
"targetLocation": "AU"    // Australia
"targetLocation": "JP"    // Japan
"targetLocation": "BR"    // Brazil
"targetLocation": "MX"    // Mexico
"targetLocation": "IN"    // India
"targetLocation": "SG"    // Singapore

{
  "success": true,
  "data": {
    "ads": [/* AdData[] */],
    "advertisers": [/* AdvertiserData[] */], 
    "hasMore": false,
    "totalAds": 156,
    "totalAdvertisers": 23
  },
  "meta": {
    "query": "search terms used",
    "platforms": ["platforms searched"],
    "totalResults": 156,
    "totalAdvertisers": 23,
    "authMethod": "general_token|basic_auth",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

{
  "id": "string",                    // Unique ad identifier
  "platform": "meta|google",        // Platform where ad was found
  "page_name": "string",             // Advertiser/page name
  "ad_url": "string",                // URL to view the ad
  "titles": ["string"],              // Ad headlines/titles
  "descriptions": ["string"],        // Ad descriptions
  "captions": ["string"],            // Ad captions/CTAs  
  "reach": 45000,                    // Estimated reach (number)
  "platforms": ["facebook", "instagram"], // Platforms where ad ran
  "page_id": "string",               // Platform-specific page ID
  "spend": 3500,                     // Estimated spend (number or string)
  "website": "string",               // Landing page domain
  "target_locations": [/* array */], // Geographic targeting info
  "targetsDACH": true,               // Whether targets DACH region
  "targetedCountries": ["DE", "AT"]  // Specific countries targeted
}

{
  "advertiser": "string",            // Advertiser name
  "platform": "meta|google",        // Platform
  "adCount": 15,                     // Number of ads found
  "totalReach": 45000,               // Combined reach across ads
  "totalSpend": 3500,                // Combined spend across ads
  "landingDomain": "example.com",    // Primary landing domain
  "ads": [/* AdData[] */]            // All ads from this advertiser
}

{
  "error": "User-friendly error message",
  "code": "ERROR_CODE_IDENTIFIER", 
  "severity": "low|medium|high|critical"
}

{
  "query": "fitness app"
}

{
  "query": "electric vehicles",
  "platforms": ["meta", "google"]
}

{
  "query": "luxury hotels", 
  "filters": {
    "targetLocation": "EU",
    "adType": "IMAGE"
  }
}

{
  "query": "black friday deals",
  "filters": {
    "dateRange": {
      "start": "2024-11-01",
      "end": "2024-11-30" 
    },
    "pageSize": 100
  }
}

{
  "query": "project management software",
  "platforms": ["meta", "google"],
  "filters": {
    "targetLocation": "NA",
    "desiredAdvertisers": 25,
    "limit": 500,
    "exactMatch": false
  }
}

{
  "query": "online courses",
  "filters": {
    "adType": "VIDEO", 
    "targetLocation": "DACH",
    "pageSize": 50
  }
}

{
  "query": "cryptocurrency",
  "platforms": ["meta", "google"],
  "filters": {
    "pageSize": 200,
    "desiredAdvertisers": 100, 
    "limit": 1000,
    "targetLocation": "APAC"
  }
}

const searchAds = async (query, options = {}) => {
  const response = await fetch('https://adlibrary.com/api/v1/search', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query,
      platforms: options.platforms || ['meta'],
      filters: {
        targetLocation: options.location || 'US',
        adType: options.adType || 'ALL',
        pageSize: options.pageSize || 50,
        ...options.filters
      }
    })
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error} (${error.code})`);
  }
  
  return response.json();
};

// Usage
const results = await searchAds('sustainable fashion', {
  location: 'EU',
  adType: 'VIDEO',
  pageSize: 100
});

import requests
import base64

class AdLibraryAPI:
    def __init__(self, api_token=None, email=None, password=None):
        self.base_url = 'https://adlibrary.com/api/v1'
        if api_token:
            self.headers = {
                'Authorization': f'Bearer {api_token}',
                'Content-Type': 'application/json'
            }
        elif email and password:
            credentials = base64.b64encode(f'{email}:{password}'.encode()).decode()
            self.headers = {
                'Authorization': f'Basic {credentials}',
                'Content-Type': 'application/json'
            }
    
    def search(self, query, **kwargs):
        payload = {'query': query}
        
        if 'platforms' in kwargs:
            payload['platforms'] = kwargs['platforms']
            
        filters = {}
        filter_keys = ['adType', 'targetLocation', 'dateRange', 'exactMatch', 
                      'pageSize', 'desiredAdvertisers', 'limit']
        
        for key in filter_keys:
            if key in kwargs:
                filters[key] = kwargs[key]
                
        if filters:
            payload['filters'] = filters
            
        response = requests.post(
            f'{self.base_url}/search',
            headers=self.headers,
            json=payload
        )
        
        if response.status_code != 200:
            error_data = response.json()
            raise Exception(f"API Error: {error_data['error']} ({error_data['code']})")
            
        return response.json()

# Usage
api = AdLibraryAPI(api_token='your_token_here')
results = api.search(
    'cryptocurrency trading',
    platforms=['meta', 'google'],
    targetLocation='NA',
    adType='VIDEO',
    pageSize=100
)

#!/bin/bash

API_TOKEN="your_api_token_here"
BASE_URL="https://adlibrary.com/api/v1"

search_ads() {
    local query="$1"
    local location="${2:-US}"
    local ad_type="${3:-ALL}"
    local page_size="${4:-50}"
    
    curl -s -X POST "$BASE_URL/search" \
        -H "Authorization: Bearer $API_TOKEN" \
        -H "Content-Type: application/json" \
        -d "{
            \"query\": \"$query\",
            \"filters\": {
                \"targetLocation\": \"$location\",
                \"adType\": \"$ad_type\", 
                \"pageSize\": $page_size
            }
        }" | jq .
}

# Usage
search_ads "fitness apps" "EU" "VIDEO" 100