What is the Search Intent API?

Search Intent API is a programmatic interface for classifying up to 1,000 supplied keywords in a selected language. It returns normalized primary and secondary intent labels with probabilities for each available keyword.

Which intent labels can appear?

The four labels are informational, navigational, commercial, and transactional.

Which inputs control Search Intent classification?

Submit keywords, optionally set location_code or location_name, choose language_code or language, and use results_limit from 1 through 2,000 when needed.

How many keywords can I submit?

Submit from 1 through 1,000 non-empty keywords, with a maximum length of 80 characters per keyword.

What does the probability mean?

It is confidence within the intent classification, not a purchase probability or conversion rate. Mixed-intent keywords can therefore include meaningful secondary classifications.

Can every submitted keyword produce a result?

No. Some submitted keywords may not produce a classification, so match returned records by keyword and handle absent rows.

How is the endpoint billed?

Each submitted keyword costs 0.1 SocQ credits.

Search Intent API: Keyword Intent Classification

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 true

Best 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.

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.

Combine SEO data with public data from other supported social platforms.

Search Intent API