Spotbookr for Developers

Query millions of ads by brand, platform, date range, and engagement metrics. Sort and filter results to find exactly what you need.

import spotbookr

client = spotbookr.Client(api_key='your_api_key')

# Search for Nike ads on Meta in the last 30 days
results = client.ads.search(
    brand='Nike',
    platform='meta',
    date_range='last_30_days',
    limit=100,
    sort_by='engagement_index'
)

for ad in results:
    print(f"Ad ID: {ad.id}")
    print(f"Text: {ad.creative_text}")
    print(f"Engagement Index: {ad.sbkr_engagement_index}")
    print(f"Platform: {ad.platform}")
    print(f"---")

Returns: Array of ad objects with creative content, metadata, performance indexes, and targeting information.

Discover top performing ads in any industry with our trending endpoint. Filter by platform, timeframe, and minimum engagement thresholds.

// Node.js example
const Spotbookr = require('spotbookr');
const client = new Spotbookr('your_api_key');

// Get top performing fitness ads this week
const trending = await client.ads.trending({
  industry: 'fitness',
  timeframe: 'week',
  platforms: ['meta', 'tiktok'],
  min_engagement_index: 50,
  limit: 50
});

trending.forEach(ad => {
  console.log(`${ad.brand} - ${ad.format}`);
  console.log(`Engagement: ${ad.sbkr_engagement_index}`);
  console.log(`Creative URL: ${ad.creative_url}\n`);
});

Returns: Top performing ads sorted by engagement index with full creative assets and performance data.

Set up real-time webhooks to receive instant notifications when competitors launch new campaigns or when ads matching your criteria are discovered.

# Create a webhook for new competitor ads
import spotbookr

client = spotbookr.Client(api_key='your_api_key')

webhook = client.webhooks.create(
    url='https://your-domain.com/webhook-handler',
    event_type='ad.created',
    filters={
        'brands': ['Competitor A', 'Competitor B', 'Competitor C'],
        'platforms': ['meta', 'google', 'tiktok'],
        'min_spend_index': 30
    }
)

print(f"Webhook created: {webhook.id}")
print(f"Status: {webhook.status}")

# Your webhook endpoint will receive:
# POST https://your-domain.com/webhook-handler
# {
#   "event": "ad.created",
#   "timestamp": "2026-01-28T12:00:00Z",
#   "data": {
#     "ad_id": "abc123",
#     "brand": "Competitor A",
#     "platform": "meta",
#     "creative_text": "...",
#     "sbkr_spend_index": 45.2
#   }
# }

Returns: Webhook configuration object with subscription details and delivery status tracking.

Get aggregated trend data for any category or metric. Analyze spend patterns, engagement trends, and identify growing brands over time.

# Ruby example
require 'spotbookr'

client = Spotbookr::Client.new('your_api_key')

# Get ad spend trends for e-commerce category
trends = client.analytics.trends(
  category: 'ecommerce',
  metric: 'spend_index',
  timeframe: 'last_90_days',
  granularity: 'week',
  platforms: ['meta', 'google']
)

trends.data_points.each do |point|
  puts "Week of #{point.date}: #{point.avg_spend_index}"
end

puts "\nTop growing brands:"
trends.top_brands.each do |brand|
  puts "#{brand.name}: +#{brand.growth_rate}%"
end

Returns: Time-series data with aggregated metrics, top brands, and growth rates for comprehensive market analysis.

Build internal competitive intelligence dashboards with your own branding, layouts, and KPIs integrated with existing analytics tools. Transform raw ad data into actionable insights your team can act on immediately.

Common Implementations:

• Executive Dashboards: High-level views showing competitor ad spend trends, market share shifts, and strategic positioning across platforms
• Creative Team Portals: Visual galleries displaying top performing ad formats, messaging strategies, and creative elements by industry or competitor
• Performance Benchmarking: Side-by-side comparisons of your ads versus competitors with engagement indexes, spend estimates, and trend lines
• Real-Time Monitoring: Live dashboards tracking specific brands, product categories, or seasonal campaigns with automatic refresh
• BI Tool Integration: Custom data feeds into Tableau, Power BI, Looker, or Data Studio with pre-built dashboard templates

Technical Features:

• RESTful API endpoints for real-time data fetching
• Webhook subscriptions for automatic dashboard updates
• Customizable aggregation queries for performance metrics
• OAuth2 authentication for secure single sign-on
• Export capabilities for presentations and reports

Example Use Case:

A D2C e-commerce brand built a custom React dashboard pulling data from Spotbookr API to track their top 10 competitors' Meta and TikTok campaigns. The dashboard updates hourly, showing new ad launches, spend trends, and creative themes. Their marketing team uses it daily to identify winning strategies and react to competitive moves within hours instead of weeks.

Create real-time alerting systems that notify teams when competitors launch campaigns or change strategies. Never miss a competitive move with instant notifications delivered to your preferred channels.

Common Implementations:

