v2.0
Swagger UI Get Started

Keyword Data Reference

Get search volume, cost-per-click (CPC), competition metrics, and trend data for any keyword across different locations and languages.

Endpoints Overview

Endpoint Method Description
/api/v1/keyword-sv POST Create keyword search volume task (async)
/api/v1/keyword-sv/{task_id} GET Retrieve task results

Create Search Volume Task

POST /api/v1/keyword-sv

Create a task to retrieve search volume metrics for one or more keywords. Submit an array of keyword objects, each specifying the keyword and location.

Request Body

Array of keyword request objects:

Parameter Type Required Description
key string Required The keyword to analyze
loc_id integer Required Google Ads location code (e.g., 2840 for US)
postback_url string Optional Webhook URL for result delivery

Example Request

curl -X POST "https://engine.v2.serpwatch.io/api/v1/keyword-sv" \
  -H "Authorization: Bearer $SERPWATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"key": "project management software", "loc_id": 2840},
    {"key": "task management app", "loc_id": 2840},
    {"key": "team collaboration tools", "loc_id": 2840}
  ]'
import requests
import os

response = requests.post(
    "https://engine.v2.serpwatch.io/api/v1/keyword-sv",
    headers={
        "Authorization": f"Bearer {os.environ['SERPWATCH_API_KEY']}",
        "Content-Type": "application/json"
    },
    json=[
        {"key": "project management software", "loc_id": 2840},
        {"key": "task management app", "loc_id": 2840},
        {"key": "team collaboration tools", "loc_id": 2840}
    ]
)

tasks = response.json()
for task in tasks:
    print(f"Task ID: {task['id']} - {task['key']}")
const response = await fetch(
  "https://engine.v2.serpwatch.io/api/v1/keyword-sv",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SERPWATCH_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {key: "project management software", loc_id: 2840},
      {key: "task management app", loc_id: 2840},
      {key: "team collaboration tools", loc_id: 2840}
    ])
  }
);

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

Response (Tasks Created)

[
  {
    "id": 1166085302613024768,
    "user_id": 1134894642391789569,
    "status": "awaiting",
    "key": "project management software",
    "loc_id": 2840,
    "postback_url": null,
    "result": [],
    "created_at": 1769712401,
    "ttl": 1769798801
  },
  {
    "id": 1166085302613024769,
    "user_id": 1134894642391789569,
    "status": "awaiting",
    "key": "task management app",
    "loc_id": 2840,
    "postback_url": null,
    "result": [],
    "created_at": 1769712401,
    "ttl": 1769798801
  }
]

Get Task Results

GET /api/v1/keyword-sv/{task_id}

Retrieve the results of a keyword search volume task.

Response Example (Completed)

{
  "id": 1166085302613024768,
  "user_id": 1134894642391789569,
  "status": "success",
  "key": "project management software",
  "loc_id": 2840,
  "postback_url": null,
  "result": [
    {
      "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},
          {"year": 2025, "month": "DECEMBER", "monthly_searches": 71000}
        ]
      }
    }
  ],
  "created_at": 1769712401,
  "succeed_at": 1769712450,
  "ttl": 1769798801
}

Response Schema

Task Object

Field Type Description
id integer Unique task identifier
status string Task status: awaiting, success, or error
key string The keyword analyzed
loc_id integer Location code used
result array Array of keyword metrics (when completed)
created_at integer Unix timestamp of task creation
ttl integer Unix timestamp when task expires

Result Metrics

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

About Competition

The competition metric reflects advertiser competition in Google Ads, not organic SEO difficulty. High CPC and competition typically indicate commercial intent keywords with higher conversion potential.

Best Practices

Optimize Requests

  • Batch keywords - Submit up to 100 keywords per request for efficiency
  • Use async for bulk - Use the async endpoint for large keyword lists
  • Cache results - Keyword metrics change slowly; cache for 24-48 hours
  • Request trends selectively - Only include monthly_searches when needed

Interpret Metrics

  • Volume is estimated - Search volume is a monthly average, not exact count
  • CPC varies - Actual ad costs depend on Quality Score and bidding
  • Seasonality matters - Check monthly trends for seasonal keywords
  • Location affects data - Metrics vary significantly by location

Keyword Research

Generate keyword ideas and discover new opportunities.

Research Workflow

Complete keyword research workflow guide.

Batch Processing

Process large keyword lists efficiently.