Keyword Search Volume
Keyword search-volume records pair known search terms with estimated demand, CPC, paid competition, and monthly observations for a selected or worldwide search context. These measurements support demand comparison, seasonality review, paid-market research, and term-list enrichment.
Features
- Known-keyword batch measurementMeasure from 1 to 1,000 prepared keywords in one request, with each input limited to 80 characters.
- Search-demand fieldsReturn available search_volume values and monthly_searches observations for each keyword that has measurement data.
- Paid-market contextKeep available CPC, competition, competition level, competition index, and optional bid fields connected to the measured term.
- Normalized records with source contextPromote stable demand fields into metrics while preserving the complete returned row in extra for optional market and bid metadata.
Parameters
| Parameters | Required | Description |
|---|---|---|
keywords | Required | Required list of 1 to 1,000 known, non-empty keywords, with a maximum of 80 characters per item. |
location_code | Optional | Optional positive numeric search-market code. The Playground explicitly sends 2840 for the United States; clear this field with language_code to use the backend's worldwide scope. |
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 explicitly sends en; clear this field with location_code to use the backend's worldwide scope. |
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 known-keyword list with optional market and language settings, then read normalized demand fields from the asynchronous result records.
- Prepare 1 to 1,000 non-empty known keywords, each no longer than 80 characters.
- POST keywords to /v1/seo/keyword-search-volume; include location_code and language_code for a reproducible market-specific request, then save the returned task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
- Read data.results.items and follow next_cursor while has_more is true; inspect extra for source fields that are not promoted.
curl -X POST "https://api.socq.ai/v1/seo/keyword-search-volume" \
-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
- Prepared-list demand comparison: Join search_volume values to a known term list and compare estimated demand within a consistent search context.
- Monthly seasonality review: Use year, month, and search_volume observations to examine changes in measured demand over time.
- Paid-search landscape research: Compare CPC, competition, competition index, and optional bid context across measured keywords.
Pro Tips
- Combine prepared terms into a bounded batch when appropriate because the fixed 24-credit charge applies to the request rather than each returned row.
- Keep location_code and language_code explicit and unchanged when comparing batches; omit both only when worldwide scope is intended.
- Do not submit results_limit because the keywords array controls this operation's batch and the operation has no documented limit control.
- Match returned rows by keyword and treat missing records or null fields as unavailable data rather than confirmed zero demand.
- Interpret CPC and competition as paid-search signals, not as organic ranking difficulty, and account for close variants that can share aggregated volume.
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.
- 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.