Keyword API (v1)

Authentication

Basic Authentication Token

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

Security scheme type: HTTP
HTTP Authorization Scheme basic

Query Parameter Token

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

Security scheme type: API Key
Query parameter name: api_key

HMAC Authentication Header

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

Security scheme type: API Key
Header parameter name: Authentication

Related Keywords

Similar Keywords

get /related/getRelatedKeywords
https://www.spyfu.com/apis/keyword_api/related/getRelatedKeywords

Get keywords that contain term searched

query Parameters
query
required
string
Example: query=shoes

The keywords to query for.

sortBy
string
Default: null
Enum: "SearchVolume" "LiveSearchVolume" "RankingDifficulty" "TotalMonthlyClicks" "PercentMobileSearches" "PercentDesktopSearches" "PercentSearchesNotClicked" "PercentPaidClicks" "PercentOrganicClicks" "BroadCostPerClick" "PhraseCostPerClick" "ExactCostPerClick" "BroadMonthlyClicks" "PhraseMonthlyClicks" "ExactMonthlyClicks" "BroadMonthlyCost" "PhraseMonthlyCost" "ExactMonthlyCost" "PaidCompetitors" "RankingHomepages"
Example: sortBy=SearchVolume

Column to sort by.

sortOrder
string
Default: "Descending"
Enum: "Ascending" "Descending"
Example: sortOrder=Descending

Order to sort the results.

startingRow
integer <int32> [ 1 .. 2147483647 ]
Default: 1
Example: startingRow=1

Row number to start the results with.

pageSize
integer <int32> [ 1 .. 10000 ]
Default: 5
Example: pageSize=5

The maximum number of rows returned.

countryCode
string
Default: "US"
Enum: "AR" "AU" "BE" "BR" "CA" "CH" "DE" "DK" "ES" "FR" "IE" "IN" "IT" "JP" "MX" "NL" "NO" "NZ" "PT" "SE" "SG" "UA" "UK" "US" "ZA"
Example: countryCode=US

Country to get results for.

adultFilter
boolean
Default: true
Example: adultFilter=true

Exclude adult keywords considered unsafe for work.

Responses

200

OK

400

Bad Request

401

User failed authorization

500

Internal Server Error

Request samples

Copy
curl "https://www.spyfu.com/apis/keyword_api/related/getRelatedKeywords?query=shoes&sortBy=searchvolume&startingRow=1&pageSize=5&countryCode=US&adultFilter=false&api_key=SECRET_KEY"

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "resultCount": 100,
  • "totalMatchingResults": 0,
  • "results":
    [
    • {
      • "keyword": "red shoes",
      • "searchVolume": 266000,
      • "liveSearchVolume": 82000,
      • "rankingDifficulty": 98,
      • "totalMonthlyClicks": 219000,
      • "percentMobileSearches": 0.52009505,
      • "percentDesktopSearches": 0.47990492,
      • "percentSearchesNotClicked": 0.1792681,
      • "percentPaidClicks": 0.52188635,
      • "percentOrganicClicks": 0.47811362,
      • "broadCostPerClick": 0.73,
      • "phraseCostPerClick": 0.67,
      • "exactCostPerClick": 0.65,
      • "broadMonthlyClicks": 57019.8,
      • "phraseMonthlyClicks": 0,
      • "exactMonthlyClicks": 29094.6,
      • "broadMonthlyCost": 41604.9,
      • "phraseMonthlyCost": 25542,
      • "exactMonthlyCost": 19041.6,
      • "paidCompetitors": 15,
      • "distinctCompetitors":
        [
        • "string"
        ],
      • "rankingHomepages": 8,
      • "serpFeaturesCsv": "Images,Maps",
      • "serpFirstResult": "clarksusa.com",
      • "isQuestion": false,
      • "isNotSafeForWork": false
      }
    ]
}

Question Keywords

get /related/getQuestionKeywords
https://www.spyfu.com/apis/keyword_api/related/getQuestionKeywords

Get keywords that are questions

query Parameters
query
required
string
Example: query=shoes

