7th June 2025 - All API methods are now available for all subscription plans, including the Bronze.

# Get Keyword Data ?> **POST** `{{{v1.server}}}/get_keyword_data` Get Volume, CPC and competition for a set of keywords. Also returns the amount of credits left in the account. **Note:** Each keyword result retrieved through this API endpoint consumes 1 credit. ### Authorization You need an API key to access this API endpoint. Get your API key [here](https://keywordseverywhere.com/first-install-addon.html). ### Example API Calls #### ** Bash ** - Urlencoded version ```shell script params=() params+=('kw[]=keywords tool') params+=('kw[]=keyword planner') params+=("kw[]=$(echo -e 'brésil' | iconv -t utf-8)") # For shells not using UTF-8, ensure that your input data is encoded in UTF-8. params+=('country=us') params+=('currency=usd') params+=('dataSource=cli') data=$(IFS='&' ; echo "${params[*]}") curl -H 'Authorization: Bearer {{{v1.apiKey}}}' -H 'Accept: application/json' --data "$data" '{{{v1.server}}}/get_keyword_data' ``` - JSON version ```shell script curl -H 'Authorization: Bearer {{{v1.apiKey}}}' -H 'Accept: application/json' -H 'Content-type: application/json' --data '{ "kw": [ "keywords tool", "keyword planner", "brésil" ], "country": "us", "currency": "usd", "dataSource": "cli" }' '{{{v1.server}}}/get_keyword_data' ``` #### ** PHP ** ```php [ "keywords tool", "keyword planner", mb_convert_encoding("brésil", 'UTF-8') # Please ensure that your input data is encoded in UTF-8. ], "country" => "us", "currency" => "usd", "dataSource" => "cli" ]; $query = http_build_query($parameters); $ch = curl_init('{{{v1.server}}}/get_keyword_data'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Accept: application/json', 'Authorization: Bearer {{{v1.apiKey}}}' )); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $query); $data = curl_exec($ch); $err = curl_error($ch); $info = curl_getinfo($ch); curl_close($ch); if($info['http_code'] == 200){ echo "Success!\n\n" . $data; } else { echo "An error occurred.\n\n" . $data; } ``` #### ** Laravel ** ```php acceptJson() ->asForm() ->post('{{{v1.server}}}/get_keyword_data', [ "kw" => [ "keywords tool", "keyword planner", mb_convert_encoding("brésil", 'UTF-8') # Please ensure that your input data is encoded in UTF-8. ], "country" => "us", "currency" => "usd", "dataSource" => "cli" ]); try { echo $response->throw()->body(); } catch (\Exception $e) { echo "An error occurred.\n\n" . $e->getMessage(); } return 0; } } ``` #### ** Java ** ```java package org.example; import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; import com.mashape.unirest.http.exceptions.UnirestException; import java.util.Arrays; public class GetKeywordData { public static void main(String[] args) throws UnirestException { // Unirest automatically encodes data in the standard UTF-8 format during a request. // However, when using HttpURLConnection or similar libraries, ensure they are set to use UTF-8 encoding. HttpResponse response = Unirest.post("{{{v1.server}}}/get_keyword_data") .header("Accept", "application/json") .header("Authorization", "Bearer {{{v1.apiKey}}}") .field("kw[]", Arrays.asList( "keywords tool", "keyword planner", "brésil" )) .field("country", "us") .field("currency", "usd") .field("dataSource", "cli") .asString(); if (response.getStatus() == 200) { System.out.printf("Success.\n\n%s\n", response.getBody()); } else { System.out.printf("An error occurred.\n\n%s\n", response.getBody()); } } } ``` #### ** Python ** ```python # pip install requests import requests my_headers = { 'Accept': 'application/json', 'Authorization': 'Bearer {{{v1.apiKey}}}' } # In Python 3, strings are inherently in UTF-8 encoding. # Character set conversions are unnecessary unless directly dealing with byte arrays. my_data = { 'kw[]': [ "keywords tool", "keyword planner", "brésil" ], "country": "us", "currency": "usd", "dataSource": "cli" } response = requests.post('{{{v1.server}}}/get_keyword_data', data=my_data, headers=my_headers) if response.status_code == 200: print('success\n\n' + response.content.decode('utf-8')) else: print("An error occurred\n\n" + response.content.decode('utf-8')) ``` #### ** Ruby ** ```ruby require 'uri' require 'net/http' require 'openssl' endpoint_url = URI("{{{v1.server}}}/get_keyword_data") http = Net::HTTP.new(endpoint_url.host, endpoint_url.port) {{^v1_ruby_disable_ssl}} http.use_ssl = false {{/v1_ruby_disable_ssl}} request_params = [] kw_array = [ "keywords tool", "keyword planner", "brésil" ] for kw_item in kw_array do request_params.append("kw[]=" + kw_item) end request_params.append("country=us") request_params.append("currency=usd") request_params.append("dataSource=cli") request = Net::HTTP::Post.new(endpoint_url) request["Accept"] = 'application/json' request["Authorization"] = 'Bearer {{{v1.apiKey}}}' # Ensure that your data is encoded in UTF-8 format before sending it to the API request.body = request_params.join("&").encode(Encoding::UTF_8) response = http.request(request) if response.code == "200" puts "Success\n\n%s" % response.read_body else puts "An error occurred\n\n%s" % response.read_body end ``` #### ** NodeJs ** ```js // The Fetch API inherently supports only UTF-8 encoding, eliminating the need for character set conversions. fetch('{{{v1.server}}}/get_keyword_data', { method: 'POST', body: new URLSearchParams([ ["kw[]", "keywords tool"], ["kw[]", "keyword planner"], ["kw[]", "brésil"], ["country", "us"], ["currency", "usd"], ["dataSource", "cli"] ]), headers: { 'Accept': 'application/json', 'Authorization': `Bearer {{{v1.apiKey}}}` }, }) .then((response) => response.text()) .then((text) => console.log(text)) .catch(error => { console.log(error) }) ``` #### ** R ** ```R #install.packages(c("httr", "jsonlite")) library(httr) library(jsonlite) body <- list() kw <- c( "keywords tool", "keyword planner", "brésil" ) for (i in 1:length(kw)) { body[[paste('kw[', i, ']', sep = '')]] <- kw[i] } body["country"] <- "us" body["currency"] <- "usd" body["dataSource"] <- "cli" # R strings and httr requests use UTF-8 by default, removing the need for post data character set conversions. res = POST( "{{{v1.server}}}/get_keyword_data", body = body, add_headers('Accept' = 'application/json', 'Authorization' = 'Bearer {{{v1.apiKey}}}') ) prettify(content(res, as = "text", encoding = "UTF-8")) ``` #### ** n8n (Custom Node) ** #### Workflow Diagram ![](images/n8n/custom_node/get_keyword_data.png) #### Steps to Import the Workflow 1. If you haven't done so already, install the **[Keywords Everywhere API](https://www.npmjs.com/package/n8n-nodes-keywords-everywhere-api)** community node in your n8n instance. 2. Copy the JSON below and save it in a file. ```json {{=<% %>=}} { "name": "Get Keyword Data with Keywords Everywhere API", "nodes": [ { "parameters": [], "type": "n8n-nodes-base.manualTrigger", "typeVersion": 1, "position": [ 60, -80 ], "id": "c8208228-b0b9-48ea-bc1b-78486f157b81", "name": "When clicking ‘Test workflow’" }, { "parameters": { "jsCode": "return [\n {\n \"keywords\": [\"climate change\", \"expired domains\"]\n }\n];" }, "type": "n8n-nodes-base.code", "typeVersion": 2, "position": [ 280, -80 ], "id": "5bbb3e77-7774-4e11-8849-311009a869cf", "name": "Generate keywords array" }, { "parameters": { "keywords_input_type": "json", "keywords_json": "={{ JSON.stringify($json.keywords) }}", "dataSource": "cli" }, "type": "n8n-nodes-keywords-everywhere-api.keApi", "typeVersion": 1, "position": [ 500, -80 ], "id": "2ebc67ad-8b54-46cb-ba9c-cde4dc8e0c86", "name": "Get Keyword Data", "credentials": { "keApi": { "id": "N2i3rMzytn7OfaN3", "name": "Keywords Everywhere account" } } } ], "pinData": [], "connections": { "When clicking ‘Test workflow’": { "main": [ [ { "node": "Generate keywords array", "type": "main", "index": 0 } ] ] }, "Generate keywords array": { "main": [ [ { "node": "Get Keyword Data", "type": "main", "index": 0 } ] ] } }, "active": false, "settings": { "executionOrder": "v1" }, "versionId": "7b4fa5b9-c760-439b-b91f-e61d0396eb3c", "meta": { "templateCredsSetupCompleted": true, "instanceId": "05035923b4e6188dc7851e2829900eebe8ed69d4f94ad4bab03daf6d88491d90" }, "id": "fb6mxQghbcHEbRgJ", "tags": [] } <%={{ }}=%> ``` 3. In your n8n instance, click on the **⋯** menu at the top right and select the **Import from File** option. 4. Select the JSON file you saved above. 5. Adjust any necessary parameters (e.g., **Keywords Everywhere** credentials). #### ** n8n (HTTP Request) ** #### Workflow Diagram ![](images/n8n/http_request/get_keyword_data.png) #### Steps to Recreate the Workflow 1. Start with a **Trigger Node**: e.g., **"Trigger Manually"** to invoke the workflow. 2. Add a **"HTTP Request"** node. - Click **"Import cURL"** at the top right of the node editor. - Paste the command below and click **"Import"**. ```shell curl -H 'Authorization: Bearer {{{v1.apiKey}}}' -H 'Accept: application/json' -H 'Content-type: application/json' --data '{ "kw": [ "keywords tool", "keyword planner", "brésil" ], "country": "us", "currency": "usd", "dataSource": "cli" }' '{{{v1.server}}}/get_keyword_data' ``` - Adjust the authorization header with your **Keywords Everywhere** API key. ![](../_media/n8n/authorization_header.png) 3. Adjust any necessary parameters (e.g., you can rename the node to **"Get Keyword Data"**). #### ** Make.com ** #### Scenario Diagram ![](images/make/get_keyword_data.png) #### Steps to Recreate the Above Scenario 1. Copy the JSON blueprint below and save it as a file (for example, blueprint.json). ```json { "name": "Get Keyword Data - Keywords Everywhere API", "flow": [ { "id": 2, "module": "app#keywords-everywhere-api:getKeywordData", "version": 1, "parameters": { "__IMTCONN__": 3266898 }, "mapper": { "kw": [ "keywords tool", "keyword planner" ], "country": "us", "currency": "usd", "dataSource": "gkp" }, "metadata": { "designer": { "x": 0, "y": 0 }, "restore": { "expect": { "kw": { "mode": "chose", "items": [ null, null ] } }, "parameters": { "__IMTCONN__": { "data": { "scoped": "true", "connection": "app#keywords-everywhere-api-0p871s" }, "label": "Keywords Everywhere Production" } } }, "parameters": [ { "name": "__IMTCONN__", "type": "account:app#keywords-everywhere-api-0p871s", "label": "Connection", "required": true } ], "expect": [ { "name": "kw", "spec": { "name": "value", "type": "text" }, "type": "array", "label": "Kw", "required": true }, { "name": "country", "type": "text", "label": "Country", "required": true }, { "name": "currency", "type": "text", "label": "Currency", "required": true }, { "name": "dataSource", "type": "text", "label": "Data Source", "required": true }, { "name": "kw", "spec": { "name": "value", "type": "text" }, "type": "array", "label": "Kw", "required": true }, { "name": "country", "type": "text", "label": "Country", "required": true }, { "name": "currency", "type": "text", "label": "Currency", "required": true }, { "name": "dataSource", "type": "text", "label": "Data Source", "required": true } ] } } ], "metadata": { "instant": false, "version": 1, "scenario": { "roundtrips": 1, "maxErrors": 3, "autoCommit": true, "autoCommitTriggerLast": true, "sequential": false, "slots": null, "confidential": false, "dataloss": false, "dlq": false, "freshVariables": false }, "designer": { "orphans": [] }, "zone": "us2.make.com", "notes": [] } } ``` 2. Sign in at make.com using your credentials. 3. From your dashboard, click **"Scenarios"** in the navigation menu. 4. Click the **"Create a new scenario"** button in the top right. 5. In the scenario editor, click the ellipsis (⋯) menu in the bottom left and select **"Import blueprint."** ![](../_media/make/import_blueprint.png) 6. When prompted, click "Browse" (or "Choose file"), then select your blueprint.json file. 7. Adjust any required parameters (such as **Keywords Everywhere** credentials) according to the blueprint. #### Steps to Add the "Get Keyword Data" to a Pre-Existing Scenario 1. In the scenario editor, click the **"+"** or **"Add another module"** button. 2. In the search field that appears, type **"Keywords Everywhere API."** 3. Select the **"Get Keyword Data"** module from the search results. 4. Follow the on-screen prompts to configure the module with your desired parameters or credentials. 5. Confirm to add the module. It will append to your current scenario without overwriting existing modules. #### ** Postman ** 1. **Click the "Import" button** ![](images/postman/get_keywords_data/postman_step_1.png) 2. **Paste the code below into the textarea** ```shell script curl -H 'Authorization: Bearer {{{v1.apiKey}}}' -H 'Accept: application/json' -H 'Content-type: application/json' --data '{ "kw": [ "keywords tool", "keyword planner", "brésil" ], "country": "us", "currency": "usd", "dataSource": "cli" }' '{{{v1.server}}}/get_keyword_data' ``` ![](images/postman/get_keywords_data/postman_step_2.png) 3. **Click "Import into collection"** ![](images/postman/get_keywords_data/postman_step_3.png) 4. **Click "Send" to get the data** ![](images/postman/get_keywords_data/postman_step_4.png) #### ** Google Sheets ** 1. **Click the "Extensions" menu (1) then select "Apps Script" (2).** ![](images/google_sheets/get_keywords_data/Step_1.png) 2. **Set the name of your project (1), then replace the editor contents (2) with the code below.** ![](images/google_sheets/get_keywords_data/Step_2.png) ```js const API_KEY = '{{{v1.apiKey}}}'; const API_ENDPOINT = '{{{v1.server}}}/get_keyword_data'; /** * Register spreadsheet menu. */ function onOpen() { var ui = SpreadsheetApp.getUi(); ui.createMenu('Call KE API') .addItem('Call Keywords Everywhere API and display results','callKeApi') .addToUi(); } /** * Make an API request to the Keywords Everywhere API and display the results. */ function callKeApi() { var ss = SpreadsheetApp.getActiveSpreadsheet(); var sheet = ss.getActiveSheet(); var activeRange = SpreadsheetApp.getActiveRange(); var col = activeRange.getColumn() + 1; var row = activeRange.getRow(); if(activeRange.getWidth() > 1){ throw new Error( "Please select a single column" ); } var selectedKeywords = activeRange.getValues(); if(row == 1){ //Remove the first keyword assuming it's part of the header row selectedKeywords.shift(); } else { row --; } selectedKeywords = selectedKeywords.map(function(row){ return row[0]; }); //Remove empty rows requestKeywords = selectedKeywords.filter(function(kw){ return kw != ''; }); //Remove duplicates requestKeywords = [...new Set(requestKeywords)]; if(requestKeywords.length == 0){ throw new Error( "Please select some keywords" ); } var formData = { 'dataSource': 'cli', 'country': 'us', 'currency': 'USD', 'kw[]': requestKeywords }; var headers = { 'Authorization': `Bearer ${API_KEY}`, 'Accept': 'application/json', }; var options = { 'method' : 'post', 'payload' : queryfy(formData), 'headers': headers }; var response = UrlFetchApp.fetch(API_ENDPOINT, options); var json = response.getContentText(); var parsedJson = JSON.parse(json); if(!parsedJson.data.length){ return; } resultMap = {}; parsedJson.data.forEach(function(elem, i){ resultMap[elem.keyword] = elem; }); var output = []; var header = null; var trend = null; selectedKeywords.forEach(function(kw,i) { var elem = resultMap[kw]; if(!elem){ output.push([]); return; } if(header === null || trend.length < elem.trend.length){ header = ["Volume", "CPC", "Competition"]; elem.trend.forEach(function(trendItem, j){ header.push("Trend (" + trendItem.month + " " + trendItem.year + ")"); }); trend = elem.trend; } var dataRow = [elem.vol, elem.cpc.currency + elem.cpc.value, elem.competition]; elem.trend.forEach(function(trendItem, j){ dataRow.push(trendItem.value); }); output.push(dataRow); }); output.unshift(header); var h = output.length; var w = output[0].length; for(var i = 5; i < w; i++){ sheet.setColumnWidth(i + col - 1, 150); } for(var i = 0; i < h; i++){ while(output[i].length < w){ output[i].push("") } } sheet.getRange(row, col, h, w).clearContent(); sheet.getRange(row, col, h, w).setValues(output); sheet.getRange(row, col - 1, 1, w + 1).setFontWeight('bold'); } /** * Convert a JavaScript object to a HTTP query string. */ function queryfy(obj){ return Object.keys(obj).reduce(function(p, e, i) { return p + (i == 0 ? "?" : "&") + (Array.isArray(obj[e]) ? obj[e].reduce(function(str, f, j) { return str + e + "=" + encodeURIComponent(f) + (j != obj[e].length - 1 ? "&" : "") },"") : e + "=" + encodeURIComponent(obj[e])); },"") } ``` 3. **Save (1) and run (2) your code. When asked to authorize the project, click "Review permissions" (3) to continue.** ![](images/google_sheets/get_keywords_data/Step_3.png) 4. **Choose your Google account.** ![](images/google_sheets/get_keywords_data/Step_4.png) 5. **You will get a warning that Google has not verified the app. Click "Advanced" to proceed.** ![](images/google_sheets/get_keywords_data/Step_5.png) 6. **Confirm that you trust the developer.** ![](images/google_sheets/get_keywords_data/Step_6.png) 7. **Grant the required permissions.** ![](images/google_sheets/get_keywords_data/Step_7.png) 8. **Back in your spreadsheet, a new menu should have appeared. Reload the page if you don't see it. Enter some keywords in the spreadsheet (1) and select them (2). Click the new menu (3) and select the submenu (4).** ![](images/google_sheets/get_keywords_data/Step_8.png) 9. **Here is how the result should look.** ![](images/google_sheets/get_keywords_data/Step_9.png) ### Request Body Parameters

