SERPSpur Keyword Research Tool & REST API: Complete 24-Metric Reference Guide

Traditional keyword research platforms were built for a search landscape that no longer exists. For years, SEO teams have been forced to pay $129 to $139.95 per month for legacy subscriptions just to view basic monthly search volume estimates and opaque, black-box Keyword Difficulty (KD) scores—with unused credits expiring every 30 days[cite: 1].

Modern search engine results pages (SERPs) require deeper engineering telemetry. Between Google AI Overviews compressing organic click-through rates, Reddit and Quora threads capturing Page 1 real estate, and rapid quarter-over-quarter search shifts, knowing how many people searched for a term last year is no longer enough. To rank predictably, you need to know the exact number of Referring Domains and Dofollow backlinks required to crack the Top 10, whether user-generated forums are exposing a SERP weakness, and whether short-term 90-day momentum is accelerating or dying.

This guide serves as the complete technical reference for SERPSpur’s Keyword Research Tool Pro and the SERPSpur Keyword Research REST API (/api/v1/keywords)[cite: 1, 2]. Every metric, formula, SERP signal, and API parameter is documented below.

---

1. Core Architecture: The 2-Tier Smart Access & Pay-As-You-Go Engine

Unlike legacy SEO suites that lock keyword research behind mandatory monthly retainers, SERPSpur operates on a 2-Tier Smart Cache & Pay-As-You-Go Architecture[cite: 1, 2].

Access Tier	Monthly Subscription	Daily Allowance / Cost	Cluster Depth	Key Capabilities
Guest Mode (Unregistered)	$0.00 / mo	Free Daily Lite Searches	Seed + 5 Visible + 3 Masked	Instant seed telemetry, 12M volume chart, SERP features, and Top-10 backlink requirements.
Registered Member (Lite Mode)	$0.00 / mo	Free Daily Lite Previews	Seed + 5 Visible + 1-Click Unlock	Full 5-card executive seed dashboard, 12M seasonality curve, and instant 1-click cluster upgrade.
Deep Research Mode (Pro / Agency / PAYG)	Pay-As-You-Go (Credits Never Expire)	Dynamic Credit Unlock (Logged in Credit History)	Up to 100 Keywords / Search (Up to 250 via API)	Full unmasked semantic clusters, per-row 12M SVG sparklines, per-row Referring Domains, instant filter tabs, and CSV export.

Why This Architecture Wins for SEO Teams & Developers

• Zero Wasted Spend: Pay-as-you-go credits never expire. Every unlock is recorded transparently in your account’s Credit History.
• 30-Day Smart Vault Caching: When a keyword cluster is analyzed for a specific country and language, SERPSpur caches the normalized intelligence in a high-speed local vault for 30 days. Subsequent lookups retrieve data in under 50 milliseconds.
• Global Coverage: Supports live localized Google search telemetry across 55+ countries and 30+ languages.

---

2. Complete Reference of All 24 Keyword & SERP Telemetry Data Points

Every search executed in the SERPSpur Keyword Research Tool inspects both historical search demand and the live Top-10 organic ranking URLs on Google Page 1[cite: 1]. Below is the complete specification of all 24 data points generated per report.

Pillar A: Search Demand, Seasonality & Trajectory Metrics

1. Monthly Search Volume (search_volume): The localized average monthly Google search volume over the trailing 12 months for the selected country and language.
2. 12-Month Search Volume Trajectory Chart (monthly_searches): An interactive 12-month historical bar/line chart displaying month-by-month search demand for the primary seed keyword.
3. Per-Row 12-Month SVG Sparklines (sparkline): Lightweight, inline 12-month trend sparklines rendered inside every row of the 100-keyword cluster table so you can spot rising or dying sub-topics at a glance.
4. Year-over-Year (YoY %) Growth Trend (volume_trend): Compares the most recent month’s search volume against the same month 12 months prior to quantify macro market expansion or contraction.
5. 3-Month Quarter-over-Quarter (QoQ %) Momentum (qoq_trend): Compares the average search volume of the last 3 months against the preceding 3-month window. This catches breakout trends 6 to 9 months before annual averages reflect them.
6. Peak Seasonality Month Identification (peak_month): Automatically scans the 12-month curve to flag the exact calendar month when search demand peaks (e.g., Peaks in May or Steady), allowing content teams to publish 60–90 days ahead of seasonal surges.
7. Total Indexed SERP Results (results_count / se_results_count): The total number of web pages indexed by Google for that exact query, providing a macro view of content supply.

