SEO Intelligence Integration¶

Document Version: 1.0 Last Updated: December 2025 Status: Production

Overview¶

Vell's SEO Intelligence feature provides comprehensive SEO analysis powered by DataForSEO APIs. This integration enables:

Domain Overview: Organic/paid traffic estimates, keyword rankings
Competitor Discovery: Find competing domains with keyword overlap
Keyword Analysis: Ranked keywords, search volume, positions
Technology Detection: Identify tech stack of any domain
Backlink Analysis: Referring domains, domain authority, link profile
LLM Mentions Tracking: AI visibility across ChatGPT, Claude, Perplexity

Architecture¶

DataForSEO Client¶

Location: app/Services/DataForSEO/DataForSEOClient.php

The DataForSEOClient provides a unified interface to multiple DataForSEO API endpoints:

┌─────────────────────────────────────────────────────────────────┐
│                    SEO Intelligence Layer                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────┐    ┌──────────────────┐                  │
│  │ SeoIntelligence  │    │  Marketplace     │                  │
│  │   Controller     │    │  SEOMiddleware   │                  │
│  └────────┬─────────┘    └────────┬─────────┘                  │
│           │                        │                            │
│  ┌────────▼────────────────────────▼─────────┐                 │
│  │            DataForSEOClient                │                 │
│  │  • Domain Analytics API                    │                 │
│  │  • DataForSEO Labs API                     │                 │
│  │  • Content Analysis API                    │                 │
│  │  • Backlinks API                           │                 │
│  │  • On-Page API                             │                 │
│  │  • LLM Mentions API                        │                 │
│  └────────────────────┬───────────────────────┘                │
│                       │                                         │
└───────────────────────┼─────────────────────────────────────────┘
                        │
            ┌───────────▼───────────┐
            │   DataForSEO API      │
            │   api.dataforseo.com  │
            └───────────────────────┘

API Endpoints Reference¶

DataForSEO Labs API¶

Method	Endpoint	Purpose	Cost
`getLabsDomainOverview()`	`/dataforseo_labs/google/domain_rank_overview/live`	Domain traffic, keyword counts	~$0.05
`getCompetitors()`	`/dataforseo_labs/google/competitors_domain/live`	Find competing domains	~$0.05
`getRankedKeywords()`	`/dataforseo_labs/google/ranked_keywords/live`	Keywords domain ranks for	~$0.05
`getKeywordIdeas()`	`/dataforseo_labs/google/keyword_ideas/live`	Related keyword suggestions	~$0.05
`getDomainIntersection()`	`/dataforseo_labs/google/domain_intersection/live`	Shared keywords between domains	~$0.05

Domain Analytics API¶

Method	Endpoint	Purpose	Cost
`getDomainOverview()`	`/domain_analytics/overview/live`	Basic domain metrics	~$0.001
`getDomainTechnologies()`	`/domain_analytics/technologies/domain_technologies/live`	Tech stack detection	~$0.002
`getDomainWhois()`	`/domain_analytics/whois/live`	WHOIS information	~$0.002

Backlinks API¶

Method	Endpoint	Purpose	Cost
`getBacklinksSummary()`	`/backlinks/summary/live`	Backlink overview	~$0.002
`getBacklinks()`	`/backlinks/backlinks/live`	Detailed backlink list	~$0.0004/link
`getReferringDomains()`	`/backlinks/referring_domains/live`	List of referring domains	~$0.002
`getBacklinkCompetitors()`	`/backlinks/competitors/live`	Backlink competitors	~$0.002

LLM Mentions API (AI Optimization)¶

Method	Endpoint	Purpose	Cost
`searchLlmMentions()`	`/ai_optimization/llm_mentions/search/live`	Search for AI mentions	~$0.15
`getLlmAggregatedMetrics()`	`/ai_optimization/llm_mentions/aggregated_metrics/live`	Aggregated AI visibility	~$0.10
`getLlmTopDomains()`	`/ai_optimization/llm_mentions/top_domains/live`	Top mentioned domains	~$0.10
`getLlmTopPages()`	`/ai_optimization/llm_mentions/top_pages/live`	Top mentioned pages	~$0.10

