research_keywords

POST https://api.adspirer.ai/api/v1/tools/research_keywords/execute

Research high-intent keywords using Google Keyword Planner API. ⚠️ IMPORTANT: This is a READ-ONLY tool. Safe to call multiple times. 🎯 **What This Tool Does:** - Researches keywords via Google Keyword Planner API - Returns keywords with real CPC data, search volume, and competition metrics - Groups keywords by commercial intent (HIGH/MEDIUM/LOW based on dynamic CPC thresholds) - Selects top 15-20 keywords optimized for conversions - Provides budget recommendations based on actual keyword costs **When to Use:** - BEFORE creating a Google Search campaign - When you need data-driven keyword insights - To understand keyword costs and search volume - To get budget recommendations **Parameters:** - business_description (required): What the business sells/offers - website_url (optional): Business website for better keyword suggestions - target_location (optional): Geographic target (default: "United States") - language (optional): 'de' / 'German' / '1001' — defaults to the language the account's campaigns target (auto-detected), falling back to English. For non-English seeds, location AND language should match (e.g. German seeds → target_location "Germany" + language auto/de). - seed_keywords (optional): 5-10 seed keywords (will auto-extract if not provided) - customer_id (optional): Google Ads account ID **Returns:** - Keyword table with dynamic CPC thresholds (adapts to any industry) - HIGH/MEDIUM/LOW intent grouping - Budget recommendations (Conservative/Moderate/Aggressive) - Top 15-20 recommended keywords for campaign **Execution time:** 3-8 seconds (calls live Google Ads API) 📊 **Example Usage:** 1. User: "I want to create a campaign for my plumbing business" 2. YOU call: research_keywords with business_description="Emergency plumbing services" 3. Tool returns: Keyword table with 100+ keywords, 20 recommended, budget suggestions 4. YOU show user: The keyword table and ask if they want modifications 5. User approves or requests changes 6. YOU call: create_search_campaign with approved keywords 💡 **Dynamic Thresholds:** This tool automatically adapts CPC thresholds to any industry: - Plumbing: HIGH ≥$6, MEDIUM $3-6, LOW <$3 - Legal: HIGH ≥$95, MEDIUM $45-95, LOW <$45 - E-commerce: HIGH ≥$2, MEDIUM $0.50-2, LOW <$0.50 All keywords returned will use **BROAD match** (Google's 2025 recommendation with Smart Bidding).

{
  "arguments": {
    "business_description": "string",
    "website_url": "string",
    "target_location": "United States",
    "language": "string",
    "seed_keywords": [
      "string"
    ],
    "customer_id": "string"
  }
}

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for research_keywords)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "research_keywords"
}

{
  "success": false,
  "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n  - Acme Holdings (ad_account_id=\"act_123456789\")\n  - Acme EU (ad_account_id=\"act_987654321\")",
  "is_error": true,
  "tool": "research_keywords"
}

{
  "success": false,
  "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
  "is_error": true,
  "tool": "research_keywords",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}