---

Pillar B: Link Authority & Page 1 Backlink Barrier Metrics

Standard Keyword Difficulty scores fail because they do not tell you how many backlinks you actually need to build. SERPSpur inspects the backlink profiles of the current Top 10 ranking pages on Google to output exact link-building targets:

8. Keyword Difficulty (difficulty • 0–100 Scale): Standardized difficulty score evaluating the link authority of current Page 1 organic results.
9. Average Referring Domains Needed to Rank (avg_ref_domains / ~RD): The average number of unique root domains linking to the top 10 organic URLs currently ranking on Page 1. Provided both for the seed keyword and for every individual row in the related keywords table.
10. Average Total Backlinks (avg_backlinks): The mean total backlink count pointing to current Page 1 ranking URLs.
11. Average Dofollow Backlinks (avg_dofollow): Isolates equity-passing dofollow links from nofollow noise so outreach teams know the true link-equity barrier.
12. Normalized Top-10 Average Domain Rank (avg_domain_rank • DR 0–100): Converts raw logarithmic domain authority scores into a clean 0–100 benchmark representing the average site-wide authority of Page 1 competitors.
13. Normalized Top-10 Average URL Rank (avg_url_rank • UR 0–100): Measures the page-level link strength (0–100) of the specific ranking URLs.

Operational Keyword Difficulty & Backlink Matrix

Difficulty Tier	KD Score Range	Avg. Referring Domains (~RD)	Recommended SEO Execution Strategy
Very Easy	0 – 14	0 – 4 Ref. Domains	Rankable with comprehensive on-page intent coverage and internal linking alone.
Easy (Golden Gem Zone)	15 – 29	5 – 18 Ref. Domains	Prime ROI zone. High traffic potential achievable for new and mid-sized domains.
Possible	30 – 49	19 – 50 Ref. Domains	Requires authoritative pillar content backed by targeted niche edits or digital PR.
Hard	50 – 69	51 – 140 Ref. Domains	Competitive commercial terms. Build supporting topical clusters before targeting the head term.
Very Hard	70 – 100	150+ Ref. Domains	Dominated by national brands. Filter the cluster table using Easy Wins (KD ≤ 30) or Long-Tail (4+ Words).

---

Pillar C: Commercial Valuation, PPC Bids & AI-Adjusted Traffic Value

14. Commercial Cost-Per-Click (cpc in USD): The average price advertisers pay per click in Google Ads for the target keyword.
15. Top-of-Page Bid Range (low_bid – high_bid): The 20th-to-80th percentile Google Ads bid range required to appear at the top of Page 1. A high bid ceiling confirms strong bottom-of-funnel conversion value.
16. Paid Ads Competition Index (competition • 0.00–1.00) & Level (LOW / MEDIUM / HIGH): Measures advertiser density bidding on the query.
17. AI-Adjusted Position #1 Monthly Clicks (est_clicks): Standard SEO tools assume Position #1 always captures ~28%–30% of clicks. SERPSpur checks if an AI Overview (ai_overview) is present on the SERP; if active, it automatically adjusts the estimated Position #1 click-through rate from 28% down to 22% to reflect real-world click compression.
18. Estimated Rank #1 Monthly Organic Traffic Value (est_traffic_value in $/mo): Multiplies AI-adjusted Position #1 monthly clicks by the keyword’s commercial CPC (est_clicks × cpc), quantifying the monthly Google Ads equivalent value of ranking #1 organically.

---

Pillar D: Search Intent, Topical Hierarchy & SERP Vulnerability Radar

