---
updatedAt: 2025-08-09T21:12:58.000Z
agentTools:
projectIndex: https://developer.spyfu.com/llms.txt
---
# Get SEO Keywords
Unified endpoint for SEO keyword analyses. Select an analysis via `searchType` to return gains/losses in clicks, rank movers, page-one entries/exits, newly ranked terms, or top-value keywords -- without switching endpoints.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "SEO Research API",
"version": "v2",
"description": "Access the world's most comprehensive organic search intelligence database to identify keyword opportunities, track ranking changes, and analyze competitor SEO strategies. Powered by SpyFu's industry-leading data collection spanning 18 years of continuous monitoring across global search markets.\n\nSpyFu's SEO Research API is built on an unprecedented foundation of **1.6 trillion search results** collected across all time periods and countries, with **8 billion keywords** featuring comprehensive search volume and performance metrics. Our database actively tracks **1.6 billion keywords** in live SERPs globally, providing **2x more organic keywords per domain** than SEMRush or Ahrefs. **Every data point updates every 15 seconds**, ensuring you have real-time competitive intelligence across all 28 supported countries.\n\nCompared to competitors who offer limited historical snapshots, SpyFu provides **18 years of complete SEO timeline data** with live updates every 15 seconds. While SEMRush and Ahrefs provide basic keyword tracking, SpyFu delivers 2x more organic keyword coverage per domain with unmatched historical depth and real-time accuracy.\n\nWith this API, you can identify high-value keyword opportunities through ranking change analysis, track competitor SEO performance across time, discover newly ranked keywords before competitors notice, analyze SERP features and click potential, monitor keyword ranking volatility and trends, and uncover content gaps where competitors are gaining or losing ground. Access historical ranking data to understand long-term SEO strategy evolution and benchmark your performance against any competitor in your market.\n\nThe SEO Research API integrates seamlessly with SpyFu's Ad History, Competitors, and Domain Stats APIs to provide complete competitive intelligence across both organic and paid search channels.\n\nGet started with comprehensive API documentation and interactive examples at [SpyFu Developer Portal](https://developer.spyfu.com)."
},
"servers": [
{
"url": "https://api.spyfu.com/apis/serp_api"
}
],
"paths": {
"/v2/seo/getSeoKeywords": {
"get": {
"operationId": "OrganicSerpApi_GetSeoKeywords_GET",
"summary": "Get SEO Keywords",
"description": "Unified endpoint for SEO keyword analyses. Select an analysis via `searchType` to return gains/losses in clicks, rank movers, page-one entries/exits, newly ranked terms, or top-value keywords -- without switching endpoints.",
"parameters": [
{
"name": "query",
"in": "query",
"description": "Domain, URL, subdomain, or path to analyze. Accepts full domains (example.com), complete URLs (https://example.com/blog), subdomains (blog.example.com), specific paths (example.com/products/), or individual pages.",
"required": true,
"schema": {
"type": "string",
"examples": [
"example.com"
]
},
"example": "example.com"
},
{
"name": "searchType",
"in": "query",
"description": "Type of SEO keyword analysis to perform. Each type provides different insights into keyword performance and ranking changes.",
"required": true,
"schema": {
"type": "string",
"examples": [
"MostValuable"
],
"default": "MostValuable",
"enum": [
"GainedClicks",
"GainedRanks",
"JustFellOff",
"JustMadeIt",
"LostClicks",
"LostRanks",
"MostValuable",
"NewlyRanked"
],
"x-enumDescriptions": {
"GainedClicks": "MoM increase in estimated organic clicks.",
"GainedRanks": "Largest positive MoM rank change (moved up).",
"JustFellOff": "Now <10; was 1-10 last month (fell off page one).",
"JustMadeIt": "Now 1-10; was <10 last month (made page one).",
"LostClicks": "MoM decrease in estimated organic clicks.",
"LostRanks": "Largest negative MoM rank change (moved down).",
"MostValuable": "Highest current estimated organic clicks for the domain/URL.",
"NewlyRanked": "Unranked last month; now 1-100."
}
},
"example": "MostValuable"
},
{
"name": "compareDomain",
"in": "query",
"description": "Domain to compare against when evaluating where it outranks you and where you outrank it.",
"schema": {
"type": "string",
"examples": [
"competitor.com"
]
},
"example": "competitor.com"
},
{
"name": "includeTerms",
"in": "query",
"description": "Comma-separated list of terms that must be present in the keyword.",
"schema": {
"type": "string",
"examples": [
"hosting,domain,website"
]
}
},
{
"name": "includeAnyTerm",
"in": "query",
"description": "Used with includeTerms. If true: match any term (OR). If false: require all terms (AND).",
"schema": {
"type": "boolean",
"examples": [
false
],
"default": false
}
},
{
"name": "excludeTerms",
"in": "query",
"description": "Comma-separated list of terms to exclude from results (e.g., branded or irrelevant terms).",
"schema": {
"type": "string",
"examples": [
"free,cheap,discount"
]
}
},
{
"name": "excludeHomepageKeywords",
"in": "query",
"description": "If true, exclude keywords where the domain/URL's homepage (root domain, e.g., example.com) ranks; if false, include all.",
"schema": {
"type": "boolean",
"examples": [
false
],
"default": false
},
"example": false
},
{
"name": "searchVolume.min",
"in": "query",
"description": "Filter to keywords where monthly search volume (Google) is ≥ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
1000
]
},
"example": 1000
},
{
"name": "searchVolume.max",
"in": "query",
"description": "Filter to keywords where monthly search volume (Google) is ≤ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
50000
]
},
"example": 50000
},
{
"name": "keywordDifficulty.min",
"in": "query",
"description": "Filter to keywords where the keyword difficulty score is ≥ this value (0-100; higher = harder to rank).",
"schema": {
"type": "number",
"format": "float",
"examples": [
30
]
},
"example": 30
},
{
"name": "keywordDifficulty.max",
"in": "query",
"description": "Filter to keywords where the keyword difficulty score is ≤ this value (0-100; higher = harder to rank).",
"schema": {
"type": "number",
"format": "float",
"examples": [
70
]
},
"example": 70
},
{
"name": "rank.min",
"in": "query",
"description": "Filter to keywords where the domain/URL rank position is ≥ this value (1 = best/top organic result).",
"schema": {
"type": "number",
"format": "float",
"examples": [
1
]
},
"example": 1
},
{
"name": "rank.max",
"in": "query",
"description": "Filter to keywords where the domain/URL rank position is ≤ this value (1 = best/top organic result).",
"schema": {
"type": "number",
"format": "float",
"examples": [
10
]
},
"example": 10
},
{
"name": "rankChange.min",
"in": "query",
"description": "Filter to keywords where the domain/URL improved by at least this many positions vs. the previous month (rank_change ≥ value). Positive values mean moved up; negative values mean moved down.",
"schema": {
"type": "number",
"format": "float",
"examples": [
5
]
},
"example": 5
},
{
"name": "rankChange.max",
"in": "query",
"description": "Filter to keywords where the month-over-month rank change is at most this many positions (rank_change ≤ value). Positive values mean moved up; negative values mean moved down.",
"schema": {
"type": "number",
"format": "float",
"examples": [
20
]
},
"example": 20
},
{
"name": "costPerClick.min",
"in": "query",
"description": "Filter to keywords where the average cost per click (CPC) is ≥ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
1
]
},
"example": 1
},
{
"name": "costPerClick.max",
"in": "query",
"description": "Filter to keywords where the average cost per click (CPC) is ≤ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
10
]
},
"example": 10
},
{
"name": "costPerClickOption",
"in": "query",
"description": "Match type for CPC filtering. Broad = includes variations/related terms; Exact = exact keyword only; Phrase = contains the keyword phrase in order (with additional words allowed).",
"schema": {
"type": "string",
"examples": [
"Broad"
],
"enum": [
"Broad",
"Exact",
"Phrase"
],
"x-enumDescriptions": {
"Broad": "Includes keyword variations and related terms",
"Exact": "Requires precise keyword match only",
"Phrase": "Includes the keyword phrase in order with additional words"
}
},
"example": "Broad"
},
{
"name": "seoClicks.min",
"in": "query",
"description": "Filter to keywords where estimated monthly organic clicks (SEO clicks) are ≥ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
100
]
},
"example": 100
},
{
"name": "seoClicks.max",
"in": "query",
"description": "Filter to keywords where estimated monthly organic clicks (SEO clicks) are ≤ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
1000
]
},
"example": 1000
},
{
"name": "seoClicksChange.min",
"in": "query",
"description": "Filter to keywords where the month-over-month change in estimated organic clicks is ≥ this value. Positive values indicate click gains; negative values indicate click losses.",
"schema": {
"type": "number",
"format": "float",
"examples": [
10
]
},
"example": 10
},
{
"name": "seoClicksChange.max",
"in": "query",
"description": "Filter to keywords where the month-over-month change in estimated organic clicks is ≤ this value. Positive values indicate click gains; negative values indicate click losses.",
"schema": {
"type": "number",
"format": "float",
"examples": [
500
]
},
"example": 500
},
{
"name": "percentMobileSearches.min",
"in": "query",
"description": "Filter to keywords where the mobile search share (%) is ≥ this value (range 0-100).",
"schema": {
"type": "number",
"format": "float",
"examples": [
50
]
},
"example": 50
},
{
"name": "percentMobileSearches.max",
"in": "query",
"description": "Filter to keywords where the mobile search share (%) is ≤ this value (range 0-100).",
"schema": {
"type": "number",
"format": "float",
"examples": [
80
]
},
"example": 80
},
{
"name": "percentDesktopSearches.min",
"in": "query",
"description": "Filter to keywords where the desktop search share (%) is ≥ this value (range 0-100).",
"schema": {
"type": "number",
"format": "float",
"examples": [
20
]
},
"example": 20
},
{
"name": "percentDesktopSearches.max",
"in": "query",
"description": "Filter to keywords where the desktop search share (%) is ≤ this value (range 0-100).",
"schema": {
"type": "number",
"format": "float",
"examples": [
50
]
},
"example": 50
},
{
"name": "percentNotClicked.min",
"in": "query",
"description": "Filter to keywords where the percentage of searches with no click is ≥ this value (range 0-100).",
"schema": {
"type": "number",
"format": "float",
"examples": [
10
]
},
"example": 10
},
{
"name": "percentNotClicked.max",
"in": "query",
"description": "Filter to keywords where the percentage of searches with no click is ≤ this value (range 0-100).",
"schema": {
"type": "number",
"format": "float",
"examples": [
30
]
},
"example": 30
},
{
"name": "percentPaidClicks.min",
"in": "query",
"description": "Filter to keywords where the share of SERP clicks going to paid ads (%) is ≥ this value (range 0-100).",
"schema": {
"type": "number",
"format": "float",
"examples": [
20
]
},
"example": 20
},
{
"name": "percentPaidClicks.max",
"in": "query",
"description": "Filter to keywords where the share of SERP clicks going to paid ads (%) is ≤ this value (range 0-100).",
"schema": {
"type": "number",
"format": "float",
"examples": [
60
]
},
"example": 60
},
{
"name": "percentOrganicClicks.min",
"in": "query",
"description": "Filter to keywords where the share of SERP clicks going to organic results (%) is ≥ this value (range 0-100).",
"schema": {
"type": "number",
"format": "float",
"examples": [
40
]
},
"example": 40
},
{
"name": "percentOrganicClicks.max",
"in": "query",
"description": "Filter to keywords where the share of SERP clicks going to organic results (%) is ≤ this value (range 0-100).",
"schema": {
"type": "number",
"format": "float",
"examples": [
80
]
},
"example": 80
},
{
"name": "monthlyCost.min",
"in": "query",
"description": "Filter to keywords where the estimated monthly advertising cost is ≥ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
100
]
},
"example": 100
},
{
"name": "monthlyCost.max",
"in": "query",
"description": "Filter to keywords where the estimated monthly advertising cost is ≤ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
5000
]
},
"example": 5000
},
{
"name": "monthlyCostOption",
"in": "query",
"description": "Match type for monthly cost filtering. Broad = includes variations/related terms; Exact = exact keyword only; Phrase = contains the keyword phrase in order (with additional words allowed).",
"schema": {
"type": "string",
"examples": [
"Broad"
],
"enum": [
"Broad",
"Exact",
"Phrase"
],
"x-enumDescriptions": {
"Broad": "Includes keyword variations and related terms",
"Exact": "Requires precise keyword match only",
"Phrase": "Includes the keyword phrase in order with additional words"
}
},
"example": "Broad"
},
{
"name": "paidCompetitors.min",
"in": "query",
"description": "Filter to keywords where the number of distinct advertisers observed over the last 6 months is ≥ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
5
]
},
"example": 5
},
{
"name": "paidCompetitors.max",
"in": "query",
"description": "Filter to keywords where the number of distinct advertisers observed over the last 6 months is ≤ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
50
]
},
"example": 50
},
{
"name": "rankingHomepages.min",
"in": "query",
"description": "Filter to keywords where the number of homepage/root-domain URLs in the top 100 results is ≥ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
2
]
},
"example": 2
},
{
"name": "rankingHomepages.max",
"in": "query",
"description": "Filter to keywords where the number of homepage/root-domain URLs in the top 100 results is ≤ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
10
]
},
"example": 10
},
{
"name": "totalMonthlyClicks.min",
"in": "query",
"description": "Filter to keywords where total monthly SERP clicks (all domains) are ≥ this value. Independent of rank; includes both organic and paid clicks.",
"schema": {
"type": "number",
"format": "float",
"examples": [
1000
]
},
"example": 1000
},
{
"name": "totalMonthlyClicks.max",
"in": "query",
"description": "Filter to keywords where total monthly SERP clicks (all domains) are ≤ this value. Includes both organic and paid clicks.",
"schema": {
"type": "number",
"format": "float",
"examples": [
10000
]
},
"example": 10000
},
{
"name": "adCount.min",
"in": "query",
"description": "Filter to keywords where the number of distinct advertisers observed over the last 6 months is ≥ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
3
]
},
"example": 3
},
{
"name": "adCount.max",
"in": "query",
"description": "Filter to keywords where the number of distinct advertisers observed over the last 6 months is ≤ this value.",
"schema": {
"type": "number",
"format": "float",
"examples": [
25
]
},
"example": 25
},
{
"name": "pageSize",
"in": "query",
"description": "The maximum number of rows returned.",
"schema": {
"type": "integer",
"format": "int32",
"examples": [
5
],
"default": 5,
"maximum": 10000,
"minimum": 1
},
"example": 5
},
{
"name": "countryCode",
"in": "query",
"description": "Country market to search. Specifically, this maps to the Google domain version to query against (e.g., google.com for US, google.de for Germany, etc.). All Countries",
"schema": {
"type": "string",
"examples": [
"US"
],
"default": "US",
"enum": [
"AR",
"AT",
"AU",
"BE",
"BR",
"CA",
"CH",
"DE",
"DK",
"ES",
"FR",
"IE",
"IN",
"IT",
"JP",
"MX",
"NL",
"NO",
"NZ",
"PL",
"PT",
"SE",
"SG",
"TR",
"UA",
"UK",
"US",
"ZA"
]
},
"example": "US"
},
{
"name": "sortBy",
"in": "query",
"description": "Column to sort by.",
"schema": {
"type": "string",
"examples": [
"SearchVolume"
],
"default": "SearchVolume",
"enum": [
"SearchVolume",
"KeywordDifficulty",
"Rank",
"RankChange",
"SeoClicks",
"SeoClicksChange",
"PercentMobileSearches",
"PercentDesktopSearches",
"PercentNotClicked",
"PercentPaidClicks",
"PercentOrganicClicks",
"BroadCostPerClick",
"ExactCostPerClick",
"PhraseCostPerClick",
"BroadMonthlyCost",
"ExactMonthlyCost",
"PhraseMonthlyCost",
"TotalMonthlyClicks",
"PaidCompetitors",
"RankingHomepages"
],
"x-enumDescriptions": {
"SearchVolume": "Number of searches done this past month on Google (or within selected country). Blended from multiple sources for better snapshot of search activity",
"KeywordDifficulty": "SEO ranking difficulty score (0-100 scale, higher = more difficult to rank). Based on domain strength, on-page signals like 'keyword in title,' and number of .gov/.edu domains",
"Rank": "Organic search result position (1 = top organic result)",
"RankChange": "Change in organic position from previous data update (positive values indicate ranking improvement; negative values indicate moving further down the SERP).",
"SeoClicks": "Estimated number of organic clicks the domain gets from ranking on this keyword",
"SeoClicksChange": "Change in estimated organic clicks from previous data update",
"PercentMobileSearches": "Percentage breakdown of searches from mobile vs desktop devices",
"PercentDesktopSearches": "Percentage breakdown of searches from desktop vs mobile devices",
"PercentNotClicked": "Rate that searchers leave the SERP without clicking any result",
"PercentPaidClicks": "Percentage of SERP clicks that went to paid ads",
"PercentOrganicClicks": "Percentage of SERP clicks that went to organic results",
"BroadCostPerClick": "Average amount advertisers pay per click for broad match ads on this keyword",
"ExactCostPerClick": "Average amount advertisers pay per click for exact match ads on this keyword",
"PhraseCostPerClick": "Average amount advertisers pay per click for phrase match ads on this keyword",
"BroadMonthlyCost": "Estimated monthly advertising spend for broad match bidding",
"ExactMonthlyCost": "Estimated monthly advertising spend for exact match bidding",
"PhraseMonthlyCost": "Estimated monthly advertising spend for phrase match bidding",
"TotalMonthlyClicks": "Total estimated clicks made on this SERP to any paid or organic results",
"PaidCompetitors": "Total number of advertisers seen over the last 6 months for this keyword",
"RankingHomepages": "Number of homepage URLs (vs deeper paths) ranking within first 100 results"
}
},
"example": "SearchVolume"
},
{
"name": "sortOrder",
"in": "query",
"description": "Order to sort the results.",
"schema": {
"type": "string",
"examples": [
"Descending"
],
"default": "Descending",
"enum": [
"Ascending",
"Descending"
]
},
"example": "Descending"
},
{
"name": "startingRow",
"in": "query",
"description": "Row number to start the results with.",
"schema": {
"type": "integer",
"format": "int32",
"examples": [
1
],
"default": 1,
"maximum": 10000,
"minimum": 1
},
"example": 1
},
{
"name": "adultFilter",
"in": "query",
"description": "Exclude adult keywords considered unsafe for work.",
"schema": {
"type": "boolean",
"examples": [
true
],
"default": true
},
"example": true
},
{
"name": "onlyAdultKeywords",
"in": "query",
"description": "Only include adult keywords considered unsafe for work.",
"schema": {
"type": "boolean",
"examples": [
false
],
"default": false
},
"example": false
},
{
"name": "exactMatch",
"in": "query",
"description": "Indicates whether to apply exact match filtering for the query.\r\nThis parameter will result in **only** exact matches,\r\nmeaning protocols (http/https) and trailing slashes **must** be included.\r\nFor example, a query of \"https://example.com/blog\" will not match\r\n- \"example.com/blog\"\r\n- \"https://example.com/blog/\"",
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "Response wrapper containing organic SERP keyword results with comprehensive SEO metrics and pagination metadata.",
"type": "object",
"properties": {
"resultCount": {
"description": "Number of results returned",
"type": "integer",
"format": "int32",
"examples": [
100
],
"readOnly": true
},
"results": {
"description": "Array of organic search keywords with comprehensive SEO metrics including rankings, click estimates, and SERP analysis data.",
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"keyword": {
"description": "The keyword for which this domain ranks organically in the top 100 search results.",
"type": [
"string",
"null"
],
"examples": [
"running shoes"
],
"readOnly": true
},
"topRankedUrl": {
"description": "The highest ranking URL from this domain for this specific keyword.",
"type": [
"string",
"null"
],
"examples": [
"https://example.com/best-running-shoes"
],
"readOnly": true
},
"rank": {
"description": "Current organic search position for this keyword (1 = top position).",
"type": "integer",
"format": "int32",
"examples": [
7
],
"readOnly": true
},
"rankChange": {
"description": "Change in ranking position since the previous measurement period (positive values indicate ranking improvement; negative values indicate moving further down the SERP).",
"type": [
"integer",
"null"
],
"format": "int32",
"examples": [
-3
],
"readOnly": true
},
"searchVolume": {
"description": "Monthly search volume for this keyword based on Google search data across the selected country/region.",
"type": [
"integer",
"null"
],
"format": "int64",
"examples": [
700000
],
"readOnly": true
},
"keywordDifficulty": {
"description": "SEO difficulty score (1-100) indicating how challenging it would be to rank organically for this keyword, with 100 being most difficult.",
"type": "integer",
"format": "int32",
"examples": [
69
],
"readOnly": true
},
"broadCostPerClick": {
"description": "Average cost per click for broad match advertising on this keyword.",
"type": [
"number",
"null"
],
"format": "double",
"examples": [
0.28
],
"readOnly": true
},
"phraseCostPerClick": {
"description": "Average cost per click for phrase match advertising on this keyword.",
"type": [
"number",
"null"
],
"format": "double",
"examples": [
0.28
],
"readOnly": true
},
"exactCostPerClick": {
"description": "Average cost per click for exact match advertising on this keyword. These costs fluctuate depending on many factors, so keep that in mind when you are estimating larger budgets.",
"type": [
"number",
"null"
],
"format": "double",
"examples": [
0.28
],
"readOnly": true
},
"seoClicks": {
"description": "Estimated monthly organic clicks this domain receives from this keyword based on current ranking position.",
"type": "integer",
"format": "int64",
"examples": [
3000
],
"readOnly": true
},
"seoClicksChange": {
"description": "Change in estimated organic clicks compared to the previous measurement period.",
"type": [
"integer",
"null"
],
"format": "int64",
"examples": [
-600
],
"readOnly": true
},
"totalMonthlyClicks": {
"description": "Total number of clicks (organic and paid combined) on search results for this keyword in the past month.",
"type": [
"integer",
"null"
],
"format": "int64",
"examples": [
647000
],
"readOnly": true
},
"percentMobileSearches": {
"description": "Percentage of searches for this keyword that come from mobile devices.",
"type": [
"number",
"null"
],
"format": "double",
"examples": [
0.4
],
"readOnly": true
},
"percentDesktopSearches": {
"description": "Percentage of searches for this keyword that come from desktop devices.",
"type": [
"number",
"null"
],
"format": "double",
"examples": [
0.6
],
"readOnly": true
},
"percentNotClicked": {
"description": "Percentage of searches where users leave the SERP without clicking any result.",
"type": [
"number",
"null"
],
"format": "double",
"examples": [
0.075
],
"readOnly": true
},
"percentPaidClicks": {
"description": "Percentage of total SERP clicks that go to paid ads.",
"type": [
"number",
"null"
],
"format": "double",
"examples": [
0.079
],
"readOnly": true
},
"percentOrganicClicks": {
"description": "Percentage of total SERP clicks that go to organic search results.",
"type": [
"number",
"null"
],
"format": "double",
"examples": [
0.921
],
"readOnly": true
},
"broadMonthlyCost": {
"description": "Estimated monthly advertising cost for broad match bidding on this keyword from the #2 position.",
"type": [
"number",
"null"
],
"format": "double",
"examples": [
6043.5
],
"readOnly": true
},
"phraseMonthlyCost": {
"description": "Estimated monthly advertising cost for phrase match bidding on this keyword from the #2 position.",
"type": [
"number",
"null"
],
"format": "double",
"examples": [
5695.5
],
"readOnly": true
},
"exactMonthlyCost": {
"description": "Estimated monthly advertising cost for exact match bidding on this keyword from the #2 position.",
"type": [
"number",
"null"
],
"format": "double",
"examples": [
5392.5
],
"readOnly": true
},
"paidCompetitors": {
"description": "Total number of advertisers observed purchasing ads for this keyword over the last 14 months.",
"type": [
"integer",
"null"
],
"format": "int32",
"examples": [
0
],
"readOnly": true
},
"rankingHomepages": {
"description": "Number of domain homepages (vs. deeper pages) ranking in the top 100 organic results for this keyword.",
"type": [
"integer",
"null"
],
"format": "int32",
"examples": [
10
],
"readOnly": true
},
"yourRank": {
"description": "The comparison domain's organic search position for this keyword (1 = top organic result). This field represents the rank of the domain specified in the 'compareDomain' parameter, allowing direct comparison with the primary query domain's rank.",
"type": [
"integer",
"null"
],
"format": "int32",
"examples": [
5
]
},
"yourRankChange": {
"description": "Change in the comparison domain's organic position from the previous data update. Positive values indicate the comparison domain moved up in rankings; negative values indicate it moved down. This shows how the comparison domain's performance has changed over time.",
"type": [
"integer",
"null"
],
"format": "int32",
"examples": [
-3
]
},
"yourUrl": {
"description": "The specific URL from the comparison domain that ranks for this keyword. This shows which page on the comparison domain is competing for this search term, providing insights into their content strategy.",
"type": [
"string",
"null"
],
"examples": [
"https://comparedomain.com/blog"
],
"readOnly": true
}
},
"additionalProperties": false,
"description": "Represents an organic search keyword with comprehensive SEO metrics including rankings, click estimates, costs, and SERP analysis data."
},
"readOnly": true
},
"totalMatchingResults": {
"description": "Total number of organic keywords available that match the query criteria, including results not included in the current page.",
"type": "integer",
"format": "int64",
"examples": [
75000
],
"readOnly": true
}
},
"additionalProperties": false
}
}
}
},
"400": {
"description": "Bad Request"
},
"401": {
"description": "User failed authorization"
},
"500": {
"description": "Internal Server Error"
}
},
"tags": [
"SEO Research API"
]
}
}
},
"components": {
"securitySchemes": {
"Basic_Authentication_Token": {
"type": "http",
"description": "Basic Authentication is a standard that involves encoding your SPYFU_API_ID:SECRET_KEY into a Base64 string. Your SpyFu API ID and Secret Key can both be found under the Account Settings -> API Usage page. Additionally, you can find the Base64 string has been pre-generated on the same page under Base 64 Key. Finally, this encoded string is sent in the \"Authorization\" header prefixed with the keyword \"Basic\":
For example, to authorize as 00000000-0000-0000-0000-000000000000:AB12WXYZ the client would send
Authorization: Basic MDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwOkFCMTJXWFla
",
"scheme": "basic"
},
"Query_Parameter_Token": {
"type": "apiKey",
"description": "An API key can be added as a query parameter. Your API key is listed as \"Secret Key\" found under the Account Settings -> API Usage page
For example, to authorize with the API key AB12WXY
/apis/example_api/GetExample?domain=spyfu.com&api_key=AB12WXYZ
",
"name": "api_key",
"in": "query"
},
"HMAC_Authentication_Header": {
"type": "apiKey",
"description": "For even more security, each request can be individually authenticated with a timestamped HMAC (Hash Message Authentication Code) signature. Composed of your secret key, a valid timestamp, the API request path, and all request parameters. Creating the signature:
Combine the pieces that will be converted into the signature.
StringToSign =
HTTP-Verb + \"\\n\" +
Timestamp + \"\\n\" +
UrlPath + \"\\n\"
QueryParameters;
Create UTF-8 encodings of the above string and of your secret key.
byte[] SecretKeyBytes = UTF-8-Encoding-Of( Upper-Case-Of( SECRET_KEY ) );
byte[] StringToSignBytes = UTF-8-Encoding-Of( StringToSign );
Use an implementation of HMAC256 using your UTF-8 secret key to encode the combined string of your request. This should then be converted to Base64 to finish creating your signature.
Signature = Base64( HMAC-SHA256( SecretKeyBytes, StringToSignBytes ) );
Using the signature:
This signature is then sent in through an Authentication header with your username.
Authentication: UserName:Signature
",
"name": "Authentication",
"in": "header"
}
}
},
"security": [
{
"Basic_Authentication_Token": []
},
{
"Query_Parameter_Token": []
},
{
"HMAC_Authentication_Header": []
}
]
}
```