SpyFu · Schema
SpyFu SEO Research API Schemas
JSON Schema definitions for SpyFu SEO Research API API responses
SEOPPCCompetitive IntelligenceKeyword ResearchAd HistoryBacklinksDomain AnalyticsSERP
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "SpyFu SEO Research API Schemas",
"description": "JSON Schema definitions for SpyFu SEO Research API API responses",
"definitions": {
"OrganicSerpApi_GetMostValuableKeywords_GET": {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Get Most Valuable Keywords",
"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
},
"OrganicSerpApi_GetNewlyRankedKeywords_GET": {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Get Newly Ranked Keywords",
"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
},
"OrganicSerpApi_GetGainedRanksKeywords_GET": {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Get Gained Ranks Keywords",
"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": {
"descriptio
# --- truncated at 32 KB (162 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spyfu/refs/heads/main/json-schema/spyfu-seo-research-serp-schema.json