Keyword Research

{
  "status": "success",
  "result": [
    { "keyword": "project management software" },
    { "keyword": "project management tools" },
    { "keyword": "project management certification" },
    { "keyword": "project management jobs" },
    { "keyword": "project management app" },
    { "keyword": "project management methodologies" },
    { "keyword": "project management courses" },
    { "keyword": "project management skills" }
  ]
}

#!/usr/bin/env python3
"""
SerpWatch Keyword Research Workflow
Generates a comprehensive keyword list from a seed topic
"""

import os
import time
import requests

API_KEY = os.environ.get("SERPWATCH_API_KEY")
BASE_URL = "https://engine.v2.serpwatch.io"

def get_suggestions(keyword, location_code=2840):
    """Get autocomplete suggestions for a keyword."""
    response = requests.post(
        f"{BASE_URL}/api/v1/keyword-research/suggest/live",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "keyword": keyword,
            "location_code": location_code,
            "language_code": "en"
        }
    )
    response.raise_for_status()
    return [s["keyword"] for s in response.json().get("result", [])]

def get_keyword_ideas(keywords, location_code=2840):
    """Get keyword ideas (async workflow)."""
    # Submit request
    response = requests.post(
        f"{BASE_URL}/api/v1/keyword-research/ideas",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "keywords": keywords,
            "location_code": location_code,
            "language_code": "en",
            "include_seed_keyword": True
        }
    )
    response.raise_for_status()
    task_id = response.json()["id"]

    # Poll for results
    for _ in range(40):  # Max 2 minutes
        result = requests.get(
            f"{BASE_URL}/api/v1/keyword-research/ideas/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"}
        ).json()

        if result["status"] in ["success", "completed"]:
            return result.get("result", {}).get("keywords", [])
        elif result["status"] == "error":
            raise Exception(f"Task failed: {result.get('error_message')}")

        time.sleep(3)

    raise TimeoutError("Request timed out")

def research_topic(seed_keyword):
    """Complete keyword research workflow for a topic."""
    print(f"\nResearching: {seed_keyword}")
    print("=" * 50)

    all_keywords = set()

    # Step 1: Get autocomplete suggestions
    print("\n1. Getting autocomplete suggestions...")
    suggestions = get_suggestions(seed_keyword)
    all_keywords.update(suggestions)
    print(f"   Found {len(suggestions)} suggestions")

    # Step 2: Get keyword ideas for seed + top suggestions
    print("\n2. Generating keyword ideas...")
    seed_list = [seed_keyword] + suggestions[:3]  # Use top 3 suggestions
    ideas = get_keyword_ideas(seed_list)
    print(f"   Found {len(ideas)} keyword ideas")

    # Step 3: Compile and sort results
    print("\n3. Compiling results...")
    keywords_with_data = []

    for idea in ideas:
        kw = idea.get("keyword", "")
        volume = idea.get("search_volume", 0)
        all_keywords.add(kw)
        keywords_with_data.append({
            "keyword": kw,
            "volume": volume
        })

    # Sort by volume
    keywords_with_data.sort(key=lambda x: x["volume"] or 0, reverse=True)

    # Display top 20
    print(f"\nTop Keywords by Volume:")
    print("-" * 50)
    for kw in keywords_with_data[:20]:
        vol = kw["volume"] if kw["volume"] else "N/A"
        print(f"  {kw['keyword']}: {vol}")

    print(f"\nTotal unique keywords found: {len(all_keywords)}")
    return keywords_with_data

if __name__ == "__main__":
    results = research_topic("project management software")
    # Export to CSV, database, etc.