Keyword.com API


Keyword.com's simplistic API allows users to integrate our powerful ranking data into all of their applications and ideas.

API calls are made by sending a HTTP GET request to Keyword.com.

There are two different types authorization keys needed in successfully integrating Keyword.com into your program.


Your MASTER KEY is the primary authorization key needed - this is used to fetch category links, delete categories, add keywords, and delete keywords.

Your CATEGORY AUTHKEY is used along with your CATEGORY VIEWKEY to modify and fetch data from each individual category.


Please LOGIN to view your API Key

Fetch Regions and Languages

Information Description
Feature This call will allow return a list of supported regions and languages to add keywords
Method GET
URL http://keyword.com/serp/api/
Parameter Value Description
fetch regionslanguages This parameter is needed to request this data
Example Link
Query Link Click Here for a Sample Query
Responses
Success {"regions":["google.com",..."google.ws"],"languages":["en",..."zu"]}

Adding Keywords

Information Description
Feature This call will allow you to add a new keyword (a category is automatically created with the first added keyword).
Method GET
URL http://keyword.com/serp/api/
Parameter Value Description
action addkeyword addkeyword is the command we need to send to Keyword.com's API.
auth PLEASELOGIN Your MASTER KEY is needed to retrieve this information.
category YOUR CATEGORY NAME Specify the category name you want to add your keyword to. If the category does not exist, one will be created automatically. Maximum Length: 100 Characters
url or url[] YOUR URL Specify the URL you are trying to add, without the "http://" prefix. Use the url[] parameter to add multiple keywords.

For yt only include the video ID (for example "Hm-08DIMTT4").
kw or kw[] YOUR KEYWORD Specify the keyword you are trying to add. Use the kw[] parameter to add multiple keywords.
region google region (ie. google.com, google.ca) Specify the region you are trying to add corresponding to your URL/KW (List).
language language (ie. en, en-ca, en-au) Specify the language you are trying to add corresponding to your URL/KW (List).
type type of tracking (se, map, or yt) se for Google/Yahoo/Bing, map for Google maps, yt for YouTube
type desktop or mobile optional, defaults to desktop.
exact 0 OR 1 optional. Set this to 1 if you need to track an EXACT URL (ie. youtube.com/?v=V1jei32I) or set it to 0 if that is not needed.
near ZIP/POSTAL CODE optional. GEO Location Search - leave blank if not needed.
gmblistingname GMB Business Name optional track local results / map listings with GMB business name. read me.
ignore_local 0 or 1 optional, defaults to false/0. Set this to 1 to ignore local listings, or set it to 0 if not needed.
tags or tags[] tag1,tag2,another tag, tag3 optional. Include tags to go along with your keywords, if the keyword already exists, it will overwrite the existing tags. You can also pass multiple &tags parameters along to add in multiple, different tags for each keyword.
Example Link
Query Link Please Login
Responses
Success {"RESPONSE":"SUCCESS","VIEWKEY":"https:\/\/keyword.com\/serp\/api\/?viewkey=9o61jdh&auth=90029db3ffacedfa1cf3348e51d9038a", "USED": 120} Keyword has been successfully added, also includes the CATEGORY VIEWKEY link (which can be used to view category data). If an existing category exists, it will return the existing VIEWKEY link, otherwise one will be created. Also returns the current number of keywords in the account as used.
Error {"RESPONSE":"FULL"} There are no more keywords that can be added into your account, keyword limit reached
Error {"RESPONSE":"RATE LIMITED", "MESSAGE": "Please slow down adding in keywords and try again later."} You have been rate limited, please slow down, or upgrade your account
Error {"RESPONSE":"AUTHORIZATION ERROR"} Ensure &auth=PLEASELOGIN is set correctly
Error {"RESPONSE":"SUBSCRIPTION EXPIRED"} Your account's subscription has expired, please extend your account
Error {"RESPONSE":"CATEGORY TOO LONG"} Category must be 100 characters or less
Error {"RESPONSE":"INVALID REGION"} Unsupported Region - please use a supported region
Error {"RESPONSE":"INVALID LANGUAGE"} Unsupported Language - please use a supported language
Error {"RESPONSE":"ERROR_SYNC"} The number of url[] does not add up to the number of kw[]
Error {"RESPONSE":"ERROR_TAG_SYNC"} The number of tags[] does not add up to the number of url[]kw[]
Error {"RESPONSE":"ERROR"} Unknown error occurred, please contact us for assistance

