This page explains how to use our Keyword Planner API to generate a keyword plan and fetch the results.
The common use-case for this API is to generate an intelligent, business-specific list of keyword suggestions for a small business.
All requests to our API should be authenticated. Our API is RESTful and communicates using JSON.
The keyword planner uses data collected by the audit as a starting point. At the moment you can only generate a keyword plan once an audit has already been generated for a business.
Trigger a new keyword plan
Method: POST
Request body should be JSON encoded, and can include the following fields:
Property | Definition | Required |
reportId | String – URL to analyze | Yes |
websiteUrl | String - Website domain of the business you want to generate a keyword plan for | No (defaults to website URL from the audit) |
products | Array of strings – Products and services that Insites should use when generating the keyword plan | No (by default AI will generate these from website content, but you can pass specific ones you want the AI to use) |
competitors | Array of Competitor objects - see below | No |
businessName | String – the name of the business you want to create a keyword plan for | No (defaults to the business name from the audit) |
countryCode | String – ISO 2 letter country code, e.g. GB, US | No (defaults to account country setting) |
Competitor object
Property | Definition | Required |
business_name | String - Business name of the competitor | No |
website_url | String - Website address of the competitor | No |
Example
curl "https://app.insites.com/api/v1/keyword-planner/submit" \
--header "api-key:[YOUR API KEY]" \
--header "Content-Type: application/json" \
--data '{
"websiteUrl": "easyitguys.com",
"products": [
"Computer Repair",
"IT Services",
"Tech Support",
"Computer IT"
],
"competitors": [
{
"business_name": "Randolph Communications",
"website_url": "rtmc.net"
}
],
"reportId": "ea7116cbc43a46ea037790cc5bb6cd8c50a77a51",
"businessName": "EasyITGuys - CyberSecurity, Compliance, and Managed IT Support",
"countryCode": "US"
}'
Expected response
{
"request_status": "success",
"keywordPlanId": "75df7d99-e705-4bdd-a4cb-eef2b3a15d52",
"status": "success"
}
All possible responses
Code | Reason |
201 | Keyword plan has been requested and is now running |
400 | Your request was un-processable |
402 | Insufficient feature credits to run keyword plan |
Fetch a keyword plan
Method: GET
The following parameter must be passed via GET:
Property | Definition | Required |
reportId | String – the report ID the keyword plan has been generated for | Yes |
Example
curl "https://app.insites.com/api/v1/keyword-planner/latest?reportId=ea7116cbc43a46ea037590ca5bb6cd8c50a77d51" \
--header "api-key:[YOUR API KEY]"
Expected response
{
"request_status": "success",
"keywordPlan": {
"id": "75df7d99-e705-4bdd-a4cb-eef2b3a15d52",
"status": "complete",
"report_id": "ea7116cbc43a46ea037590ca5bb6cd8c50a77d51",
"business_name": "EasyITGuys - CyberSecurity, Compliance, and Managed IT Support",
"domain": "easyitguys.com",
"products": [
"Computer Repair",
"IT Services",
"Tech Support",
"Computer IT"
],
"locations": null,
"competitors": [
{
"website_url": "rtmc.net",
"business_name": "Randolph Communications"
}
],
"created_at": "2025-06-11 10:20:10.856908",
"keywords": [
{
"id": 12343,
"keyword_plan_id": 199,
"keyword": "AI in data analytics",
"difficulty": null,
"volume": 5400,
"cpc": "20.39",
"relevance": "0",
"target": "service",
"source": "AI Suggestion",
"competition": "0.37",
"created_at": "2025-06-11 10:20:54"
},
{
"id": 12344,
"keyword_plan_id": 199,
"keyword": "AI integration in business",
"difficulty": null,
"volume": 140,
"cpc": "32.06",
"relevance": "0",
"target": "service",
"source": "AI Suggestion",
"competition": "0.11",
"created_at": "2025-06-11 10:20:54"
}
]
},
"status": "success"
}
All possible responses
Code | Reason |
200 | Keyword plan is completed |
201 | Keyword plan is still running |
204 | No keywords found |
400 | Your request was un-processable |
500 | Keyword plan generation failed |