Keyword Research

Better Keywords AI

Discover high-intent keywords with volume, CPC, competition, search-intent scoring, fan-out expansion, and metrics provenance — or filter an existing keyword set.

POSThttps://ai.seovendor.co/api/better-keywords/

Authenticate every request by passing your secret key as k in the JSON body. Requests are POST with Content-Type: application/json.

Enhanced research output. The research action now returns additional fields: fanout_parent_keyword, fanout_seed, fanout_status (query fan-out expansion); keyword_source, research_origin (provenance); metrics_source, metrics_status, result_complete (data quality); language_name, location_code, location_name, retrieved_at (metadata); score_formula (scoring). The filter action output also includes DTR and Keyword fields.

01Request parameters

Field	Type	Required	Description
action	string	optional	research Research keywords.filter Filter keyword data.
kw	string	required	Keyword text, 4 to 300 characters.
brand	string	optional	Brand text, max 60 characters.
web	string	optional	Website URL, max 300 characters.
url	string	optional	Fallback website URL used when web is not sent, max 300 characters.
location	string	optional	Location text, max 50 characters.
brandpersona	string	optional	Brand persona text, max 2000 characters.
lang	integer	optional	0 US English1 UK English2 Australian English3 Spanish4 Italian5 French6 German7 Portuguese8 Dutch9 Bulgarian10 Czech11 Danish12 Estonian13 Finnish ► +26 more options 14 Greek15 Hungarian16 Polish17 Norwegian18 Romanian19 Swedish20 Brazilian Portuguese21 Mexican Spanish22 Colombian Spanish23 Argentine Spanish24 Peruvian Spanish25 Canadian English26 Chilean Spanish27 Bolivian Spanish28 Catalan29 Austrian German30 Canadian French31 Belgian Dutch (Flemish)32 Belgian French33 Scottish English34 Slovak35 New Zealand English36 Irish English37 Swiss German38 Croatian39 Turkish
researchtype	array	optional	0 Product Interest1 Nearby Services2 National Services3 Online Shopping4 Brand Visibility5 Content Development6 Market Expansion7 Customer Engagement8 Competitive Analysis9 Seasonal Campaigns10 Event Promotion11 Lead Generation12 Audience Targeting13 Reputation Management ► +52 more options 14 Mobile Optimization15 Voice Search Trends16 Conversion Rate Improvement17 Local SEO Focus18 Global Outreach19 User Experience Enhancement20 Customer Retention21 New Product Launch22 Cost-Per-Click Optimization23 Long-Tail Keyword Targeting24 Social Media Integration25 Brand Differentiation26 Awareness Campaigns27 Behavioral Insights28 Traffic Generation29 SERP Feature Optimization30 Organic Traffic Growth31 Content Repurposing32 Engagement Metrics Improvement33 Personalization Strategy34 Cross-Channel Marketing35 Community Building36 Referral Traffic Boost37 Demographic Targeting38 Budget Optimization39 Holistic SEO Approach40 SERP Domination41 Algorithm Update Adaptation42 Sustainable Traffic Growth43 Data-Driven Strategy44 Crisis Management SEO45 Geo-Targeting46 E-commerce Enhancement47 Brand Partnership48 B2B Marketing49 Accessibility Optimization50 Compliance and Security51 Sponsored Content Strategy52 Interactive Content53 Landing Page Optimization54 Keyword Cannibalization Prevention55 Authority Building56 Image Search Optimization57 Predictive Search Trends58 Meta Data Optimization59 Click-Through Rate Optimization60 Customer Journey Mapping61 In-Depth Topic Coverage62 Google Profile Optimization63 Social Listening64 Multichannel Attribution65 Privacy-Focused Marketing
kwcompetition	array	optional	0 Opportunity Keywords1 All Keywords2 High-ROI Keywords3 Niche-Specific Keywords4 Broad Match Keywords5 Long Tail Keywords6 Low Competition Keywords7 High Competition Keywords8 Emerging Trend Keywords9 Seasonal Peak Keywords10 Authority Builder Keywords11 Brand-Specific Keywords12 Zero Competition Keywords13 Buyer Intent Keywords ► +18 more options 14 High Volume Keywords15 Low Volume Keywords16 Geo-Specific Keywords17 User Intent Keywords18 High Difficulty Keywords19 Low Difficulty Keywords20 Mid-Range Competition Keywords21 Question-Based Keywords22 Content Gap Keywords23 Underutilized Keywords24 Conversion-Focused Keywords25 Strategic Growth Keywords26 Untapped Keywords27 High Cost-Per-Click Keywords28 Low Cost-Per-Click Keywords29 Quick Win Keywords30 High Impact Keywords31 Semantic Keywords
data	array	optional	JSON array of keyword objects to AI-filter for relevance. Required for filter action only. Each object must include keyword (string). Optional fields: competition (0-100 integer), volume (integer), score (integer), category (string), intent (string), cpc (string). Max 1000 items. Tip: pass the data array returned by the research action directly.
k	string	required	API key sent as k in query string, POST body, JSON body; api_key is also accepted, 11 to 120 characters.