Deleting Keywords

Information Description
Feature This call will allow you to delete a keyword (a category is automatically deleted at when it has 0 keywords).
Method GET
URL http://keyword.com/serp/api/
Parameter Value Description
action delkeyword delkeyword is the command we need to send to Keyword.com's API.
auth PLEASELOGIN Your MASTER KEY is needed to retrieve this information.
Method 1 - Using kwid|auth
kwid kwid|auth (for example 66565602|faa6192fbac8ecd7b87fb47671602304) You will need your keyword's kwid and auth and join them together with a "|". This can be found when fetching your category data (See "Fetching Category Data").
Method 2 - Passing all the variables
category YOUR CATEGORY NAME Specify the category name your keyword is currently in.
url YOUR URL Specify the URL you are trying to delete, without the "http://" prefix.
kw YOUR KEYWORD Specify the keyword you are trying to delete.
region google region (ie. google.com, google.ca) Include the region the keyword is associated to.
language language (ie. en, en-ca, en-au) Include the language the keyword is associated to.
Example Link
Query Link Please Login
Responses
Success {"RESPONSE":"SUCCESS", "USED": 120} Keyword has been successfully deleted. Also returns the current number of keywords in the account as used.
Error {"RESPONSE":"AUTHORIZATION ERROR"} Ensure &auth=PLEASELOGIN is set correctly
Error {"RESPONSE":"SUBSCRIPTION EXPIRED"} Your account's subscription has expired, please extend your account
Error {"RESPONSE":"INVALID REGION"} Unsupported REGION - please use a supported region
Error {"RESPONSE":"INVALID LANGUAGE"} Unsupported LANGUAGE - please use a supported language
Error {"RESPONSE": "ERROR", "MESSAGE": "Keyword does not exist"} The keyword you are trying to delete does not exist
Error {"RESPONSE":"ERROR"} Unknown error occurred, please contact us for assistance

Fetching Category Details

Information Description
Feature This call will fetch all of your categories' CATEGORY AUTHKEY and CATEGORY VIEWKEY in the form of a link. These two keys are needed to fetch the data in your categories.
Method GET
URL /serp/api/
Parameter Value Description
action getcategories getcategories is the command we need to send to Keyword.com's API.
auth PLEASELOGIN Your MASTER KEY is needed to retrieve this information.
start_date 2024-11-21 optional - you can specify a date in YYY-MM-DD format to view the category from a previous date.
Example Link
Query Link Please Login
Responses
Success {"demo":"https:\/\/keyword.com\/serp\/api\/?viewkey=9o61jdh&auth=90029db3ffacedfa1cf3348e51d9038a"}
Error {"RESPONSE": "NO CATEGORIES FOUND"} No categories are in the account
Error {"RESPONSE": "AUTHORIZATION ERROR"} Ensure &auth=PLEASELOGIN is set correctly

Fetching Single Category's ViewKey

Information Description
Feature This call will fetch a single categories' CATEGORY AUTHKEY and CATEGORY VIEWKEY in the form of a link. These two keys are needed to fetch the data in your categories. This call is for faster usage, rather than loading the entire category list.
Method GET
URL /serp/api/
Parameter Value Description
action getsinglecategory getsinglecategory is the command we need to send to Keyword.com's API.
auth PLEASELOGIN Your MASTER KEY is needed to retrieve this information.
category REQUESTED CATEGORY Enter in the category name you wish to retrieve - must be exactly as when it was created.
Example Link
Query Link Please Login
Responses
Success {"RESPONSE":"SUCCESS","demo":"https:\/\/keyword.com\/serp\/api\/?viewkey=9o61jdh&auth=90029db3ffacedfa1cf3348e51d9038a"}
Error {"RESPONSE":"CATEGORY NOT FOUND"} Requested category does not exist in the account
Error {"RESPONSE": "AUTHORIZATION ERROR"} Ensure &auth=PLEASELOGIN is set correctly