19. Primary & Secondary Search Intent (main_intent & foreign_intent): Classifies every query into Informational, Commercial, Transactional, or Navigational intent, including secondary hybrid intents (e.g., Primary: Commercial, Secondary: Informational).
20. Overarching Parent Topic (parent_topic / core_keyword): Identifies the master umbrella keyword for the cluster, telling you whether a keyword deserves a standalone article or should be an H2 section inside a broader pillar post.
21. Proprietary SERPSpur Opportunity Score (opportunity_score • 0–100): A composite prioritization score that rewards high search volume, low Keyword Difficulty, commercial CPC value, and positive YoY momentum.
22. Active SERP Features Radar (serp_features): Detects 9+ rich SERP features occupying Page 1 real estate:
    • 🤖 AI Overview (ai_overview)
    • 📋 Featured Snippet (featured_snippet)
    • ❓ People Also Ask (people_also_ask)
    • 🔥 Forums & Discussions (discussions_and_forums)
    • ▶️ Video Pack (video)
    • 📍 Local Map Pack (local_pack)
    • 🖼️ Image Pack (images)
    • 🛍️ Shopping Carousel (shopping)
    • 🏛️ Knowledge Panel (knowledge_graph) & Top Stories (top_stories)
23. Forums on Page 1 Weakness Detector (has_forum_weakness): Automatically triggers a high-priority 🔥 Forums on Page 1 (Easy Rank Signal) badge whenever Google ranks Reddit, Quora, or forum threads on Page 1—proving Google lacks dedicated, authoritative articles for that query.
24. 1-Click Live Google SERP Inspector (serp_check_url): Opens a localized, country-and-language-specific live Google SERP view in one click to inspect competitors visually.

---

3. Real-Time Discovery Workflows: Stock Ticker, Filter Tabs & Community Cloud

Beyond single-query lookups, the tool includes four built-in discovery accelerators:

• Live Keyword Stock Exchange Ticker: Streams real-time keyword discoveries across the top of the interface, automatically categorized into 💎 Golden Gems ($\text{Vol} \ge 500, \text{KD} \le 30$), 🔥 Surging ($\text{YoY} \ge +25%$), 💰 High CPC ($\text{CPC} \ge $3.00$), and ⚡ Opportunity. Clicking any ticker item loads its report immediately.
• Instant Client-Side Cluster Filter Tabs: Filter any 100-keyword cluster in zero milliseconds without reloading the page:
  • All Keywords
  • 💎 Golden Gems ($\text{Vol} \ge 300 \text{ & KD} \le 30$)
  • 🟢 Easy Wins (KD ≤ 30)
  • ❓ Questions (who, what, where, when, why, how, can, is...)
  • 💰 Buyer Intent ($\text{Commercial/Transactional or CPC} \ge $2$)
  • 📏 Long-Tail (4+ Words)
• Weighted Community Discovery Cloud (24h Daily & 7d Weekly): A visual tag cloud of the highest-scoring keywords discovered across the platform over the last 24 hours or 7 days, dynamically sized and color-coded by their 0–100 Opportunity Score.
• 1-Click Weekly Golden Gems Email Digest & Full CSV Export: Subscribe in one click to receive the top 15 low-KD Golden Gems every week via email, or export any unlocked cluster (including Referring Domains and CPC data) to CSV.

---

4. Developer Guide: Using the SERPSpur Keyword Research REST API (/api/v1/keywords)

For agencies, SaaS builders, Google Sheets automations, and AI agent pipelines, every data point in the Keyword Research Tool is accessible programmatically via the SERPSpur Universal Developer API[cite: 2, 6, 7].

4.1 Authentication Methods

Generate your secret API key (ss_live_...) inside the Developer API Console. You can configure up to 10 independent keys with tool-specific scopes (keywords, tai, or all), optional daily credit caps, and IP/CIDR whitelists[cite: 2, 4, 6, 7].

Authenticate using any of the three supported methods[cite: 6, 7]:

1. Custom Header (Recommended): X-API-Key: ss_live_YOUR_API_KEY[cite: 6, 7]
2. Bearer Token: Authorization: Bearer ss_live_YOUR_API_KEY[cite: 2, 6, 7]
3. HTTP Basic Auth: username = your_account_email, password = ss_live_YOUR_API_KEY[cite: 2, 6, 7]

---

4.2 Crawl Depth Tiers & Endpoints Overview

