Keyword Suggestions
Keyword suggestions are long-tail search terms that contain a seed word or phrase with additions before, after, or within it, and their records can include demand, cost, competition, monthly history, and intent signals. These matched terms and measurements support query expansion, content-brief research, paid-search analysis, and controlled comparison of phrasing variants.
Features
- Full-text seed expansionReturn search terms that retain the submitted seed words while allowing additions before, after, or within the phrase and differences in word order.
- Keyword measurement objectsPreserve available search volume, CPC, paid competition, monthly history, and difficulty details inside each record's source data.
- Search-intent contextExpose available primary and secondary intent information for each matched keyword without treating it as a ranking recommendation.
- Controlled result windowsAccept a result ceiling from 1 through 1,000 and a zero-based row offset for retrieving a later source window.
Parameters
| Parameters | Required | Description |
|---|---|---|
query | Required | Required non-empty seed keyword or phrase. One task accepts one query. |
location_code | Optional | Positive numeric search-market code. The Playground defaults to 2840. |
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. 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 | Requested maximum from 1 through 1,000 suggestions. Fewer rows may be returned. |
offset | Optional | Zero-based number of source rows to skip before collecting the requested result window. |
How to Use
Submit one seed query with market controls and a bounded result window, then read each suggestion from the completed asynchronous task.
- Choose one non-empty query, a location_code, a language_code, a results_limit from 1 through 1,000, and an offset of 0 or greater.
- POST the payload to /v1/seo/keyword-suggestions and save the returned task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
- Read data.results.items, then request the returned next_cursor while has_more remains true.
curl -X POST "https://api.socq.ai/v1/seo/keyword-suggestions" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"keyword research","location_code":2840,"language_code":"en","results_limit":100}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueBest Use Cases
- Long-tail query expansion: Use one seed phrase and returned keyword text to collect longer query variants that preserve the original words.
- Content-brief candidate research: Combine matched terms with available volume, monthly history, difficulty, and intent fields to assemble a reviewable keyword set.
- Paid-search keyword comparison: Compare available CPC and paid-competition measurements across phrasing variants before handing candidates to a planning workflow.
Pro Tips
- Use a specific seed phrase when you need tightly matched long-tail variants; choose a semantic keyword endpoint when the terms do not need to contain the seed words.
- Treat offset as a row count rather than a page number, and increase it by the size of the source window you intend to skip.
- Record query, location_code, language_code, results_limit, and offset together because later source ordering can change between otherwise matched requests.
- Read keyword and search_intent from normalized fields first, then inspect extra.keyword_info and extra.keyword_properties for direct measurement objects that are not promoted.
- Deduplicate repeated windows by keyword plus market and language, and allow every optional metric or nested object to be absent.
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 Difficulty API — Compare organic ranking difficulty for a submitted keyword batch, returning each available keyword with its normalized score.
- 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.
- 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.