Google Organic SERP
Google organic search result pages combine ranked links with other visible elements such as featured snippets, questions, local results, and videos. Their destinations, positions, element types, and presentation details support ranking snapshots, layout analysis, and device or market comparison.
Features
- One-query market snapshotResolve one search query against explicit market, language, and desktop or mobile settings for a comparable point-in-time result page.
- Rank and destination fieldsReturn available destination URLs, display titles, group positions, absolute positions, and search-results-page numbers in normalized fields.
- Mixed SERP element coveragePreserve organic links and other returned result types, with extra.type identifying the kind of element represented by each record.
- Complete element contextRetain the full element-specific object in extra so domains, snippets, breadcrumbs, images, and rich-result attributes remain available when present.
Parameters
| Parameters | Required | Description |
|---|---|---|
query | Required | Required non-empty search query. One task accepts one query. |
location_code | Optional | Positive numeric market code. The Playground defaults to 2840 for the United States. |
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. |
device | Optional | Search device context: desktop or mobile. |
results_limit | Optional | Requested ranking depth from 1 through 700. It is a ceiling and does not guarantee the same number of flattened elements. |
How to Use
Submit one query with code-based market settings and a bounded depth, then read each normalized SERP element from the completed asynchronous task.
- Choose one non-empty query, a location_code, a language_code, a device, and a results_limit from 1 through 200.
- POST the payload to /v1/seo/google-organic-serp 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/google-organic-serp" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"keyword research","location_code":2840,"language_code":"en","device":"desktop","results_limit":10}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueBest Use Cases
- Current rank snapshots: Use destination URLs with rank.group, rank.absolute, rank.page, and collected_at to record where returned pages appear for a defined query.
- Device and market comparison: Submit matched queries with controlled device, location_code, and language_code values to compare result destinations and positions across contexts.
- SERP layout analysis: Inspect extra.type and element-specific fields to distinguish ranked links from questions, snippets, local results, videos, and other returned page features.
Pro Tips
- Keep query, location_code, and language_code unchanged when comparing desktop and mobile so the device is the only planned variable.
- Use a results_limit no higher than 200 even though route validation accepts larger values, because the live advanced-result depth is capped at 200.
- Branch on extra.type before reading element-specific keys, and allow url and rank values to be absent for elements that do not expose them.
- Treat rank.page as the search-results-page number; use next_cursor separately to paginate stored SocQ result records.
- Store extra as a flexible object because its available keys vary by SERP element type and may evolve.
Related APIs
Use these APIs when you need a different type of public SEO data.
- 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.
- Search Intent API — Classify primary and secondary search intent for a submitted keyword batch while preserving source probabilities and complete records.