Ranked Keywords
Ranked keywords are search queries linked to a domain, subdomain, or page through a matching result URL, with group, absolute, and result-page positions plus available demand, difficulty, intent, and traffic signals. These query-to-page relationships support visibility inventories, landing-page mapping, opportunity review, and comparison of target snapshots.
Features
- Domain, subdomain, or page scopeResolve one correctly formatted web target at the breadth needed for a whole domain, a subdomain, or one complete page URL.
- Keyword-to-URL relationshipsPair every returned keyword with the matching destination URL exposed by its ranked search-result element.
- Position and keyword measurementsReturn available group, absolute, and result-page positions together with search volume, CPC, competition, difficulty, monthly history, and intent.
- Complete matching elementPreserve keyword_data and ranked_serp_element in extra so result type, modeled traffic, and non-promoted source details remain available.
Parameters
| Parameters | Required | Description |
|---|---|---|
target | Required | Required domain, subdomain, or page target. Omit https:// and www. for a domain, omit the protocol for a subdomain, or use a complete URL for one page. |
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 ranked keyword rows. 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 correctly scoped target with market controls and a bounded result window, then read each ranked keyword from the completed asynchronous task.
- Choose one target, 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/ranked-keywords 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/ranked-keywords" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"target":"microsoft.com","location_code":2840,"language_code":"en","results_limit":5}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueBest Use Cases
- Organic visibility inventory: Use returned keyword text and matching URLs to catalog where a domain or subdomain appears in the selected search market.
- Landing-page ranking map: Combine each keyword, destination URL, and rank object to identify which page is associated with each returned position.
- Keyword opportunity review: Compare position with available volume, CPC, competition, difficulty, and intent fields to assemble a review queue.
- Visibility snapshot comparison: Store matched target inputs, collected_at, keywords, URLs, and ranks from repeated tasks to compare separately collected snapshots.
Pro Tips
- Remove https:// and www. from a domain target, and remove the protocol from a subdomain target so the intended scope is interpreted correctly.
- Use a complete page URL when you need page-level results; a page path without a protocol can be interpreted as a domain-wide target.
- Increase offset by the number of source rows you intend to skip, and keep the target, market, language, and limit fixed when retrieving consecutive windows.
- Treat rank.page as the search-results-page number; use offset for source windows and next_cursor separately for stored SocQ result pages.
- Read normalized positions and keyword metrics first, then inspect extra.ranked_serp_element for modeled etv and other source fields that are not promoted.
- Build historical comparisons from repeated tasks, and deduplicate windows by keyword, matching URL, market, and language because source order can change.
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.
- Keyword Suggestions API — Expand one seed query into matching long-tail terms with available demand measurements, monthly history, intent context, and complete source rows.
- 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.