Get Gained Ranks Keywords

get

https://api.spyfu.com/apis/serp_api/v2/seo/getGainedRanksKeywords

Returns keywords where a domain, path, subdomain, page or full URL improved its organic search ranking positions compared to the previous month. This endpoint identifies the biggest ranking gains to reveal successful SEO efforts and content optimizations.

Visualize this API live on SpyFu

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

query

string

required

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.

compareDomain

string

Domain to compare against when evaluating where it outranks you and where you outrank it.

includeTerms

string

Comma-separated list of terms that must be present in the keyword.

includeAnyTerm

boolean

Defaults to false

Used with includeTerms. If true: match any term (OR). If false: require all terms (AND).

excludeTerms

string

Comma-separated list of terms to exclude from results (e.g., branded or irrelevant terms).

excludeHomepageKeywords

boolean

Defaults to false

If true, exclude keywords where the domain/URL's homepage (root domain, e.g., example.com) ranks; if false, include all.

searchVolume.min

float

Filter to keywords where monthly search volume (Google) is ≥ this value.

searchVolume.max

float

Filter to keywords where monthly search volume (Google) is ≤ this value.

keywordDifficulty.min

float

Filter to keywords where the keyword difficulty score is ≥ this value (0-100; higher = harder to rank).

keywordDifficulty.max

float

Filter to keywords where the keyword difficulty score is ≤ this value (0-100; higher = harder to rank).

rank.min

float

Filter to keywords where the domain/URL rank position is ≥ this value (1 = best/top organic result).

rank.max

float

Filter to keywords where the domain/URL rank position is ≤ this value (1 = best/top organic result).

rankChange.min

float

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.

rankChange.max

float

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.

costPerClick.min

float

Filter to keywords where the average cost per click (CPC) is ≥ this value.

costPerClick.max

float

Filter to keywords where the average cost per click (CPC) is ≤ this value.

costPerClickOption

string

enum

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).

Show Details

Broad	Includes keyword variations and related terms
Exact	Requires precise keyword match only
Phrase	Includes the keyword phrase in order with additional words

Allowed:

seoClicks.min

float

Filter to keywords where estimated monthly organic clicks (SEO clicks) to the domain/url are ≥ this value.

seoClicks.max

float

Filter to keywords where estimated monthly organic clicks (SEO clicks) to the domain/url are ≤ this value.

seoClicksChange.min

float

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.

seoClicksChange.max

float

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.

percentMobileSearches.min

float

Filter to keywords where the mobile search share (%) is ≥ this value (range 0-100).

percentMobileSearches.max

float

Filter to keywords where the mobile search share (%) is ≤ this value (range 0-100).

percentDesktopSearches.min

float

Filter to keywords where the desktop search share (%) is ≥ this value (range 0-100).

percentDesktopSearches.max

float

Filter to keywords where the desktop search share (%) is ≤ this value (range 0-100).

percentNotClicked.min

float

Filter to keywords where the percentage of searches with no click is ≥ this value (range 0-100).

percentNotClicked.max

float

Filter to keywords where the percentage of searches with no click is ≤ this value (range 0-100).

percentPaidClicks.min

float

Filter to keywords where the share of SERP clicks going to paid ads (%) is ≥ this value (range 0-100).

percentPaidClicks.max

float

Filter to keywords where the share of SERP clicks going to paid ads (%) is ≤ this value (range 0-100).

percentOrganicClicks.min

float

Filter to keywords where the share of SERP clicks going to organic results (%) is ≥ this value (range 0-100).

percentOrganicClicks.max

float

Filter to keywords where the share of SERP clicks going to organic results (%) is ≤ this value (range 0-100).

monthlyCost.min

float

Filter to keywords where the estimated monthly advertising cost is ≥ this value.

monthlyCost.max

float

Filter to keywords where the estimated monthly advertising cost is ≤ this value.

monthlyCostOption

string

enum

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).

Show Details

Broad	Includes keyword variations and related terms
Exact	Requires precise keyword match only
Phrase	Includes the keyword phrase in order with additional words

Allowed:

paidCompetitors.min

float

Filter to keywords where the number of distinct advertisers observed over the last 14 months is ≥ this value.

paidCompetitors.max

float

Filter to keywords where the number of distinct advertisers observed over the last 14 months is ≤ this value.

rankingHomepages.min

float

Filter to keywords where the number of homepage/root-domain URLs in the top 100 results is ≥ this value.

rankingHomepages.max

float

Filter to keywords where the number of homepage/root-domain URLs in the top 100 results is ≤ this value.

totalMonthlyClicks.min

float

Filter to keywords where total monthly SERP clicks (all domains) are ≥ this value. Independent of rank; includes both organic and paid clicks.

totalMonthlyClicks.max

float

Filter to keywords where total monthly SERP clicks (all domains) are ≤ this value. Includes both organic and paid clicks.

adCount.min

float

Filter to keywords where the number of distinct advertisers observed over the last 14 months is ≥ this value.

adCount.max

float

Filter to keywords where the number of distinct advertisers observed over the last 14 months is ≤ this value.

pageSize

int32

1 to 10000

Defaults to 5

The maximum number of rows returned.

countryCode

string

enum

Defaults to US

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

sortBy

string

enum

Defaults to SearchVolume

Column to sort by.

Show Details

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

sortOrder

string

enum

Defaults to Descending

Order to sort the results.

Allowed:

startingRow

int32

1 to 10000

Defaults to 1

Row number to start the results with.

adultFilter

boolean

Defaults to true

Exclude adult keywords considered unsafe for work.

onlyAdultKeywords

boolean

Defaults to false

Only include adult keywords considered unsafe for work.

exactMatch

boolean

Indicates whether to apply exact match filtering for the query. This parameter will result in only exact matches, meaning protocols (http/https) and trailing slashes must be included. For example, a query of "https://example.com/blog" will not match

"example.com/blog"
"https://example.com/blog/"

Responses

400

Bad Request

401

User failed authorization

500

Internal Server Error

200OK