The keywords to query for.

sortBy
string
Default: null
Enum: "SearchVolume" "LiveSearchVolume" "RankingDifficulty" "TotalMonthlyClicks" "PercentMobileSearches" "PercentDesktopSearches" "PercentSearchesNotClicked" "PercentPaidClicks" "PercentOrganicClicks" "BroadCostPerClick" "PhraseCostPerClick" "ExactCostPerClick" "BroadMonthlyClicks" "PhraseMonthlyClicks" "ExactMonthlyClicks" "BroadMonthlyCost" "PhraseMonthlyCost" "ExactMonthlyCost" "PaidCompetitors" "RankingHomepages"
Example: sortBy=SearchVolume

Column to sort by.

sortOrder
string
Default: "Descending"
Enum: "Ascending" "Descending"
Example: sortOrder=Descending

Order to sort the results.

startingRow
integer <int32> [ 1 .. 2147483647 ]
Default: 1
Example: startingRow=1

Row number to start the results with.

pageSize
integer <int32> [ 1 .. 10000 ]
Default: 5
Example: pageSize=5

The maximum number of rows returned.

countryCode
string
Default: "US"
Enum: "AR" "AU" "BE" "BR" "CA" "CH" "DE" "DK" "ES" "FR" "IE" "IN" "IT" "JP" "MX" "NL" "NO" "NZ" "PT" "SE" "SG" "UA" "UK" "US" "ZA"
Example: countryCode=US

Country to get results for.

adultFilter
boolean
Default: true
Example: adultFilter=true

Exclude adult keywords considered unsafe for work.

Responses

200

OK

400

Bad Request

401

User failed authorization

500

Internal Server Error

Request samples

Copy
curl "https://www.spyfu.com/apis/keyword_api/related/getQuestionKeywords?query=shoes&sortBy=searchvolume&startingRow=1&pageSize=5&countryCode=US&adultFilter=false&api_key=SECRET_KEY"

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "resultCount": 100,
  • "totalMatchingResults": 0,
  • "results":
    [
    • {
      • "keyword": "red shoes",
      • "searchVolume": 266000,
      • "liveSearchVolume": 82000,
      • "rankingDifficulty": 98,
      • "totalMonthlyClicks": 219000,
      • "percentMobileSearches": 0.52009505,
      • "percentDesktopSearches": 0.47990492,
      • "percentSearchesNotClicked": 0.1792681,
      • "percentPaidClicks": 0.52188635,
      • "percentOrganicClicks": 0.47811362,
      • "broadCostPerClick": 0.73,
      • "phraseCostPerClick": 0.67,
      • "exactCostPerClick": 0.65,
      • "broadMonthlyClicks": 57019.8,
      • "phraseMonthlyClicks": 0,
      • "exactMonthlyClicks": 29094.6,
      • "broadMonthlyCost": 41604.9,
      • "phraseMonthlyCost": 25542,
      • "exactMonthlyCost": 19041.6,
      • "paidCompetitors": 15,
      • "distinctCompetitors":
        [
        • "string"
        ],
      • "rankingHomepages": 8,
      • "serpFeaturesCsv": "Images,Maps",
      • "serpFirstResult": "clarksusa.com",
      • "isQuestion": false,
      • "isNotSafeForWork": false
      }
    ]
}

Also Buys Ads For Keywords

get /related/getAlsoBuysAdsForKeywords
https://www.spyfu.com/apis/keyword_api/related/getAlsoBuysAdsForKeywords

Get keywords other users who rank on this keyword also buy ads for.

query Parameters
query
required
string
Example: query=shoes

The keywords to query for.

sortBy
string
Default: null
Enum: "SearchVolume" "LiveSearchVolume" "RankingDifficulty" "TotalMonthlyClicks" "PercentMobileSearches" "PercentDesktopSearches" "PercentSearchesNotClicked" "PercentPaidClicks" "PercentOrganicClicks" "BroadCostPerClick" "PhraseCostPerClick" "ExactCostPerClick" "BroadMonthlyClicks" "PhraseMonthlyClicks" "ExactMonthlyClicks" "BroadMonthlyCost" "PhraseMonthlyCost" "ExactMonthlyCost" "PaidCompetitors" "RankingHomepages"
Example: sortBy=SearchVolume

