Skip to main content

Keyword Planner API

The keyword planning API combines competitor intelligence, scraping and AI to generate a keyword plan for a small business

Andrew Waite avatar
Written by Andrew Waite
Updated yesterday

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

Did this answer your question?