SEO Keyword Research

Documentation Index

Fetch the complete documentation index at: https://aisa.one/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Install

aisa skills install seo-keyword-research

​

What can agents do with it?

​

Requirements

export AISA_API_KEY="your-aisa-api-key"

• Data APIs: https://api.aisa.one/apis/v1/...
• LLM gateway: https://api.aisa.one/v1/chat/completions

​

Compatibility

​

Quick Start

export AISA_API_KEY="your-aisa-api-key"

python3 {baseDir}/scripts/site_crawler.py \
  https://example.com \
  --max-pages 12 \
  --out site-profile.json

python3 {baseDir}/scripts/aisa_client.py data \
  /apis/v1/dataforseo/dataforseo_labs/google/keyword_suggestions/live \
  payload.json \
  --out keyword-suggestions.json

​

When to Use

• “Find SEO keywords for this site.”
• “Build a keyword strategy for my SaaS.”
• “Research keywords for this product category.”
• “Find keyword gaps between us and competitors.”
• “Cluster these keywords by search intent.”
• “Pick the best SEO content topics for next month.”
• “Create a keyword map for these landing pages.”

​

Core Workflow

​

1. Define the research scope

• Target domain or URL
• Seed topics, products, services, or categories
• Target country, language, and search engine
• Competitors, if provided
• Business goal: traffic, leads, sales, awareness, local visibility, or content planning
• Constraints: brand terms only, non-brand terms only, blog topics, landing pages, commercial pages, or programmatic pages

​

2. Crawl the website before keyword research

python3 {baseDir}/scripts/site_crawler.py \
  https://example.com \
  --max-pages 12 \
  --out site-profile.json

• Homepage
• Product, feature, pricing, docs, integrations, use case, comparison, blog, and about pages
• Sitemap URLs when available
• Navigation labels and internal links
• Page titles, meta descriptions, headings, schema hints, and visible copy

• Product category
• Main features and capabilities
• Target audience and buyer roles
• Use cases and jobs to be done
• Integrations, platforms, APIs, or supported tools
• Pricing model or conversion goal, if visible
• Competitors, alternatives, and category language mentioned on the site
• Existing content themes and gaps

• /apis/v1/dataforseo/on_page/content_parsing/live
• /apis/v1/dataforseo/on_page/task_post
• /apis/v1/dataforseo/on_page/pages
• /apis/v1/dataforseo/on_page/raw_html
• /apis/v1/dataforseo/on_page/summary/{id}

​

3. Convert the site profile into seed topics

• Product category terms
• Feature and capability terms
• Use case terms
• Integration and platform terms
• Pain points and problem terms
• Competitor and alternative terms
• Buyer role terms
• Transactional modifiers: pricing, alternative, best, tool, API, software, platform, comparison
• Informational modifiers: what is, how to, guide, examples, tutorial, checklist

​

4. Build the initial keyword universe

1. Crawl-derived seed expansion:
   • /apis/v1/dataforseo/dataforseo_labs/google/keyword_suggestions/live
   • /apis/v1/dataforseo/dataforseo_labs/google/keyword_ideas/live
   • /apis/v1/dataforseo/dataforseo_labs/google/related_keywords/live
   • /apis/v1/dataforseo/keywords_data/google_ads/keywords_for_keywords/live
2. Site-derived validation, after seed expansion:
   • /apis/v1/dataforseo/dataforseo_labs/google/keywords_for_site/live
   • /apis/v1/dataforseo/keywords_data/google_ads/keywords_for_site/live
3. Demand and trend checks:
   • /apis/v1/dataforseo/keywords_data/google_ads/search_volume/live
   • /apis/v1/dataforseo/keywords_data/clickstream_data/global_search_volume/live
   • /apis/v1/dataforseo/keywords_data/dataforseo_trends/explore/live
4. Difficulty and intent:
   • /apis/v1/dataforseo/dataforseo_labs/google/bulk_keyword_difficulty/live
   • /apis/v1/dataforseo/dataforseo_labs/google/search_intent/live
   • /apis/v1/dataforseo/dataforseo_labs/google/keyword_overview/live

​

5. Expand through competitors and SERPs

• Use /apis/v1/dataforseo/dataforseo_labs/google/competitors_domain/live
• Use /apis/v1/dataforseo/dataforseo_labs/google/domain_intersection/live
• Use /apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live
• Use /apis/v1/dataforseo/dataforseo_labs/google/serp_competitors/live
• Use /apis/v1/dataforseo/dataforseo_labs/google/relevant_pages/live

• /apis/v1/dataforseo/serp/google/organic/live/advanced
• /apis/v1/dataforseo/serp/ai_summary
• /apis/v1/dataforseo/serp/screenshot

​

6. Normalize and clean the data

• Lowercase only for deduplication; preserve original keyword casing in output.
• Merge close duplicates, singular/plural variants, and obvious spelling variants.
• Remove irrelevant brand, adult, navigational, and off-market terms unless requested.
• Mark keywords with missing volume, difficulty, or intent as incomplete rather than guessing numbers.
• Keep localized variants separate when intent differs by geography.