Column to sort by.

sortOrder
string
Default: "Descending"
Enum: "Ascending" "Descending"
Example: sortOrder=Descending

Order to sort the results.

startingRow
integer <int32> [ 1 .. 2147483647 ]
Default: 1
Example: startingRow=1

Row number to start the results with.

pageSize
integer <int32> [ 1 .. 10000 ]
Default: 5
Example: pageSize=5

The maximum number of rows returned.

countryCode
string
Default: "US"
Enum: "AR" "AU" "BE" "BR" "CA" "CH" "DE" "DK" "ES" "FR" "IE" "IN" "IT" "JP" "MX" "NL" "NO" "NZ" "PT" "SE" "SG" "UA" "UK" "US" "ZA"
Example: countryCode=US

Country to get results for.

adultFilter
boolean
Default: true
Example: adultFilter=true

Exclude adult keywords considered unsafe for work.

Responses

200

OK

400

Bad Request

401

User failed authorization

500

Internal Server Error

Request samples

Copy
curl "https://www.spyfu.com/apis/keyword_api/related/getAlsoBuysAdsForKeywords?query=shoes&sortBy=searchvolume&startingRow=1&pageSize=5&countryCode=US&adultFilter=false&api_key=SECRET_KEY"

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "resultCount": 100,
  • "totalMatchingResults": 0,
  • "results":
    [
    • {
      • "keyword": "red shoes",
      • "searchVolume": 266000,
      • "liveSearchVolume": 82000,
      • "rankingDifficulty": 98,
      • "totalMonthlyClicks": 219000,
      • "percentMobileSearches": 0.52009505,
      • "percentDesktopSearches": 0.47990492,
      • "percentSearchesNotClicked": 0.1792681,
      • "percentPaidClicks": 0.52188635,
      • "percentOrganicClicks": 0.47811362,
      • "broadCostPerClick": 0.73,
      • "phraseCostPerClick": 0.67,
      • "exactCostPerClick": 0.65,
      • "broadMonthlyClicks": 57019.8,
      • "phraseMonthlyClicks": 0,
      • "exactMonthlyClicks": 29094.6,
      • "broadMonthlyCost": 41604.9,
      • "phraseMonthlyCost": 25542,
      • "exactMonthlyCost": 19041.6,
      • "paidCompetitors": 15,
      • "distinctCompetitors":
        [
        • "string"
        ],
      • "rankingHomepages": 8,
      • "serpFeaturesCsv": "Images,Maps",
      • "serpFirstResult": "clarksusa.com",
      • "isQuestion": false,
      • "isNotSafeForWork": false
      }
    ]
}

Also Ranks For Keywords

get /related/getAlsoRanksForKeywords
https://www.spyfu.com/apis/keyword_api/related/getAlsoRanksForKeywords

Get keywords other users who rank on this keyword also rank on organically.

query Parameters
query
required
string
Example: query=shoes

The keywords to query for.

sortBy
string
Default: null
Enum: "SearchVolume" "LiveSearchVolume" "RankingDifficulty" "TotalMonthlyClicks" "PercentMobileSearches" "PercentDesktopSearches" "PercentSearchesNotClicked" "PercentPaidClicks" "PercentOrganicClicks" "BroadCostPerClick" "PhraseCostPerClick" "ExactCostPerClick" "BroadMonthlyClicks" "PhraseMonthlyClicks" "ExactMonthlyClicks" "BroadMonthlyCost" "PhraseMonthlyCost" "ExactMonthlyCost" "PaidCompetitors" "RankingHomepages"
Example: sortBy=SearchVolume

Column to sort by.

sortOrder
string
Default: "Descending"
Enum: "Ascending" "Descending"
Example: sortOrder=Descending

Order to sort the results.

startingRow
integer <int32> [ 1 .. 2147483647 ]
Default: 1
Example: startingRow=1