Response Formats¶

Domain Rank Overview Response¶

The domain_rank_overview endpoint returns metrics in the following structure:

{
  "tasks": [{
    "status_code": 20000,
    "status_message": "Ok.",
    "result": [{
      "se_type": "google",
      "target": "example.com",
      "location_code": 2840,
      "items": [{
        "metrics": {
          "organic": {
            "etv": 15234.5,        // Estimated Traffic Value
            "count": 1250,         // Number of keywords
            "pos_1": 15,           // Keywords in position 1
            "pos_2_3": 45,         // Keywords in positions 2-3
            "pos_4_10": 180,       // Keywords in positions 4-10
            "is_new": 23,          // New keywords this period
            "is_lost": 8           // Lost keywords this period
          },
          "paid": {
            "etv": 0,
            "count": 0
          }
        }
      }]
    }]
  }]
}

Important: The domain_rank_overview endpoint returns metrics inside result[0].items[0].metrics, not directly in result[0].metrics.

Competitors Domain Response¶

{
  "tasks": [{
    "result": [{
      "items": [{
        "domain": "competitor.com",
        "intersection_count": 450,     // Common keywords
        "full_domain_metrics": {
          "organic": {
            "etv": 25000,
            "count": 3200
          }
        }
      }]
    }]
  }]
}

Configuration¶

Admin Settings¶

Navigate to Admin > Settings > DataForSEO to configure:

API Credentials
DataForSEO Login (email)
DataForSEO Password (API password, not account password)
API Features (enable/disable individually)
Domain Analytics API (~$0.001-0.002/request)
DataForSEO Labs API (~$0.05/request)
Content Analysis API (~$0.002/request)
Backlinks API (~$0.002/request)
On-Page API (~$0.002/audit)
LLM Mentions API (~$0.10-0.15/request)
Advanced Settings
API Timeout (30-300 seconds)
Default Location (US, UK, CA, AU, DE)
Daily Spending Limit (USD)
Cache Duration (1-168 hours)

Marketplace SEO Middleware¶

The Marketplace SEO Middleware (MarketplaceSEOMiddleware.php) aggregates backlinks and LLM mentions data for AWS Marketplace listings, providing structured insights to AgentCore capabilities.

Settings: - marketplace_seo_middleware_enabled: Enable/disable the middleware - marketplace_seo_cache_ttl: Cache TTL in minutes (default: 60)

Usage Examples¶

Controller Usage¶

use App\Services\DataForSEO\DataForSEOClient;

class MyController extends Controller
{
    public function analyze(Request $request)
    {
        $client = new DataForSEOClient();

        // Check if API is enabled
        if (!$client->isApiEnabled('labs')) {
            return response()->json(['error' => 'Labs API not enabled'], 403);
        }

        // Get domain overview
        $response = $client->getLabsDomainOverview('example.com', 'United States');

        // Parse response (note: metrics are in items[0])
        $result = $response['tasks'][0]['result'][0] ?? null;
        $item = $result['items'][0] ?? null;
        $metrics = $item['metrics'] ?? null;

        return [
            'organic_traffic' => $metrics['organic']['etv'] ?? 0,
            'organic_keywords' => $metrics['organic']['count'] ?? 0,
        ];
    }
}

Capability Usage¶

use App\Services\DataForSEO\DataForSEOClient;

class SeoIntelligenceCapability extends BaseCapability
{
    protected function execute(array $params): array
    {
        $client = new DataForSEOClient();

        // Get comprehensive SEO data
        $overview = $client->getLabsDomainOverview($params['domain']);
        $competitors = $client->getCompetitors($params['domain']);
        $backlinks = $client->getBacklinksSummary($params['domain']);

        return $this->formatResults($overview, $competitors, $backlinks);
    }
}