The Keyword Research API supports granular DataForSEO-style Crawl Depth Tiers (depth=0 through depth=4) as well as a 30-Day Vault Mode and Free Sandbox Mode:

Endpoint	Mode / Depth Parameter	Keywords Returned	Credit Cost	Description
GET /api/v1/keywords	mode=sandbox	Mock Cluster	0 Credits (Free)	Integration testing mode. Returns realistic schema payloads and rate-limit headers for 0 credits.
GET /api/v1/keywords	mode=vault	Seed + Cached Cluster	Vault Tier Cost (0 Cr on miss)	Instant sub-50ms retrieval from the 30-day cache vault. Returns HTTP 404 with 0 credits deducted if uncached.
GET /api/v1/keywords	depth=0 (or mode=seed)	1 Seed Keyword	Depth 0 Cost	Full 24-metric intelligence for the exact seed keyword only.
GET /api/v1/keywords	depth=1 (or mode=lite)	Seed + Top 8 KWs	Depth 1 Cost	1st-level Google related searches + full seed intelligence.
GET /api/v1/keywords	depth=2 (or mode=standard)	Seed + Up to 35 KWs	Depth 2 Cost	2-level semantic cluster expansion with per-row sparklines and RD counts.
GET /api/v1/keywords	depth=3 (or mode=full)	Seed + Up to 100 KWs	Depth 3 Cost	3-level deep semantic cluster crawl returning up to 100 keywords.
GET /api/v1/keywords	depth=4 (or mode=mega)	Seed + Up to 250 KWs	Depth 4 Cost	Maximum 4-level enterprise cluster expansion for large-scale topical mapping.
POST /api/v1/keywords/batch	mode=vault or mode=live	Up to 50 KWs (vault) / 10 KWs (live)	Per-Hit Cost (0 Cr for vault misses)	Bulk multi-keyword enrichment in a single HTTP request.
GET /api/v1/keywords/golden	period=daily or weekly	Up to 50 Golden Gems	Lite Tier Cost	Returns the top community Golden Keywords discovered over the last 24h or 7d.

*(View live credit pricing for each tier anytime on our Credit Cost Schedule[cite: 1]).*

---

4.3 Code Examples (cURL, Python & Node.js)

Full SDK templates, OpenAPI 3.1 specifications, and Postman collections are available in our official SERPSpur GitHub Repository [cite: 8, 9, 10, 11].

Example 1: Single 100-Keyword Cluster Lookup (cURL)

curl -X GET "[https://serpspur.com/api/v1/keywords?keyword=seo+audit+tool&country=us&language=en&depth=3](https://serpspur.com/api/v1/keywords?keyword=seo+audit+tool&country=us&language=en&depth=3)" \
  -H "X-API-Key: ss_live_YOUR_API_KEY" \
  -H "Accept: application/json"

Example 2: Bulk 50-Keyword Batch Lookup in Python (POST /api/v1/keywords/batch)

Python

import requests

API_KEY = "ss_live_YOUR_API_KEY"
BASE_URL = "[https://serpspur.com/api/v1/keywords/batch](https://serpspur.com/api/v1/keywords/batch)"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

payload = {
    "keywords": [
        "seo audit tool",
        "broken link checker",
        "ai search rank tracker"
    ],
    "country": "us",
    "language": "en",
    "mode": "vault"  # 'vault' (up to 50 KWs, 0 Cr on miss) | 'live' (up to 10 KWs) | 'sandbox'
}

response = requests.post(BASE_URL, headers=headers, json=payload, timeout=30)
print("Credits Deducted:", response.headers.get("X-SerpSpur-Credits-Deducted"))
print("Rate Limit Remaining:", response.headers.get("X-RateLimit-Remaining"))
print(response.json())

Example 3: Node.js Integration

JavaScript

const API_KEY = process.env.SERPSPUR_API_KEY || 'ss_live_YOUR_API_KEY';

