Keyword Difficulty
Keyword difficulty scores express the estimated relative competition for ranking organically on a search term, with higher values indicating greater difficulty. These keyword-level signals support prioritization, research-group segmentation, and comparison across a prepared term list.
Features
- Batch keyword inputEvaluate from 1 to 1,000 non-empty keywords in one task while applying the same selected market and language context to the batch.
- Normalized difficulty metricReturn each available keyword with metrics.keyword_difficulty, normally expressed on a 0–100 scale for direct comparison.
- Complete source contextPreserve the complete returned row in extra so clients can inspect additional source fields without treating them as a stable normalized schema.
Parameters
| Parameters | Required | Description |
|---|---|---|
keywords | Required | Required list of 1 to 1,000 non-empty keywords, with a maximum of 80 characters per item. |
location_code | Optional | Positive numeric search-market code. The Playground defaults to 2840 for the United States. |
location_name | Optional | Optional search-market name alternative to location_code. When filled, it takes precedence over location_code. |
language_code | Optional | Search-language code from 2 through 10 characters applied to the batch. The Playground defaults to en. |
language | Optional | Optional search-language name alternative to language_code. When filled, it takes precedence over language_code. |
results_limit | Optional | Optional result limit from 1 through 2,000. |
How to Use
Submit a bounded keyword list with code-based market settings, then read the available normalized scores from the completed asynchronous task.
- Prepare 1 to 1,000 non-empty keywords, each no longer than 80 characters.
- POST keywords with location_code and language_code to /v1/seo/keyword-difficulty, then save the returned task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
- Read data.results.items, then follow next_cursor while has_more is true.
curl -X POST "https://api.socq.ai/v1/seo/keyword-difficulty" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keywords":["keyword research","seo tools"],"location_code":2840,"language_code":"en"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueBest Use Cases
- Keyword list prioritization: Compare metrics.keyword_difficulty across a prepared term set to add a competition signal to editorial or research triage.
- Difficulty-band segmentation: Group returned scores into internally defined ranges to organize lower- and higher-difficulty keyword research queues.
- Market comparison: Run the same keyword list with controlled location_code and language_code values to compare estimated difficulty across search contexts.
Pro Tips
- Deduplicate keywords before submission so repeated terms do not consume repeated input-based charges.
- Keep location_code and language_code unchanged when comparing scores within one research set.
- Omit results_limit because this batch is controlled by the keywords array rather than a returned-result limit.
- Match results by keyword instead of array position because unavailable terms can be omitted from the returned records.
- Distinguish a numeric score of 0 from an absent keyword_difficulty value when building score bands.
Related APIs
Use these APIs when you need a different type of public SEO data.
- Google Organic SERP API — Retrieve one live Google result page by query and market with normalized destinations, ranks, element types, and full result details.
- Keyword Overview API — Enrich a submitted keyword batch with available demand, paid competition, difficulty, monthly-search, and intent context.
- Keyword Search Volume API — Measure known keywords with available search volume, CPC, paid competition, and monthly search history.
- Keywords for Site API — Generate keywords relevant to one website with available demand measurements, monthly history, market context, and complete source rows.
- Keyword Suggestions API — Expand one seed query into matching long-tail terms with available demand measurements, monthly history, intent context, and complete source rows.
- Ranked Keywords API — Find keywords a domain, subdomain, or page ranks for, with matching URLs, positions, search measurements, intent, and complete source elements.
- Related Keywords API — Follow related-search paths from one seed query with depth controls, available keyword measurements, intent context, and complete source rows.
- Relevant Pages API — Inventory indexed pages for one domain with organic and paid ranking distributions, modeled traffic, and estimated cost context.
- Search Intent API — Classify primary and secondary search intent for a submitted keyword batch while preserving source probabilities and complete records.