Error Handling¶

Common Errors¶

Error	Cause	Solution
`Invalid Field: 'category_codes'`	Using wrong endpoint for domain overview	Use `domain_rank_overview` instead of `domain_metrics_by_categories`
`No data available for this domain`	Domain not in DataForSEO database	Try a more popular domain or check spelling
`Rate limit exceeded`	Too many requests	Implement caching, reduce request frequency
`Authentication failed`	Invalid credentials	Check API password (not account password)

Endpoint Selection Guide¶

Use Case	Correct Endpoint	Incorrect Endpoint
Simple domain metrics (traffic, keywords)	`domain_rank_overview/live`	`domain_metrics_by_categories/live`
Metrics by industry category	`domain_metrics_by_categories/live` (requires `category_codes`)	N/A
Competitor discovery	`competitors_domain/live`	N/A

Cost Management¶

Estimated Costs per Analysis¶

A full domain analysis typically includes:

API Call	Cost
Domain Overview	$0.05
Competitors (10)	$0.05
Ranked Keywords	$0.05
Technologies	$0.01
Backlinks Summary	$0.02
LLM Aggregated Metrics	$0.10
LLM Top Domains	$0.10
LLM Search Mentions	$0.15
Total	~$0.53

Cost Optimization¶

Enable Caching: Set dataforseo_cache_hours to cache results (default: 24 hours)
Set Daily Limits: Use dataforseo_daily_limit to cap daily spending
Enable Only Needed APIs: Disable APIs you don't use
Use Middleware Caching: marketplace_seo_cache_ttl reduces repeated calls

Future Opportunities¶

Relationship Mapping¶

SEO Intelligence data can be connected to other platform features:

Relationship	Use Case	Implementation
Brand Voice	Use competitor analysis to identify differentiation opportunities in brand messaging	Store competitor keywords/positioning for brand voice context
AgentCore Capabilities	Feed SEO insights to content generation workflows	MarketplaceSEOMiddleware already provides backlink/LLM data
Co-Sell Opportunities	Identify partners with complementary keyword coverage	Cross-reference competitor data with partner database
Content Strategy	Auto-suggest topics based on keyword gaps	Compare your keywords vs competitor keywords

Data Storage Opportunities¶

Consider storing the following for user benefit:

Historical Tracking: Track domain metrics over time to show trends
Competitor Watchlist: Allow users to track competitors and get alerts on changes
AI Visibility Benchmarking: Compare AI visibility vs industry peers
Backlink Monitoring: Alert when high-value backlinks are gained/lost

API Usage Notes¶

Location Selection: One location per API request. Changing location triggers separate API calls.
Multi-location Analysis: Future feature could aggregate data across multiple locations but would multiply API costs.

Changelog¶

December 2025¶

Fixed: Domain overview now uses correct domain_rank_overview endpoint instead of domain_metrics_by_categories which required category_codes parameter
Updated: Response parsing to handle items[0].metrics structure from domain_rank_overview
Improved: Technologies parsing to skip unnamed items and handle multiple response formats
UX: Moved AI Visibility section higher in results for better visibility
UX: Added tooltips explaining ETV (Estimated Traffic Value) metric
UX: Clarified "shared keywords" terminology in competitor display

Files Reference¶

File	Purpose
`app/Services/DataForSEO/DataForSEOClient.php`	Main API client
`app/Http/Controllers/Dashboard/User/SeoIntelligenceController.php`	User-facing SEO analysis
`app/Services/DataForSEO/MarketplaceSEOMiddleware.php`	AgentCore integration
`app/Services/DataForSEO/MarketplaceSEOInsights.php`	Marketplace insights aggregation
`resources/views/default/panel/admin/settings/dataforseo.blade.php`	Admin settings UI
`resources/views/default/panel/user/seo-intelligence/index.blade.php`	User dashboard UI

Document maintained by Vell Engineering Team