02Response

Every response uses the standard envelope (success, application, action, data, meta, error). The data field for this endpoint is documented below.

successaction: research · HTTP 200

200 response example

{
  "success": true,
  "application": "better-keywords",
  "action": "research",
  "data": [
    {
      "keyword": "white label seo",
      "category": "Agency Services",
      "cpc": 4.25,
      "competition": 6,
      "volume": 2400,
      "rank": 3,
      "intent": "commercial",
      "score": 0.92,
      "relativeurl": "/services/white-label-seo",
      "keyword_source": "string",
      "metrics_source": "string",
      "metrics_status": "string",
      "competition_type": "string",
      "location_code": 0,
      "location_name": "string",
      "language_name": "string",
      "retrieved_at": "string",
      "score_formula": "string",
      "research_origin": "string",
      "fanout_parent_keyword": "string",
      "fanout_seed": 0,
      "fanout_status": "string",
      "result_complete": true
    }
  ],
  "meta": {
    "request_id": "req_3f9a7c2e8b41",
    "duration_ms": 1284,
    "upstream_http_code": 200
  },
  "error": null
}

Response schema

successboolean= true

applicationstring= "better-keywords"

actionstring= "research"

dataarrayKeyword research results.

└─keywordstringDiscovered or supplied keyword.

└─categorystringKeyword topic category.

└─cpcnumberEstimated cost-per-click.

└─competitionintegerPaid search competition, 0 to 100.

└─volumeintegerMonthly search volume estimate.

└─rankintegerCurrent organic ranking position for this keyword on the submitted website, 0 if not currently ranked.

└─intentstringSearch intent classification, e.g. informational, commercial.

└─scorenumberOpportunity score. See score_formula for how it is calculated.

└─relativeurlstringRanking URL on the submitted website for this keyword, if currently ranked.

└─keyword_sourcestringHow this keyword was produced. One of: llm (AI-generated idea), user_csv (from an uploaded/explicit keyword list), google_ranked_keywords (an existing ranking pulled from Google data), llm_and_google_ranked_keywords (an AI-generated idea that also matched an existing ranking).

└─metrics_sourcestringProvenance of cpc/competition/volume. One of: google_data, unavailable.

└─metrics_statusstringWhether cpc/competition/volume were actually found. One of: verified, unavailable.

└─competition_typestringWhat the competition value measures. One of: paid_search_competition_index, paid_search_competition.

└─location_codeintegerResolved location code used for metrics lookup.

└─location_namestringResolved location name used for metrics lookup, e.g. "United States".

└─language_namestringResolved language used for metrics lookup, e.g. "English".

└─retrieved_atstringUTC timestamp this row's metrics were retrieved, format YYYY-MM-DD HH:MM:SS.