Row number to start the results with.

pageSize
integer <int32> [ 1 .. 10000 ]
Default: 5
Example: pageSize=5

The maximum number of rows returned.

countryCode
string
Default: "US"
Enum: "AR" "AU" "BE" "BR" "CA" "CH" "DE" "DK" "ES" "FR" "IE" "IN" "IT" "JP" "MX" "NL" "NO" "NZ" "PT" "SE" "SG" "UA" "UK" "US" "ZA"
Example: countryCode=US

Country to get results for.

adultFilter
boolean
Default: true
Example: adultFilter=true

Exclude adult keywords considered unsafe for work.

Responses

200

OK

400

Bad Request

401

User failed authorization

500

Internal Server Error

Request samples

Copy
curl "https://www.spyfu.com/apis/keyword_api/related/getAlsoRanksForKeywords?query=shoes&sortBy=searchvolume&startingRow=1&pageSize=5&countryCode=US&adultFilter=false&api_key=SECRET_KEY"

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "resultCount": 100,
  • "totalMatchingResults": 0,
  • "results":
    [
    • {
      • "keyword": "red shoes",
      • "searchVolume": 266000,
      • "liveSearchVolume": 82000,
      • "rankingDifficulty": 98,
      • "totalMonthlyClicks": 219000,
      • "percentMobileSearches": 0.52009505,
      • "percentDesktopSearches": 0.47990492,
      • "percentSearchesNotClicked": 0.1792681,
      • "percentPaidClicks": 0.52188635,
      • "percentOrganicClicks": 0.47811362,
      • "broadCostPerClick": 0.73,
      • "phraseCostPerClick": 0.67,
      • "exactCostPerClick": 0.65,
      • "broadMonthlyClicks": 57019.8,
      • "phraseMonthlyClicks": 0,
      • "exactMonthlyClicks": 29094.6,
      • "broadMonthlyCost": 41604.9,
      • "phraseMonthlyCost": 25542,
      • "exactMonthlyCost": 19041.6,
      • "paidCompetitors": 15,
      • "distinctCompetitors":
        [
        • "string"
        ],
      • "rankingHomepages": 8,
      • "serpFeaturesCsv": "Images,Maps",
      • "serpFirstResult": "clarksusa.com",
      • "isQuestion": false,
      • "isNotSafeForWork": false
      }
    ]
}

Transactional Keywords

get /related/getTransactionKeywords
https://www.spyfu.com/apis/keyword_api/related/getTransactionKeywords

Get keyword searches that look transactional in nature.

query Parameters
query
required
string
Example: query=shoes

The keywords to query for.

sortBy
string
Default: null
Enum: "SearchVolume" "LiveSearchVolume" "RankingDifficulty" "TotalMonthlyClicks" "PercentMobileSearches" "PercentDesktopSearches" "PercentSearchesNotClicked" "PercentPaidClicks" "PercentOrganicClicks" "BroadCostPerClick" "PhraseCostPerClick" "ExactCostPerClick" "BroadMonthlyClicks" "PhraseMonthlyClicks" "ExactMonthlyClicks" "BroadMonthlyCost" "PhraseMonthlyCost" "ExactMonthlyCost" "PaidCompetitors" "RankingHomepages"
Example: sortBy=SearchVolume

Column to sort by.

sortOrder
string
Default: "Descending"
Enum: "Ascending" "Descending"
Example: sortOrder=Descending

Order to sort the results.

startingRow
integer <int32> [ 1 .. 2147483647 ]
Default: 1
Example: startingRow=1

Row number to start the results with.

pageSize
integer <int32> [ 1 .. 10000 ]
Default: 5
Example: pageSize=5

The maximum number of rows returned.

countryCode
string
Default: "US"
Enum: "AR" "AU" "BE" "BR" "CA" "CH" "DE" "DK" "ES" "FR" "IE" "IN" "IT" "JP" "MX" "NL" "NO" "NZ" "PT" "SE" "SG" "UA" "UK" "US" "ZA"
Example: countryCode=US