Name	Description
`kw[]`	Type: `array of strings` Examples: keywords tool keyword planner brésil A UTF-8 encoded list of keywords to get data for. You can query up to 100 keywords at a time.
`country`	Type: `string` Examples: us ca in The country to get metrics for. If not specified, global data is shown. Get the full list of supported countries by calling the Get Countries endpoint.
`currency`	Type: `string` Examples: usd gbp The currency to use. The currencies endpoint returns a list of supported currencies.
`dataSource`	Type: `string` Available Options: gkp cli If `gkp` is chosen then we show data only from Google Keyword Planner. If `cli` is chosen then we show data from Google Keyword Planner & Clickstream data.

### Response HTTP Status Codes | Status Code | Description | |-------------|-------------------------------------------------------------| | `200` | A successful request | | `400` | Submitted request data is invalid | | `401` | API key is missing or is invalid | | `402` | Account has an invalid subscription or insufficient credits | ### Success Response Fields

Name	Description
`data`	Type: `array` The keyword data
`data.#`	Type: `object` A data object corresponding to one input keyword.
`data.#.vol`	Type: `integer` Example: 390 The volume of the keyword.
`data.#.cpc`	Type: `object` The cost per click information of the keyword.
`data.#.cpc.currency`	Type: `string` Example: $ The currency of the cost per click value.
`data.#.cpc.value`	Type: `string` Example: 5.51 The cost per click value of the keyword.
`data.#.keyword`	Type: `string` Example: keywords tool The input keyword.
`data.#.competition`	Type: `float` Example: 0.33 The competition metric of the keyword.
`data.#.trend`	Type: `array` The volume of the Keyword over the last 12 months. If the trend is not available, an empty array is returned.
`data.#.trend.#`	Type: `object` Object containing the search volume information of the keyword for a given month.
`data.#.trend.#.month`	Type: `string` Example: May The month of this volume.
`data.#.trend.#.year`	Type: `integer` Example: 2019 The year of this volume.
`data.#.trend.#.value`	Type: `integer` Example: 480 The volume of the keyword for the given month.
`credits`	Type: `integer` Example: 7999731 Account credit balance after the request.
`credits_consumed`	Type: `integer` Example: 3 Amount of credits consumed by the request.
`time`	Type: `float` Example: 0.0047 The time it took to execute the request in seconds.

