Public API: Clustering
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/{order_id}/
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-d51d5d260fb5Authorization *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/{order_id}/
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 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.
Last updated