Search Intent
Search Intent describes a query through informational, navigational, commercial, or transactional labels, together with primary and secondary probability signals. These classifications support keyword inventory labeling, mixed-intent review, content-brief alignment, and routing prepared keyword lists into research workflows.
Features
- Language-aware batch classificationClassify up to 1,000 supplied keywords in one selected language, with English used when no language is provided.
- Primary and secondary intent signalsReturn the most probable intent and its probability together with other likely intents and their probabilities.
- Normalized and complete recordsRead the normalized keyword and search_intent fields while retaining keyword_intent and secondary_keyword_intents in extra.
Parameters
| Parameters | Required | Description |
|---|---|---|
keywords | Required | Required list of 1 to 1,000 non-empty keywords, each no longer than 80 characters. |
location_code | Optional | Optional positive search-market location code. |
location_name | Optional | Optional search-market name alternative to location_code. When filled, it takes precedence over location_code. |
language_code | Optional | 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 | Optional result ceiling from 1 through 2,000. |
How to Use
Submit a keyword list with optional market, language, and result-limit settings, then read the normalized intent records from the completed asynchronous task.
- Prepare 1 to 1,000 non-empty keywords, each no longer than 80 characters.
- POST keywords and any optional market, language, or results_limit fields to /v1/seo/search-intent and 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 remains true.
curl -X POST "https://api.socq.ai/v1/seo/search-intent" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keywords":["how to research keywords","buy seo software"],"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 inventory labeling: Use each keyword and its primary intent to add consistent intent labels to a prepared keyword inventory.
- Mixed-intent review: Compare primary and secondary labels with their probabilities to identify keywords that may represent more than one search goal.
- Research workflow routing: Group supplied keywords by informational, navigational, commercial, or transactional intent before routing them into separate research workflows.
Pro Tips
- Remove empty and duplicate entries before submitting a batch so input-count billing reflects the keywords you intend to classify.
- Keep market and language fields consistent when comparing batches.
- Review secondary intent probabilities when a keyword has mixed intent instead of treating the primary label as a universal fact.
- Allow for missing classifications, and read extra when auditing the original keyword_intent and secondary_keyword_intents objects.
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.
- 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.