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

Start by reading integrations/github/src/index.ts and the corresponding integration structure in integrations/linear/ and integrations/slack/. Then review the Semrush API documentation and determine how the listed endpoints, authentication, response parsing, rate limits, and activity mapping fit the required files. Done means the integration is registered, documented, syncs the requested SEO data, and handles API errors and unit consumption.