└─score_formulastringIdentifier for the formula used to calculate score. Currently always volume_x_inverse_paid_competition_v1: volume * ((100 - competition) / 100).

└─research_originstringWhere this row came from in the research flow. One of: primary (from the original request), fan_out (an additional keyword discovered by expanding a high-opportunity primary result).

└─fanout_parent_keywordstringThe primary keyword this row was expanded from. Only set when research_origin is fan_out.

└─fanout_seedinteger1 if this primary keyword was itself used as a seed for fan-out expansion, 0 otherwise.

└─fanout_statusstringOutcome of fan-out expansion for a fanout_seed row. One of: (empty, not a fan-out seed), complete, failed.

└─result_completebooleanOnly present on rows merged with the website's existing Google rankings. True if every ranked keyword for the site was retrieved, false if the ranking data was truncated.

metaobject

└─request_idstring

└─duration_msinteger

└─upstream_http_codeinteger

errornull

successaction: filter · HTTP 200

200 response example

{
  "success": true,
  "application": "better-keywords",
  "action": "filter",
  "data": [
    {
      "Keyword": "white label seo",
      "DTR": 0
    }
  ],
  "meta": {
    "request_id": "req_3f9a7c2e8b41",
    "duration_ms": 1284,
    "upstream_http_code": 200
  },
  "error": null
}

Response schema

successboolean= true

applicationstring= "better-keywords"

actionstring= "filter"

dataarraySubset of the submitted data rows that scored DTR >= 80, in the same shape they were submitted in (see data's input description), each with DTR added. Not the same shape as research results.

└─KeywordstringThe keyword, carried over from the submitted row. A row without this field is dropped entirely, not just excluded from scoring.

└─DTRintegerAI-scored Direct Topical Relevance to kw, 0 to 100. Only rows scoring 80 or above are returned.

metaobject

└─request_idstring

└─duration_msinteger

└─upstream_http_codeinteger

errornull

errorHTTP 400, 401, 502, 503, or 504

error response example

{
  "success": false,
  "application": "better-keywords",
  "action": "string",
  "data": null,
  "meta": {
    "request_id": "req_3f9a7c2e8b41"
  },
  "error": {
    "code": "invalid_request",
    "message": "The kw field is required.",
    "field": "kw",
    "details": [],
    "apidefinitions": "https://ai.seovendor.co/api/better-keywords/definitions"
  }
}

Response schema

successboolean= false

applicationstring= "better-keywords"

actionstring

datanull

metaobject

└─request_idstring

errorobject

└─codestringError code returned by the API.

└─messagestringHuman-readable error message.

└─fieldstringInput field associated with the error.

└─detailsarrayAdditional error details.

└─apidefinitionsstringPublic API definitions URL.

POST /api/better-keywords/

curl -X POST "https://ai.seovendor.co/api/better-keywords/" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "k": "[API KEY]",
  "action": "research",
  "kw": "white label seo",
  "web": "https://seovendor.co",
  "brand": "SEO Vendor"
}'
<?php
$ch = curl_init("https://ai.seovendor.co/api/better-keywords/");

$payload = [
    "k" => "[API KEY]",
    "action" => "research",
    "kw" => "white label seo",
    "web" => "https://seovendor.co",
    "brand" => "SEO Vendor",
];

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Accept: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
const response = await fetch("https://ai.seovendor.co/api/better-keywords/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    k: "[API KEY]",
    action: "research",
    kw: "white label seo",
    web: "https://seovendor.co",
    brand: "SEO Vendor",
  })
});

const data = await response.json();
console.log(data);
import requests

url = "https://ai.seovendor.co/api/better-keywords/"

payload = {
    "k": "[API KEY]",
    "action": "research",
    "kw": "white label seo",
    "web": "https://seovendor.co",
    "brand": "SEO Vendor",
}

headers = {
    "Content-Type": "application/json",
    "Accept": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)

← PreviousSEO Image AI Next →Insight Igniter

SV API

Overview SV CLI SV MCP API Home GitHub seovendor.co