• Slack/Teams Integration: Real-time notifications when competitors launch new creative campaigns, with ad previews and engagement data
• Email Alert Systems: Daily or triggered emails for significant spend increases, new product launches, or seasonal campaign starts
• SMS Notifications: Urgent alerts for critical competitive moves like price promotions, new market entries, or major creative pivots
• Competitive Digests: Automated reports delivered daily or weekly with top competitor activities, trending ads, and market insights
• Smart Watchlists: Custom monitoring for specific brands, keywords, ad formats, or creative themes with configurable alert thresholds

Alert Triggers Available:

• New ads from monitored competitors
• Spend index changes above custom thresholds
• Engagement performance spikes or drops
• New creative formats or messaging angles
• Platform expansion (competitor launches on new channel)
• Landing page changes or promotion updates

Example Use Case:

A B2B SaaS company monitors 25 competitors across LinkedIn, Google, and Meta. When a competitor launches a new campaign with their SBKr Spend Index above 40, the marketing team receives a Slack notification with the ad creative, headline, and CTA. This helped them respond to a competitor's aggressive pricing campaign within 24 hours, minimizing customer churn.

Train machine learning models on millions of ads for creative optimization, spend prediction, and trend forecasting. Leverage our comprehensive historical data to build AI systems that give you a competitive edge.

Common Implementations:

• Performance Prediction: Train models on historical ad data to predict engagement and conversion potential before launching campaigns
• NLP for Copy Analysis: Natural language processing to identify successful messaging patterns, emotional triggers, and conversion-driving language
• Computer Vision for Creatives: Image classification models to detect winning visual elements, color schemes, layouts, and design patterns
• Recommendation Systems: Build engines that suggest optimal creative strategies, targeting approaches, and budget allocation based on competitive intelligence
• Trend Forecasting: Time-series analysis and predictive algorithms to anticipate market shifts, seasonal patterns, and emerging creative trends

Available Training Data:

• 100M+ ads across Meta, TikTok, Google, YouTube, and more
• Historical performance indexes and engagement metrics
• Creative assets (images, videos, ad copy, headlines)
• Temporal data for trend analysis and seasonality detection
• Platform-specific metadata and targeting information
• Brand categorization and industry vertical labels

Example Use Case:

An AI startup built a creative scoring engine using Spotbookr's API to train on 2 years of fitness industry ads. Their model analyzes new ad concepts and predicts performance with 78% accuracy. Marketing teams use it to pre-test creative variations before spending on production, reducing creative waste by 40% and improving campaign ROI by 2.3x.

Embed competitive ad intelligence into existing SaaS products, marketing platforms, or agency workflows. Add powerful competitive features to your product without building the data infrastructure.

Common Implementations:

• Marketing Automation Platforms: Add competitive insights to HubSpot, Marketo, or Salesforce Marketing Cloud with custom modules showing competitor activity
• CRM Enhancement: Surface competitor advertising data inside Salesforce, Pipedrive, or HubSpot CRM for sales intelligence and competitive positioning
• Agency Tools: Build competitive analysis features into client dashboards, media planning tools, or creative collaboration platforms
• Project Management: Integrate ad intelligence into Asana, Monday.com, or Notion for campaign planning and competitive tracking
• No-Code Automation: Create Zapier, Make.com, or n8n integrations connecting Spotbookr data to thousands of apps

Integration Methods:

• RESTful API for on-demand data fetching
• Webhooks for real-time event-driven updates
• OAuth2 for secure user authentication
• Embeddable widgets and iframes
• Custom API keys for multi-tenant applications
• Rate limiting and quota management per integration

Example Use Case:

A marketing SaaS platform integrated Spotbookr API to add a "Competitive Intelligence" tab in their product. Users can now see what their competitors are advertising without leaving the platform. This feature became their #1 differentiator in sales calls and increased their average contract value by 35%.

Generate automated competitive analysis reports, market research documents, and executive summaries. Save hours of manual research and deliver consistent, data-driven insights to stakeholders.

Common Implementations:

• Weekly Intelligence Reports: Automated reports highlighting new competitor campaigns, top performing ads, and emerging creative trends
• Monthly Market Analysis: Comprehensive documents with spend trends, platform shifts, industry benchmarks, and strategic recommendations
• Quarterly Executive Summaries: High-level presentations with competitive landscape overview, market share analysis, and actionable insights
• Custom PDF Generation: Branded reports for clients or internal stakeholders with dynamic charts, ad screenshots, and performance metrics
• Email Digests: Scheduled summaries delivered directly to inboxes with key competitive movements and trending ads

Report Components Available:

• Competitor activity summaries with ad counts and spend indexes
• Top performing ads with creative previews and metrics
• Platform distribution charts (Meta vs TikTok vs Google)
• Trend analysis with week-over-week or month-over-month comparisons
• Creative theme categorization and messaging analysis
• Landing page changes and promotional tactics

Example Use Case:

A digital agency automated their client reporting by pulling data from Spotbookr API every Monday morning. The system generates custom PDFs showing each client's competitors' advertising activity from the past week, complete with creative screenshots and performance insights. This saves 15 hours of analyst time per week and allows them to service 3x more clients without hiring additional staff.