Country to get results for.

adultFilter
boolean
Default: true
Example: adultFilter=true

Exclude adult keywords considered unsafe for work.

Responses

200

OK

400

Bad Request

401

User failed authorization

500

Internal Server Error

Request samples

Copy
curl "https://www.spyfu.com/apis/keyword_api/related/getTransactionKeywords?query=shoes&sortBy=searchvolume&startingRow=1&pageSize=5&countryCode=US&adultFilter=false&api_key=SECRET_KEY"

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "resultCount": 100,
  • "totalMatchingResults": 0,
  • "results":
    [
    • {
      • "keyword": "red shoes",
      • "searchVolume": 266000,
      • "liveSearchVolume": 82000,
      • "rankingDifficulty": 98,
      • "totalMonthlyClicks": 219000,
      • "percentMobileSearches": 0.52009505,
      • "percentDesktopSearches": 0.47990492,
      • "percentSearchesNotClicked": 0.1792681,
      • "percentPaidClicks": 0.52188635,
      • "percentOrganicClicks": 0.47811362,
      • "broadCostPerClick": 0.73,
      • "phraseCostPerClick": 0.67,
      • "exactCostPerClick": 0.65,
      • "broadMonthlyClicks": 57019.8,
      • "phraseMonthlyClicks": 0,
      • "exactMonthlyClicks": 29094.6,
      • "broadMonthlyCost": 41604.9,
      • "phraseMonthlyCost": 25542,
      • "exactMonthlyCost": 19041.6,
      • "paidCompetitors": 15,
      • "distinctCompetitors":
        [
        • "string"
        ],
      • "rankingHomepages": 8,
      • "serpFeaturesCsv": "Images,Maps",
      • "serpFirstResult": "clarksusa.com",
      • "isQuestion": false,
      • "isNotSafeForWork": false
      }
    ]
}

Get Keywords By Bulk Search

get /related/getKeywordInformation
https://www.spyfu.com/apis/keyword_api/related/getKeywordInformation

Get keyword information for the exact keywords you are looking for

query Parameters
keywords
required
string

CSV of keywords

countryCode
string
Enum: "AR" "AU" "BE" "BR" "CA" "CH" "DE" "DK" "ES" "FR" "IE" "IN" "IT" "JP" "MX" "NL" "NO" "NZ" "PT" "SE" "SG" "UA" "UK" "US" "ZA"

Country to get information for

Responses

200

OK

400

Bad Request

401

User failed authorization

500

Internal Server Error

Request samples

Copy
curl "https://www.spyfu.com/apis/keyword_api/related/getKeywordInformation?keywords=shoes,red shoes,socks&countryCode=US&api_key=SECRET_KEY"

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "resultCount": 100,
  • "totalMatchingResults": 0,
  • "results":
    [
    • {
      • "keyword": "red shoes",
      • "searchVolume": 266000,
      • "liveSearchVolume": 82000,
      • "rankingDifficulty": 98,
      • "totalMonthlyClicks": 219000,
      • "percentMobileSearches": 0.52009505,
      • "percentDesktopSearches": 0.47990492,
      • "percentSearchesNotClicked": 0.1792681,
      • "percentPaidClicks": 0.52188635,
      • "percentOrganicClicks": 0.47811362,
      • "broadCostPerClick": 0.73,
      • "phraseCostPerClick": 0.67,
      • "exactCostPerClick": 0.65,
      • "broadMonthlyClicks": 57019.8,
      • "phraseMonthlyClicks": 0,
      • "exactMonthlyClicks": 29094.6,
      • "broadMonthlyCost": 41604.9,
      • "phraseMonthlyCost": 25542,
      • "exactMonthlyCost": 19041.6,
      • "paidCompetitors": 15,
      • "distinctCompetitors":
        [
        • "string"
        ],
      • "rankingHomepages": 8,
      • "serpFeaturesCsv": "Images,Maps",
      • "serpFirstResult": "clarksusa.com",
      • "isQuestion": false,
      • "isNotSafeForWork": false
      }
    ]
}