New Integration: Semrush

Description

Add Semrush integration to sync SEO analytics, keyword research, domain data, and traffic insights into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github/ - API-based data integration
• integrations/linear/ - Project management integration
• integrations/slack/ - For reference

Required Files Structure

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

Semrush API Integration

Authentication Setup

• Use API Key authentication
• API key generated from Account tab > Subscription info > API Units
• Requires Semrush Business subscription for Standard API access
• Base URL: https://api.semrush.com

Key Endpoints

• GET /analytics/v1/?type=domain_ranks - Domain overview and rankings
• GET /analytics/v1/?type=domain_organic - Organic search positions
• GET /analytics/v1/?type=domain_adwords - Paid search data
• GET /analytics/v1/?type=phrase_all - Keyword overview
• GET /analytics/v1/?type=phrase_organic - Organic results for a keyword
• GET /analytics/ta/api/v3/ - Traffic Analytics endpoints
• GET /analytics/v1/?type=backlinks_overview - Backlink data
• GET /analytics/v1/?type=domain_rank_history - Historical ranking data

Events to Track

1. Domain Analytics - Domain ranking changes, organic/paid position shifts
2. Keyword Research - Keyword performance, search volume changes
3. Traffic Analytics - Website traffic trends and visitor metrics
4. Backlinks - New/lost backlink events
5. Position Tracking - SERP position changes over time

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 domain analytics, keyword, and traffic endpoints
• Implement sync logic in schedule.ts for periodic SEO data pulls
• Convert SEO metrics and ranking changes to CORE activity format
• Add error handling and rate limiting (API unit consumption tracking)
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Standard API package requires Business subscription plan
• API usage is measured in "API units" - track consumption carefully
• Traffic Analytics API (v3) is a separate endpoint from the standard analytics API
• Data can be filtered by database (country), display date, and export columns
• Response format is typically semicolon-separated values, not JSON - needs parsing

Resources

• Semrush API Documentation
• Traffic Analytics API
• Semrush Developer Portal

Labels

enhancement, integration, new-feature