README

Framework-agnostic PHP SDK for SEMrush API v3/v4 - Analytics, Trends, Projects, and Local API.

Features

🔌 Framework Agnostic - Works with Laravel, Yii2, Symfony, or plain PHP
📊 Analytics API v3 - Domain, Keyword, Backlink, and URL reports
📈 Trends API - Traffic and market data analysis
🔧 Projects API - Site Audit and Position Tracking
📍 Local API - Listing Management and Map Rank Tracker
🔄 Multiple Auth Methods - API Key (v3) and OAuth2 (v4)
📝 CSV & JSON Support - Automatic parsing based on endpoint
🛡️ Error Handling - Custom exceptions for API errors

Installation

composer require kalimeromk/semrush-api

Quick Start

use Kalimeromk\SemrushApi\Auth\ApiKeyAuthentication;
use Kalimeromk\SemrushApi\Client\SemrushClient;

// Initialize with API Key
$auth = new ApiKeyAuthentication('your_api_key');
$client = new SemrushClient($auth);

// Get domain organic keywords
$keywords = $client->analytics()->domainOrganic('example.com', 'us', [
    'display_limit' => 10,
]);

foreach ($keywords as $keyword) {
    echo $keyword['Ph'] . ' - Position: ' . $keyword['Po'] . "\n";
}

Framework Integration

Quick Example

// Laravel
class SeoController extends Controller
{
    public function __construct(private SemrushClient $semrush) {}
    
    public function index()
    {
        $data = $this->semrush->analytics()->domainOverview('example.com');
        return view('seo.report', compact('data'));
    }
}

// Yii2
$keywords = Yii::$app->semrush->analytics()->domainOrganic('example.com');

// Symfony
public function index(SemrushClient $semrush)
{
    $data = $semrush->analytics()->domainOverview('example.com');
    return $this->json($data->toArray());
}

API Reference

Analytics API

// Domain Overview
$client->analytics()->domainOverview('example.com', 'us');
$client->analytics()->domainRank('example.com', 'us'); // Single database
$client->analytics()->domainRankHistory('example.com', 'us'); // Historical data

// Organic Keywords
$client->analytics()->domainOrganic('example.com', 'us', [
    'display_limit' => 100,
    'export_columns' => 'Ph,Po,Nq,Cp,Ur,Tr',
]);

// Paid Keywords
$client->analytics()->domainAdwords('example.com', 'us');

// Keyword Research
$client->analytics()->keywordOverview('seo tools', 'us');
$client->analytics()->relatedKeywords('seo tools', 'us', 10);
$client->analytics()->keywordDifficulty('seo tools', 'us');
$client->analytics()->phraseQuestions('seo tools', 'us'); // Question keywords
$client->analytics()->phraseFullsearch('seo tools', 'us'); // Full search keywords

// Winners & Losers
$client->analytics()->rankDifference('us'); // Domains that gained/lost most

// Backlinks
$client->analytics()->backlinksOverview('example.com');
$client->analytics()->backlinks('example.com');
$client->analytics()->referringDomains('example.com');
$client->analytics()->backlinksTld('example.com'); // TLD distribution
$client->analytics()->backlinksGeo('example.com'); // Geographic distribution
$client->analytics()->backlinksCompetitors('example.com'); // Similar link profiles
$client->analytics()->backlinksHistorical('example.com'); // Historical trends
$client->analytics()->backlinksComparison(['example.com', 'competitor.com']); // Batch compare
$client->analytics()->backlinksAscoreProfile('example.com'); // Authority Score distribution
$client->analytics()->backlinksCategories('example.com'); // Domain categories
$client->analytics()->backlinksCategoriesProfile('example.com'); // Category profile

// URL Reports
$client->analytics()->urlOrganic('https://example.com/page', 'us');

// Keyword Gap Analysis
$client->analytics()->keywordGap(['domain1.com', 'domain2.com'], 'us');

Trends API

// Traffic Summary
$client->trends()->summary('example.com', '2024-01-01', 'US');

// Traffic Sources
$client->trends()->trafficSources('example.com', 'US');

// Geographic Distribution
$client->trends()->geoDistribution('example.com');

// Audience Insights (Premium)
$client->trends()->audienceInsights('example.com');
$client->trends()->ageSexDistribution('example.com');

Projects API

// List projects
$client->projects()->listProjects();

// Get project
$client->projects()->getProject($projectId);

// Create project
$client->projects()->createProject('My Project', 'example.com');

// Site Audit
$client->projects()->listSiteAudits($projectId);
$client->projects()->getSiteAuditHistory($projectId);

// Position Tracking
$client->projects()->listPositionTracking($projectId);
$client->projects()->getRankings($projectId, $campaignId);

Local API (OAuth2)

use Kalimeromk\SemrushApi\Auth\OAuth2Authentication;

$oauth = new OAuth2Authentication('access_token');
$client = new SemrushClient($oauth);

// Listing Management
$client->local()->getLocations();
$client->local()->getLocation($locationId);
$client->local()->updateLocation($locationId, [...]);

// Map Rank Tracker
$client->local()->getMapRankCampaigns();
$client->local()->getMapRankKeywords($campaignId);
$client->local()->getMapRankHeatmap($campaignId, $keywordId);

Error Handling

use Kalimeromk\SemrushApi\Exceptions\RateLimitException;
use Kalimeromk\SemrushApi\Exceptions\AuthenticationException;

try {
    $data = $client->analytics()->domainOrganic('example.com');
} catch (RateLimitException $e) {
    // Handle rate limit
    $retryAfter = $e->getRetryAfter();
} catch (AuthenticationException $e) {
    // Handle auth error
} catch (\Kalimeromk\SemrushApi\Exceptions\SemrushApiException $e) {
    // Handle API error
    echo $e->getMessage();
    echo $e->getHttpCode();
    echo $e->getResponseBody();
}

Response Handling

$response = $client->analytics()->domainOrganic('example.com');

// As array
$array = $response->toArray();

// As JSON string
$json = $response->toJson();

// Iterate results
foreach ($response as $item) {
    echo $item['Ph']; // Keyword phrase
}

// Get first result
$first = $response->first();

// Check count
$count = $response->count();

Testing

# Run all tests
composer test

# Run unit tests only
composer test:unit

# Run integration tests (requires API key)
composer test:integration

License

MIT License. See LICENSE file.

Support

For issues and feature requests, please use GitHub Issues.

Note: This package is not affiliated with or endorsed by SEMrush. SEMrush is a trademark of SEMrush Inc.

kalimeromk / semrush-api

Maintainers

Package info

Statistics

Security