New Integration: Similarweb

Description

Add Similarweb integration to sync web analytics, traffic data, competitor analysis, and market intelligence into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github-analytics/ - Similar analytics-focused integration
• integrations/linear/ - Project management integration
• integrations/slack/ - For reference

Required Files Structure

integrations/similarweb/
├── src/
│   ├── index.ts          # Main entry, API key spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Similarweb API utilities
│   ├── account-create.ts # API key setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Similarweb API Integration

Authentication Setup

• Use API Key authentication (subscription add-on)
• API key passed as query parameter or header
• Available through Similarweb account subscription

Key APIs

• REST API (V5) - Real-time individual HTTP requests
  • GET /v1/website/{domain}/total-traffic-and-engagement/visits - Total visits
  • GET /v1/website/{domain}/traffic-sources/overview - Traffic sources breakdown
  • GET /v1/website/{domain}/search-competitors/organic-competitors - Organic competitors
  • GET /v1/website/{domain}/audience-interests/also-visited - Also visited sites
  • GET /v1/website/{domain}/geo/traffic-by-country - Geographic traffic distribution
  • GET /v1/website/{domain}/mobile-web/visits - Mobile traffic data
• Batch API - Large-scale data extraction
  • Submit bulk data extraction jobs
  • Asynchronous processing with result retrieval
  • Ideal for multi-domain analysis

Data Categories

• Total Traffic & Engagement (visits, bounce rate, pages/visit, visit duration)
• Traffic Sources (direct, referral, search, social, email, display)
• Search Traffic (organic vs paid, keyword analysis)
• Referral Traffic (referring domains and pages)
• Audience Interests (categories, also-visited, cross-browsing)
• Geographic Distribution (traffic by country)
• Mobile vs Desktop breakdown

Events to Track

1. Traffic Changes - Significant traffic increases/decreases, trend shifts
2. Competitor Analysis - New competitor appearances, ranking changes
3. Search Performance - Keyword ranking changes, organic/paid traffic shifts
4. Audience Insights - Geographic shifts, interest category changes
5. Benchmark Updates - Industry benchmark comparisons, market share changes

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement API key authentication flow in account-create.ts
• Create API utilities in utils.ts for REST and Batch APIs
• Implement sync logic in schedule.ts for traffic data, competitors, and audience insights
• Convert web analytics events to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Similarweb API is a paid subscription add-on - requires account with API access
• REST API provides real-time data; Batch API is for large-scale extraction
• Data is typically available with a monthly granularity and some delay
• Supports analysis use cases: marketing optimization, SEO/SEM, CRM enrichment, travel audience analysis, investment research
• API V5 is the latest version

Resources

• Similarweb Developer Portal
• Similarweb API V5 Documentation
• API Solutions Overview
• Batch API Guide
• API Endpoints List

Labels

enhancement, integration, new-feature