​

7. Cluster by intent and topic

• Parent topic
• Subtopic
• Search intent: informational, commercial, transactional, navigational, local, comparison, or troubleshooting
• Funnel stage: awareness, consideration, conversion, retention
• Best page type: blog post, comparison page, landing page, product page, category page, tool page, glossary page, local page, or programmatic template

​

8. Identify high-opportunity keywords

• Keyword difficulty is lower than 40
• Search volume is greater than 1000

• Why it fits the crawled site
• Which feature, use case, product category, or audience insight from the crawl supports it
• Why the metric profile is attractive
• What risk remains after reviewing the SERP

​

9. Score opportunities

• Demand: search volume, trend, and market size
• Relevance: fit with the domain, product, ICP, or page
• Intent value: likelihood to drive qualified traffic
• Ranking feasibility: inverse of difficulty plus SERP weakness
• Strategic value: supports product positioning, topical authority, or conversion

• High priority: strong demand, clear fit, feasible SERP, valuable intent
• Medium priority: useful but constrained by difficulty, ambiguity, or lower demand
• Low priority: weak fit, weak demand, or poor feasibility
• Validate first: interesting idea with incomplete data

​

10. Generate SERP-based page recommendations

• Landing page: SERP is dominated by product, software, API, platform, or tool pages.
• Feature page: SERP shows feature-specific vendor pages, docs, or tool capability pages.
• Comparison page: query includes vs, alternative, competitor, best, or SERP contains comparison lists and review pages.
• Blog article or guide: SERP is dominated by explainers, tutorials, how-to articles, or People Also Ask.
• Pricing page: query includes pricing, cost, cheap, free, plan, or SERP contains pricing pages.
• Documentation page: SERP contains API references, SDK docs, GitHub repos, or developer guides.
• Programmatic page: the pattern can be repeated across locations, integrations, categories, competitors, templates, or use cases.

​

11. Produce the final deliverable

• Executive summary
• Research assumptions
• Crawled-site business profile
• Top keyword clusters
• Five representative keywords per cluster
• High-opportunity keywords where difficulty is lower than 40 and volume is greater than 1000
• Why those keywords are opportunities
• Priority keyword shortlist
• Best content opportunities
• SERP-based page recommendations
• Recommended next pages, updates, or programmatic templates
• Data gaps and validation notes

​

AIsa LLM Usage

• Summarizing the crawled site into a product and business profile
• Generating justified seed topics from the crawl
• Classifying search intent
• Grouping keywords into clusters
• Summarizing SERP patterns
• Translating raw metrics into SEO decisions
• Drafting a keyword strategy report
• Turning keywords into page recommendations

curl -sS "https://api.aisa.one/v1/chat/completions" \
  -H "Authorization: Bearer $AISA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [
      {
        "role": "system",
        "content": "You are an SEO strategist. Use only provided metrics as facts. Mark unverified ideas clearly."
      },
      {
        "role": "user",
        "content": "Cluster these keyword rows by topic, search intent, and best page type."
      }
    ]
  }'

​

Helper Script

python3 {baseDir}/scripts/site_crawler.py \
  https://example.com \
  --max-pages 12 \
  --out site-profile.json

python3 {baseDir}/scripts/aisa_client.py data \
  /apis/v1/dataforseo/dataforseo_labs/google/keyword_suggestions/live \
  payload.json \
  --out keyword-suggestions.json

python3 {baseDir}/scripts/aisa_client.py chat \
  --model gpt-5-mini \
  --system system-prompt.txt \
  --prompt cluster-prompt.txt \
  --out clusters.md

​

Quality Rules

• When a website is provided, crawl the website before keyword research.
• Do not begin with brand keywords unless the user explicitly asks for brand SEO.
• Prefer the local crawler and live AIsa/DataForSEO data over manual browser scraping.
• Cite which endpoint groups were used.
• Separate facts from recommendations.
• Do not invent search volume, CPC, keyword difficulty, rank, or trend values.
• Use LLM output for interpretation, not as a substitute for keyword data.
• Every keyword cluster should show five representative keywords with available metrics.
• High-opportunity keywords must satisfy difficulty < 40 and search volume > 1000.
• SERP-based page recommendations must say whether the user should create a landing page, feature page, comparison page, pricing page, documentation page, programmatic page, or blog article, and why.
• Keep raw exports private if they contain customer domains, competitors, or internal strategy.
• Make the final answer actionable: the user should know which keywords to target, which page type to create, and why.

​

References

• references/aisa-api-map.md for endpoint groups and usage notes.
• references/report-template.md for the final keyword research report structure.

​

Get started

1. Sign up at aisa.one (new accounts start with $2 free credit).
2. Generate an API key from the console.
3. Set your key and install the skill:
   export AISA_API_KEY="your-key"
   aisa skills install seo-keyword-research
   
4. Start a new agent session so the runtime loads the updated skill instructions.

​

Related