Once you have your category's CATEGORY AUTHKEY and CATEGORY VIEWKEY, you can then perform another call to fetch your current category data.

Fetching Category Data

Information Description
Feature This call will fetch a snapshot of your category's current data.
Method GET
URL http://keyword.com/serp/api/
Parameter Value Description
viewkey CATEGORY VIEWKEY Use the returned CATEGORY VIEWKEY from the API Call from the 'Fetching Category Details' section.
auth CATEGORY AUTHKEY Use the returned CATEGORY AUTHKEY from the API Call from the 'Fetching Category Details' section.
Responses
Success [{"kwid":"6181140","auth":"4971ad14406547aee9718801e4ba9ca7",...}]
Error {"RESPONSE": "NO KEYWORDS"} There are currently no keywords in the category
Error {"RESPONSE": "AUTHORIZATION ERROR"} Ensure CATEGORY VIEWKEY and CATEGORY AUTHKEY is set correctly
Successful Response Breakdown
Parameter Example Description
kwid 18960839 Keyword's Unique Keyword ID - used internally by Keyword.com
auth 5ca9b961874c4847122fc22e0884d990 Keyword's Unique Authorization ID - used internally by Keyword.com
category demo Keyword's Category Name
url google.com Keyword's URL
kw google Keyword's URL
url google.com Keyword being tracked
region google.com Keyword region being tracked
language en Keyword language being tracked
near 91210 Keyword's location setting, will return blank if there is none
ignore_local 1 Will return a 1 if local listings are ignored, or 0 if local listings are included
type se Type of search engine being tracked. se for regular search engines (Google/Yahoo/Bing) sem for Google Mobile yt for YouTube map for Google Maps
exact true or false Will return a true if the the exact URL is being tracked, false if the broad domain is tracked
ignore_local 1 or 0 Will return a 1 if local listings are ignored, or 0 if local listings are included
start 13 Keyword's STARTING position (first recorded positon)
start 13 Keyword's STARTING position (first recorded positon)
grank 5 Keyword's Ranking, depending on the type, returns ?? when data is still being fetched initially, 0 for unranked - (ie. Google for se, Google Mobile for sem, YouTube for yt, Google Maps for maps
grankhistory ["1","1","1",..."1","1","1"] Keyword's Historical Ranking (30 day max) - the current day is the first array (far left) and is incremented daily onwards
brank 5 Keyword's Bing Ranking (only if type is se, returns "0" for unranked
yrank 5 Keyword's Yahoo Ranking (only if type is se, returns "0" for unranked
isfav 0 Returns 1 if keyword is favorited or 0 if keyword is not favorited (favoring is toggled via keyword.com web dashbaord)
day 0 Day Change
week 0 Week Change
month 0 Month Change
Life 0 Life Change (comparing current ranking and start ranking)
rankingurl https://www.google.com/ Ranking URL - will return "NOT FOUND" if the keyword is not ranking
seocomp 1880000000 Number of competing pages on Google - ie. About 60,900,000 results (0.57 seconds)
searchvolume 1880000000 Number of searches per month for this keyword, region specific (data from Google Keyword Planner)
cpc 0.514586 Cost per click in USD for this keyword, region specific (data from Google Keyword Planner)
tags tag1,tag2,tag3 Tags associated to this keyword, modified through keyword.com web dashboard
timestamp 2015-04-08 Date the keyword was added in
lastupdate.when an hour ago Returns the approximate time the keyword was last updated
lastupdate.date Jul 09th, 2017 Returns the date the keyword was last updated

Delete a Category

