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"