Skip to main content
On this page, you’ll find examples on how to use the Keyword Insights Public API for clustering projects.

​
Clustering Parameters

project_name*: Name of the project for easier identification in the keywordinsights.ai UI. keywords*: List of keywords. [“keyword 1”, “keyword 2”, “keyword 3”] search_volumes*: List of search volumes. [213, 1561, 616] Or any data really doesn’t matter, as that is always provided by the user language*: Language code to use for SERP results scraping. location*: Location name to use for SERP results scraping. insights*: The types of insights to perform within the order (cluster required). For a full clustering order, you need to define: 
"insights": [
    "cluster",
    "rank",
    "context"
  ],
While for intent-only orders, you only pass context: 
"insights": [
    "context"
  ],
clustering_method: The method to be used for grouping the keywords into clusters. grouping_accuracy: Parameter used with clustering method “volume”. Describes minimum number of SERP URLs in common between every keyword in cluster and cluster lead keyword. hub_creation_method: Describes the level of similarity of keywords within the cluster for the HUB algorithm. device: The device for the SERP scraping. mobile_type: The type of mobile device. Applied if device=mobile. tablet_type: The type of tablet device. Applied if device=tablet. url: The url for ranking. Required if “rank” is specified within the “insights” property.

​
Clustering: Intent Only

POST /api/keywords-insights/order/ In order to create a clustering order for intent only, you have to specify all clustering parameters, exactly as for a full clustering order.

​
Intent Only: Example Payload

The difference to a full clustering order is the contents of the insights array inside the payload. You only need to pass “context” vs “context”, “rank” and “cluster”. A full example of an intent only order below: 
{
  "clustering_method": "volume",
  "device": "desktop",
  "grouping_accuracy": 4,
  "hub_creation_method": "medium",
  "insights": [
    "context"
  ],
  "keywords": [
    "tesla",
    "tesla s",
    "tesla 3",
    "tesla x"
  ],
  "language": "en",
  "location": "United States",
  "mobile_type": "android",
  "project_name": "project_name",
  "search_volumes": [
    213,
    1561,
    616,
    777
  ],
  "tablet_type": "android",
  "url": "https://tesla.com/"
}

​
Intent Only: Code Example Python

import os
from urllib.parse import urljoin

import requests

# See https://docs.keywordinsights.ai/api/public-api-documentation#how-to-authenticate-with-the-public-api-and-retrieve-a-bearer-token-email-and-password-approach
JWT_TOKEN = os.environ.get("JWT_TOKEN")
BASE_API = "https://api.keywordinsights.ai"

keywords = ["what was used before freon", "clean air act refrigerant regulations", "dielektrol capacitor"]

payload = {
    "clustering_method": "volume",
    "device": "desktop",
    "grouping_accuracy": 4,
    "hub_creation_method": "medium",
    "insights": ["context"],
    "keywords": keywords,
    "language": "en",
    "location": "United States",
    "project_name": "Intent only project",
    "search_volumes": len(keywords) * [0],
}

response = requests.post(
    urljoin(BASE_API, "/api/keywords-insights/order/"),
    headers={"Authorization": f"Bearer {JWT_TOKEN}"},
    json=payload,
)

print(response.json())  # Order will show in the dashboard under "Intent only project"

​
Retrieving Clustering results in XLSX: Code example python

GET /api/keywords-insights/order/xlsx// 
import os
from urllib.parse import urljoin

import requests

# See https://docs.keywordinsights.ai/api/public-api-documentation#how-to-authenticate-with-the-public-api-and-retrieve-a-bearer-token-email-and-password-approach
JWT_TOKEN = os.environ.get("JWT_TOKEN")
BASE_API = "https://api.keywordinsights.ai"


response = requests.get(
    urljoin(BASE_API, "/api/keywords-insights/order/xlsx/10ea9e67-4d45-4e77-9032-d85a29660225/"),
    headers={"Authorization": f"Bearer {JWT_TOKEN}"},
)

print(response.json()) # will print link to file download: blob:https://api.keywordinsights.ai/a7bdcfa7-b67e-44de-8602-d51d5d260fb5
ParameterDescription
Authorization *string(header)Bearer token
order_id *string(path)ID of the order to export

​
Retrieving Clustering results in JSON: Code example python

GET ​/api​/keywords-insights​/order​/json​/​/ 
import os
from urllib.parse import urljoin

import requests

# See https://docs.keywordinsights.ai/api/public-api-documentation#how-to-authenticate-with-the-public-api-and-retrieve-a-bearer-token-email-and-password-approach
JWT_TOKEN = os.environ.get("JWT_TOKEN")
BASE_API = "https://api.keywordinsights.ai"


response = requests.get(
    urljoin(BASE_API, "/api/keywords-insights/order/json/10ea9e67-4d45-4e77-9032-d85a29660225/?page_size=50&page_number=1&sort_by=search_volume&ascending=false"),
    headers={"Authorization": f"Bearer {JWT_TOKEN}"},
)

print(response.json()) # will print a json output of the first 50 clusters in the given project
Parameter NameDescription
Authorization *string(header)Bearer token
order_id *string(path)Order UUID (returned when the order was created)
page_sizeinteger(query)

Number of rows per page (max 1000)

Default value : 50

page_numberinteger(query)

Page number starting from 1

Default value : 1

sort_bystring(query)

Sort field (e.g. search_volume, keyword, cluster_id)

Default value : search_volume

ascendingboolean(query)

Sort direction. false = descending

Default value : false

—truefalse

filter_idstring(query)Filter ID. Can be obtained from the filters endpoint.