Information Description
Feature This call will delete the entire category, including all of the keywords inside.
Method GET
URL http://keyword.com/serp/api/
Parameter Value Description
action delcategory delcategory is the command we need to send to Keyword.com's API.
auth PLEASELOGIN Your MASTER KEY is needed to retrieve this information.
category CATEGORY to DELETE Enter in the category name you wish to retrieve - must be exactly as when it was created.
Query Link Please Login
Responses
Success {"RESPONSE": "SUCCESS", "MESSAGE": "CATEGORY DELETED", "USED": 120} Category has been successfully deleted. Also returns the current number of keywords in the account as used.
Error {"RESPONSE": "AUTHORIZATION ERROR"} Ensure &auth=PLEASELOGIN is set correctly
Error {"RESPONSE": "CATEGORY DOES NOT EXIST"} No categories or keywords were affected - perhaps this category has been deleted already

Refresh a Category

Information Description
Feature This call will allow you to use your on-demand keyword updates to refresh a category's keywords.
Method GET
URL http://keyword.com/serp/api/
Parameter Value Description
action refreshkws refreshkws is the command we need to send to Keyword.com's API.
auth PLEASELOGIN Your MASTER KEY is needed to retrieve this information.
refresh CATEGORY to REFRESH Enter in the category name you wish to refresh - must match exactly.
kwid[] POST this value to restrict to refresh specific keywords (optional, can submit multiple kwid[]) A kwid|auth format can be submitted to restrict the refresh to specific keywords. Ie. 69777994|8415bb30c2a5794ca11f4c8c7dc8e69f.
Query Link Please Login
Responses
Success {"response":"success","message":"Success! Your keywords will automatically refresh once updated.","remaining":"You have 2998 keyword refreshes left."} Category has been successfully refreshed
Error {"response":"failure","code":"refreshes_exceeded","message":"You have exceeded the daily allowed refreshes (no more refreshes left)!"} You have exceeded your daily refreshes, the limit will be reset at 12AM EST.
Error {"response":"failure","code":"category_not_found","message":"Error: Category not found."} Incorrect category entered / category not found.
Error {"RESPONSE": "AUTHORIZATION ERROR"} Ensure &auth=PLEASELOGIN is set correctly

Refresh Status of a Category

Information Description
Feature This call will allow you to see the status of your on-demand refresh.
Method GET
URL http://keyword.com/serp/api/
Parameter Value Description
action refreshremaining refreshremaining is the command we need to send to Keyword.com's API.
auth PLEASELOGIN Your MASTER KEY is needed to retrieve this information.
category CATEGORY to CHECK Enter in the category name you wish to check - must match exactly.
Query Link Please Login
Responses
Success {"remaining": 6} An integer will be returned, for the amount of remaining keyword to be updated in the category.

Retrieving a Single Keyword Data

Information Description
Feature This call will fetch historical ranking data for a single keyword.
Method GET
URL http://keyword.com/serp/api/
Parameter Value Description
viewkey CATEGORY VIEWKEY Use the returned CATEGORY VIEWKEY from the API Call from the 'Fetching Category Details' section.
auth CATEGORY AUTHKEY Use the returned CATEGORY AUTHKEY from the API Call from the 'Fetching Category Details' section.
single 1 This parameter tells Keyword.com that you are trying to retrieve a single keyword's historical data.
start_date Start date (YYY-MM-DD) (OPTIONAL) Optional start date range you can choose to specify.
end_date End date (YYY-MM-DD) (OPTIONAL) Optional end date range you can choose to specify.
Method 1 - Using kwid|auth
kwid kwid|auth (for example 66565602|faa6192fbac8ecd7b87fb47671602304) You will need your keyword's kwid and auth and join them together with a "|". This can be found when fetching your category data (See "Fetching Category Data").
Method 2 - Passing all the variables
url YOUR URL Enter in your URL you are trying to retrieve, without the "http://" prefix.
kw YOUR KEYWORD Enter in your keyword you are trying to retrieve.
category YOUR CATEGORY Enter in the category associated with the keyword you are trying to retrieve.
region google region (ie. google.com, google.ca) Enter in your region you are trying to retrieve corresponding to your URL/KW.
language language (ie. en, en-ca, en-au) Enter in your language you are trying to retrieve corresponding to your URL/KW.
Responses
Query Link Please Login
Responses
Success [{"url":"Google.com",..."date":"2016-03-22"}] Returns an array with the historical data
No Data [] Ensure the keyword exists in the category, and all the parameters are set correctly
Error {"RESPONSE": "MISSING INFORMATION"} Ensure the required parameters url kw category region are set
Error {"RESPONSE": "INVALID START DATE"} Ensure the START DATE is correctly set in YYYY-MM-DD format (ie. 2024-11-21)
Error {"RESPONSE": "INVALID END DATE"} Ensure the END DATE is correctly set in YYYY-MM-DD format (ie. 2024-11-21)
Error {"RESPONSE": "AUTHORIZATION ERROR"} Ensure CATEGORY VIEWKEY and CATEGORY AUTHKEY is set correctly