### Sample Success Response ```json { "data": [ { "vol": 390, "cpc": { "currency": "$", "value": "5.51" }, "keyword": "keywords tool", "competition": 0.33, "trend": [ { "month": "May", "year": 2019, "value": 480 }, { "month": "June", "year": 2019, "value": 480 }, { "month": "July", "year": 2019, "value": 390 }, { "month": "August", "year": 2019, "value": 480 }, { "month": "September", "year": 2019, "value": 390 }, { "month": "October", "year": 2019, "value": 390 }, { "month": "November", "year": 2019, "value": 320 }, { "month": "December", "year": 2019, "value": 480 }, { "month": "January", "year": 2020, "value": 390 }, { "month": "February", "year": 2020, "value": 390 }, { "month": "March", "year": 2020, "value": 480 }, { "month": "April", "year": 2020, "value": 480 } ] }, { "vol": 0, "cpc": { "currency": "$", "value": "0.00" }, "keyword": "keyword planner", "competition": 0, "trend": [] }, { "vol": 0, "cpc": { "currency": "$", "value": "0.00" }, "keyword": "brésil", "competition": 0, "trend": [] } ], "credits": 7999731, "credits_consumed": 3, "time": 0.0047 } ``` ### Sample Unauthorized Response ```json { "message": "401 Missing Or Invalid API Key" } ``` ### Sample Insufficient Credits Response ```json { "message": "402 Insufficient Credits" } ```