keyword-analysis

Keyword Analysis

Analyze keywords to get search volume, difficulty, CPC, intent, trends, and more. Each analysis costs 1 credit.

Prerequisite: Read ../thekeyword-setup/SKILL.md for auth, API base URL, geo config, and plan limits.

Before Analyzing

Always check credits first:

GET /api/v1/usage

If credits_used >= credits_limit, stop and inform the user. Do not attempt analysis without available credits.

Always confirm the target country. Ask the user if not specified. Include country in every analysis request.

Single Keyword Analysis

Costs 1 credit. Returns full metrics immediately.

POST /api/v1/keywords/analyze
Content-Type: application/json

{
  "keyword": "remote work tools",
  "country": "US"
}

Response includes:

• search_volume — Monthly search volume
• difficulty / difficulty_label — SEO difficulty (0-100, easy/moderate/hard/very_hard)
• cpc / cpc_currency — Cost per click in local currency
• competition / competition_level — Advertiser competition (0-1, low/medium/high)
• opportunity_score — Overall opportunity rating (0-100)
• intent — Search intent (informational, commercial, transactional, navigational)
• trend_direction — Rising, stable, or declining
• trend — 12-month volume trend (array, oldest first)
• signals — Market signals (Starter+ plan)
• forecast_volume_30d / forecast_volume_90d — Volume forecasts (Pro+ plan)

Batch Analysis

Analyzes multiple keywords asynchronously. Returns a job ID to poll. Each keyword costs 1 credit.

Plan limits on batch size:

• Free: Batch not available
• Starter: Up to 10 keywords per batch
• Pro: Up to 50 keywords per batch
• Ultra: Up to 100 keywords per batch

POST /api/v1/keywords/batch
Content-Type: application/json

{
  "keywords": ["remote work tools", "hybrid office software", "digital nomad gear"]
}

Response (HTTP 202):

{
  "object": "job",
  "id": "job_abc123",
  "status": "pending",
  "progress": { "completed": 0, "total": 3 }
}

Polling for Results

Poll the job endpoint until status is completed or failed:

GET /api/v1/jobs/{jobId}

Status transitions: pending -> processing -> completed | failed

Poll every 3-5 seconds. When completed, the result field contains all analyzed keywords.

If status is failed, check the error field and inform the user.

Workflow

Single keyword

1. GET /api/v1/usage — Check credits
2. Confirm country with user
3. POST /api/v1/keywords/analyze — Analyze
4. Present results: volume, difficulty, CPC, intent, trend

Batch keywords

1. GET /api/v1/usage — Check credits (need 1 per keyword)
2. Confirm country with user
3. Verify batch size fits plan limit
4. POST /api/v1/keywords/batch — Submit batch
5. GET /api/v1/jobs/{jobId} — Poll until complete
6. Present results summary: table of keywords with key metrics

Examples

User: "Analyze the keyword 'best crm software' for the US market"

1. Check credits: GET /api/v1/usage
2. Analyze: POST /api/v1/keywords/analyze with {"keyword": "best crm software", "country": "US"}
3. Present: volume, difficulty, CPC, intent, opportunity score

User: "Research these keywords for Portugal: crm software, crm tools, crm comparison"

1. Check credits: GET /api/v1/usage — need 3 credits
2. Batch: POST /api/v1/keywords/batch with {"keywords": ["crm software", "crm tools", "crm comparison"]}
3. Poll: GET /api/v1/jobs/{jobId} until complete
4. Present: comparison table sorted by volume

Library Batch Analysis

You can pick unanalyzed keywords from the user's library (keywords discovered as related results but not yet fully analyzed) and batch-analyze them. This combines the keyword-library and batch analysis workflows.

Workflow

1. GET /api/v1/usage — Check credits
2. GET /api/v1/keywords?status=known&sort=-search_volume&limit=20 — Fetch top unanalyzed keywords
3. Present the list to the user and let them confirm which to analyze
4. Extract the keyword field from each result
5. POST /api/v1/keywords/batch — Submit as batch with {"keywords": ["keyword1", "keyword2", ...]}
6. Poll GET /api/v1/jobs/{jobId} until complete

Available Filters for Unanalyzed Keywords

Use any filter from the keyword-library skill to narrow down which unanalyzed keywords to analyze:

GET /api/v1/keywords?status=known&sort=-search_volume&limit=10
GET /api/v1/keywords?status=known&sort=-cpc&difficulty_lte=30&limit=20
GET /api/v1/keywords?status=known&sort=-opportunity_score&search_volume_gte=1000&limit=15
GET /api/v1/keywords?status=known&intent=commercial&sort=-search_volume&limit=10

Example

User: "Analyze the top 10 highest-volume unanalyzed keywords"

1. Check credits: GET /api/v1/usage — need 10 credits
2. Fetch: GET /api/v1/keywords?status=known&sort=-search_volume&limit=10
3. Show user the preview list with volumes
4. On confirmation, extract keyword names and submit batch
5. Poll until complete, present results

Tips

• Keyword slugs are URL-safe: "remote work tools" becomes "remote-work-tools"
• After analysis, use the keyword-lookup skill to get detailed data including related keywords and SERP analysis
• Use the keyword-lists skill to organize analyzed keywords into groups
• Batch analysis is async — always poll the job, don't assume instant results
• Use status=known to find unanalyzed keywords discovered from related results

Related Skills

• thekeyword-setup — API authentication and configuration
• keyword-lookup — Deep-dive into a specific keyword
• keyword-library — Browse all analyzed keywords
• keyword-lists — Organize keywords into lists