Update Baseline/Start Value for a Keyword

Information Description
Feature This call will update the baseline/start value for a keyword, used in calculation of the "Life" change value.
Method GET
URL http://keyword.com/serp/api/
Parameter Value Description
action updatebaseline Required
auth PLEASELOGIN Your MASTER KEY is needed to retrieve this information.
kwid kwid|auth (for example 66565602|faa6192fbac8ecd7b87fb47671602304) You will need your keyword's kwid and auth and join them together with a "|". This can be found when fetching your category data (See "Fetching Category Data").
baselinevalue 5 Numerical number (integer, 0-100, with 0 being "unranked").
Query Link Please Login
Responses
Success {"RESPONSE": "SUCCESS"} Your baseline value has been successfully updated.
Error {"RESPONSE": "ERROR"} Your baseline value has not changed, most likely you passed the existing, unchanged baseline value. Must be different baseline values to trigger a "success".
Error {"RESPONSE": "AUTHORIZATION ERROR"} Ensure your MASTER KEY and your keyword's kwid and auth are set correctly.

Fetch Account Information

Information Description
Feature This call will return basic account information, about quotas and subscriptions.
Method GET
URL http://keyword.com/serp/api/
Parameter Value Description
action fetchaccountinfo Required
auth PLEASELOGIN Your MASTER KEY is needed to retrieve this information.
Query Link Please Login
Responses
Success {"response":"success" ... } Successful request will return account data.
Error {"response": "error"} Something went wrong, please double check your API key.
Error {"RESPONSE": "AUTHORIZATION ERROR"} Ensure your MASTER KEY and your keyword's kwid and auth are set correctly.

API Changelog

2019-05-01

Added format for SERP RAW JSON API

2019-04-26

remaining_api_credits added into fetchaccountinfo

2019-04-16

fetchaccountinfo API call added

2018-12-09

seocomp data restored in the API

2018-12-06

backlinks and seocomp data will no longer be supported and will return a value of 0

2018-07-15

exact data added into the response

2018-01-22

Multiple tags supported in bulk add

2017-10-18

Added in USED keyword count in addkeyword, delkeyword

2017-08-27

&start_date documentation added in to view a report from a previous date

2017-08-24

"Retrieving a Single Keyword Data" id parameter is now updated to category
"Retrieving a Single Keyword Data" Added in kwid|auth support

2017-08-22

Developers section has been updated to support adding bulk keywords and yt and map keywords.

2017-08-10

delkeyword API has been updated to support kwid|auth method, and an error message is returned if the keyword does not exist.

2017-07-09

Last updated information updated, to include the "when" and "date" of last updated.

2017-06-01

Update Baseline/Start Value for a Keyword support added in.
Certain requests now use ?action= instead of ?viewkey= (this is just a display update, existing queries will not be affected)

2017-04-02

RAW JSON data support added in.

2017-02-15

Reset API feature added in.

2017-02-10

&e= parameter is no longer required, existing queries will work normally.

2017-02-02

Added in {"RESPONSE":"SUBSCRIPTION EXPIRED"} for expired subscriptions.

2017-02-01

Changelog started - any new updates to the API will be listed here.