Public API: Clustering
On this page, you'll find examples on how to use the Keyword Insights Public API for clustering projects.
Clustering: Intent Only
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: 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).
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.
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".
For a full clustering order, you need to define:
"insights": [
"cluster",
"rank",
"context"
],
For an intent only orders you only pass context:
"insights": [
"context"
],
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"
Last updated