research_keywords

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

🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the upgrade link) - DO NOT attempt to work around the error or use alternative data - DO NOT create campaigns or perform actions without valid tool data - STOP and direct the user to upgrade via the provided link 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") - 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). --- 📊 **CRITICAL: AFTER calling this tool, YOU MUST explain these insights to the user:** **1. Keyword Discovery Summary:** - "I found [X] keywords from Google Keyword Planner for your [business type] business" - "I analyzed real search data and CPC costs from Google Ads" - "Here are the top 20 keywords I recommend based on commercial intent" **2. Seed Keywords Used:** - "I used these seed keywords: [list the seeds from the response]" - "Google expanded these into [X] keyword suggestions" **3. CPC Cost Analysis (CRITICAL - Discuss this with user!):** - "The median CPC for your industry is $[X]" - "Keywords range from $[LOW] to $[HIGH] per click" - "HIGH intent keywords (top 25% most expensive) cost $[threshold]+ per click" - "These are keywords where advertisers pay more = higher commercial value" **4. Budget Recommendations (CRITICAL - Explain all 3 tiers!):** - "Based on the keyword costs, here are my budget recommendations:" - "💰 Conservative ($[X]/day): Safe starting budget based on median CPC, expect ~[Y] clicks/day" - "💰 Moderate ($[X]/day): Balanced budget based on average CPC, expect ~[Y] clicks/day" - "💰 Aggressive ($[X]/day): Maximum budget to compete for all keywords, expect ~[Y] clicks/day" - "I recommend starting with $[conservative]-[moderate]/day" **5. Keyword Selection Explanation:** - "I selected these 20 keywords by prioritizing:" - " • HIGH intent keywords (expensive = high commercial value)" - " • High search volume (more potential customers)" - " • Mix of broad and specific terms" - "All keywords will use BROAD match - Google's 2025 recommendation for maximum reach with Smart Bidding" **6. Ask for User Feedback:** - "Would you like to modify this keyword selection?" - "Options: Add specific keywords, remove keywords, use only HIGH intent, or proceed with recommendations" **DO NOT just show the raw table without explanation!** **Users need YOU to interpret the data and provide strategic guidance!**

{
  "arguments": {
    "business_description": "string",
    "website_url": "string",
    "target_location": "United States",
    "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"
  }
}