async function analyzeKeywordCluster(keyword) {
  const params = new URLSearchParams({
    keyword: keyword,
    country: 'us',
    language: 'en',
    depth: '3' // 100-Keyword Cluster
  });

  const res = await fetch(`[https://serpspur.com/api/v1/keywords?$](https://serpspur.com/api/v1/keywords?$){params}`, {
    headers: {
      'X-API-Key': API_KEY,
      'Accept': 'application/json'
    }
  });

  const payload = await res.json();
  console.log('Opportunity Score:', payload.data.opportunity_score);
  console.log('Ref. Domains Needed for Top 10:', payload.data.backlinks_to_rank.avg_ref_domains);
  console.log('Forum Weakness on Page 1:', payload.data.has_forum_weakness);
  console.log('Related Keywords Returned:', payload.data.related_keywords.length);
}

analyzeKeywordCluster('seo audit tool');

4.4 Sample JSON Response Schema (GET /api/v1/keywords)

JSON

{
  "success": true,
  "code": "OK",
  "message": "Keyword intelligence retrieved successfully.",
  "timestamp": "2026-10-25T12:00:00+00:00",
  "data": {
    "keyword": "seo audit tool",
    "country": "us",
    "language": "en",
    "mode": "depth3",
    "depth": 3,
    "cached": false,
    "search_volume": 5400,
    "volume_trend_yoy": 38,
    "qoq_momentum_3m": 14,
    "peak_month": "May 2026",
    "difficulty": 24,
    "opportunity_score": 86,
    "parent_topic": "technical seo audit",
    "words_count": 3,
    "main_intent": "commercial",
    "foreign_intent": ["informational"],
    "cpc": 8.40,
    "low_bid": 3.10,
    "high_bid": 14.80,
    "competition": 0.42,
    "competition_level": "MEDIUM",
    "est_rank1_clicks": 1188,
    "est_traffic_value": 9979,
    "results_count": 48200000,
    "backlinks_to_rank": {
      "avg_ref_domains": 18,
      "avg_backlinks": 142,
      "avg_dofollow": 118,
      "avg_domain_rank": 46,
      "avg_url_rank": 31
    },
    "serp_features": [
      "ai_overview",
      "people_also_ask",
      "discussions_and_forums"
    ],
    "has_forum_weakness": true,
    "related_count": 100,
    "related_keywords": [
      {
        "keyword": "free technical seo audit tool",
        "volume": 2900,
        "trend": 45,
        "difficulty": 19,
        "cpc": 4.20,
        "intent": "transactional",
        "ref_domains": 11,
        "dofollow_links": 38,
        "is_golden": true,
        "sparkline": [1900, 2100, 2100, 2400, 2400, 2600, 2600, 2900, 2900, 3100, 2900, 2900]
      }
    ],
    "credits_deducted": 10,
    "credits_remaining": 164852
  }
}

5. Frequently Asked Questions (FAQ)

How does SERPSpur calculate “Backlinks Needed to Rank”?

SERPSpur inspects the live Top 10 organic results ranking on Google Page 1 for your target keyword and computes the mean number of unique Referring Domains (~RD), Total Backlinks, and Dofollow Backlinks pointing to those ranking URLs. This provides a concrete link-acquisition budget before you write a single word.

What happens if a keyword is not found in the 30-day API Vault (mode=vault)?

When calling GET /api/v1/keywords?mode=vault or POST /api/v1/keywords/batch with "mode": "vault", any keyword that has not been scanned within the last 30 days returns a miss status and deducts 0 credits from your wallet[cite: 2, 4]. You only pay for verified cache hits, or you can pass depth=1..4 (or "mode": "live") to trigger a fresh live crawl.

How does the AI Overview CTR adjustment work?

When Google displays a generative AI Overview (ai_overview) above organic results, traditional organic Position #1 click-through rates drop significantly. SERPSpur automatically detects active AI Overviews and adjusts estimated Position #1 click volume from 28% down to 22%, ensuring your organic Traffic Value ($/mo) projections remain accurate.

Do SERPSpur pay-as-you-go credits expire?

No. Purchased pay-as-you-go credits never expire and are shared across the entire SERPSpur ecosystem—including the Keyword Research Tool, Developer REST API, Website Audit Pro, Daily Rank Tracker, Backlink Gap Analysis, and the TAI™ Bot Traffic Detector.