v2.0
Swagger UI Get Started

Keyword Research Reference

Generate keyword ideas, get autocomplete suggestions, and discover trending searches to expand your keyword strategy.

Endpoints Overview

Endpoint Method Type Description
/api/v1/keyword-research/ideas POST Async Generate keyword ideas from seeds
/api/v1/keyword-research/ideas/{task_id} GET - Retrieve ideas task results
/api/v1/keyword-research/suggest/live POST Sync Get autocomplete suggestions
/api/v1/keyword-research/trends/live POST Sync Get trending searches

Keyword Ideas

POST /api/v1/keyword-research/ideas

Generate related keyword ideas from one or more seed keywords. This is an async endpoint that returns a task ID.

Request Parameters

Parameter Type Required Description
keywords array Required Seed keywords to generate ideas from (max 10)
location_code integer Optional Google Ads location code. Default: 2840 (US)
language_code string Optional Language code. Default: "en"
include_seed_keyword boolean Optional Include seeds in results. Default: true
postback_url string Optional Webhook URL for result delivery

Example Request

curl -X POST "https://engine.v2.serpwatch.io/api/v1/keyword-research/ideas" \
  -H "Authorization: Bearer $SERPWATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["project management", "task tracking"],
    "location_code": 2840,
    "language_code": "en",
    "include_seed_keyword": true
  }'
import requests
import os

response = requests.post(
    "https://engine.v2.serpwatch.io/api/v1/keyword-research/ideas",
    headers={
        "Authorization": f"Bearer {os.environ['SERPWATCH_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "keywords": ["project management", "task tracking"],
        "location_code": 2840,
        "language_code": "en",
        "include_seed_keyword": True
    }
)

task = response.json()
print(f"Task ID: {task['id']}")
const response = await fetch(
  "https://engine.v2.serpwatch.io/api/v1/keyword-research/ideas",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SERPWATCH_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      keywords: ["project management", "task tracking"],
      location_code: 2840,
      language_code: "en",
      include_seed_keyword: true
    })
  }
);

const task = await response.json();
console.log(`Task ID: ${task.id}`);

Response (Task Created)

{
  "id": 1166085302613024768,
  "status": "awaiting",
  "keywords": ["project management", "task tracking"],
  "location_code": 2840,
  "language_code": "en",
  "created_at": 1769712401,
  "ttl": 1769798801
}

Get Ideas Results

GET /api/v1/keyword-research/ideas/{task_id}

Retrieve the results of a keyword ideas task.

Response (Completed)

{
  "results": [
    {
      "text": "project management software",
      "keyword_idea_metrics": {
        "competition": "MEDIUM",
        "avg_monthly_searches": 74000,
        "competition_index": 44,
        "low_top_of_page_bid_micros": 2600844,
        "high_top_of_page_bid_micros": 19720000,
        "monthly_search_volumes": [
          {"year": 2026, "month": "JANUARY", "monthly_searches": 74000}
        ]
      },
      "keyword_annotations": {"concepts": []}
    },
    {
      "text": "project management tools",
      "keyword_idea_metrics": {
        "competition": "MEDIUM",
        "avg_monthly_searches": 49500,
        "competition_index": 38,
        "low_top_of_page_bid_micros": 1850000,
        "high_top_of_page_bid_micros": 15200000,
        "monthly_search_volumes": [
          {"year": 2026, "month": "JANUARY", "monthly_searches": 49500}
        ]
      },
      "keyword_annotations": {"concepts": []}
    },
    {
      "text": "task management software",
      "keyword_idea_metrics": {
        "competition": "MEDIUM",
        "avg_monthly_searches": 22000,
        "competition_index": 35,
        "low_top_of_page_bid_micros": 1200000,
        "high_top_of_page_bid_micros": 12500000,
        "monthly_search_volumes": [
          {"year": 2026, "month": "JANUARY", "monthly_searches": 22000}
        ]
      },
      "keyword_annotations": {"concepts": []}
    }
  ]
}

Autocomplete Suggestions

POST /api/v1/keyword-research/suggest/live

Get Google autocomplete suggestions for a keyword. Returns results synchronously (no polling required).

Request Parameters

Parameter Type Required Description
keyword string Required The seed keyword for suggestions
location_name string Required Geographic location (e.g., "United States")
iso_code string Required Country ISO code (e.g., "US")
location_code integer Optional Google Ads location code. Default: 2840 (US)
language_code string Optional Language code. Default: "en"

Example Request

curl -X POST "https://engine.v2.serpwatch.io/api/v1/keyword-research/suggest/live" \
  -H "Authorization: Bearer $SERPWATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "project management",
    "location_name": "United States",
    "iso_code": "US",
    "location_code": 2840,
    "language_code": "en"
  }'

Response

{
  "suggestions": [
    "project management",
    "project management certification",
    "project management tools",
    "project management course",
    "project management institute",
    "project management software",
    "project management professional",
    "project management office",
    "project management triangle",
    "project management jobs"
  ]
}

Coming Soon

The trends endpoint is currently under maintenance and temporarily unavailable. Check back for updates.

POST /api/v1/keyword-research/trends/live

Get currently trending searches for a location. Returns results synchronously.

Request Parameters

Parameter Type Required Description
location_code integer Optional Google Ads location code. Default: 2840 (US)
language_code string Optional Language code. Default: "en"

Example Request

curl -X POST "https://engine.v2.serpwatch.io/api/v1/keyword-research/trends/live" \
  -H "Authorization: Bearer $SERPWATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "location_code": 2840,
    "language_code": "en"
  }'

Response

{
  "status": "success",
  "location_code": 2840,
  "result": [
    {
      "title": "Super Bowl 2026",
      "traffic": "2M+",
      "related_queries": ["super bowl halftime show", "super bowl score"]
    },
    {
      "title": "Stock Market Today",
      "traffic": "500K+",
      "related_queries": ["dow jones", "nasdaq", "s&p 500"]
    },
    {
      "title": "Weather Tomorrow",
      "traffic": "200K+",
      "related_queries": ["weather forecast", "hourly weather"]
    }
  ]
}

Response Schema

Keyword Idea Object

Field Type Description
text string The generated keyword
keyword_idea_metrics object Search metrics for the keyword
keyword_annotations object Additional keyword metadata

Keyword Idea Metrics

Field Type Description
avg_monthly_searches integer Average monthly search volume
competition string Competition level: LOW, MEDIUM, or HIGH
competition_index integer Competition index (0-100)
low_top_of_page_bid_micros integer Low CPC estimate in micros (divide by 1,000,000 for USD)
high_top_of_page_bid_micros integer High CPC estimate in micros (divide by 1,000,000 for USD)
monthly_search_volumes array Historical monthly search volume data

Suggestions Response

The suggestions endpoint returns an array of keyword strings:

Field Type Description
suggestions array Array of autocomplete suggestion strings

Trend Object

Field Type Description
title string The trending topic
traffic string Approximate search traffic (e.g., "500K+")
related_queries array Related search queries

Combine Endpoints

For comprehensive keyword research, start with autocomplete suggestions, then use the ideas endpoint with top suggestions as seeds. Finally, use the keyword data endpoint to get metrics for your final list.

Research Workflow

Complete keyword research workflow with examples.

Keyword Data

Get search volume and metrics for keywords.

Credits & Billing

Understand credit costs for keyword endpoints.