SERP Snapshot
Capture search results for a keyword and compare markets.
A SERP Snapshot captures the results that appeared for a query at a particular location, on one device and search engine. Use it to investigate a ranking change or compare which pages compete for the same query in two markets. Save the report ID with your findings so a colleague can inspect the same capture later.
Capture two markets
Set PROJECT_ID to your project UUID and SEO_TOOLS_API_KEY to your API key. The public schema requires a payload object and leaves its fields open. This example uses the fields sent by the current SEO Tools report form.
curl -sS --fail-with-body https://seoapi.georanker.com/api/serp-snapshot \
-H "Authorization: Bearer $SEO_TOOLS_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- <<JSON
{
"payload": {
"projectId": "$PROJECT_ID",
"reportName": "Running shoes in the US and Canada",
"keywords": ["running shoes"],
"engines": ["google"],
"device": "desktop",
"language": "en",
"advanced": {"trackTop": 10},
"locations": [
{"name": "United States", "raw": "United States", "code": "US"},
{"name": "Canada", "raw": "Canada", "code": "CA"}
]
}
}
JSON
The form offers desktop or mobile and search depths from 10 to 100 in increments of 10. Its engine choices are google, googlelocal, bing, yahoo and youtube. HTTP 201 returns the report id and serpCount, the number of search pages queued. Save the UUID as REPORT_ID.
Read a capture
curl -sS --fail-with-body "https://seoapi.georanker.com/api/serp-snapshot/$REPORT_ID/results" \
-H "Authorization: Bearer $SEO_TOOLS_API_KEY"
The response contains an items array. The public schema leaves item fields open. The SEO Tools viewer uses these fields to display each capture.
| Result field | What to read |
|---|---|
keyword, location, engine, device | The conditions for this search. Match them before comparing positions. |
serpId | The identifier of the captured search. The report can contain several searches. |
organic[].position, organic[].domain, organic[].url | The order and destination of each organic listing. |
organic[].title, organic[].text | The title and snippet shown in the search results. |
An illustrative listing from a capture's organic array shows what a reader saw at position two.
{
"position": 2,
"domain": "example.com",
"url": "https://example.com/ca/running-shoes",
"title": "Running shoes in Canada",
"text": "Browse road and trail running shoes."
}
For the example above, compare the URLs occupying positions 1 to 3 in each country. A domain may rank in both countries using a different landing page. If a capture is still pending, read the report and results again after a pause.
Find or remove snapshots
GET /api/serp-snapshot/{id}returns the report underreport.GET /api/projects/{projectId}/serp-snapshot-reportsreturnsitems,totalandnextCursor. The summaries includeid,title,engines,statusandlastUpdated. The default page size is 20. Passlimitto select a page size and the returnednextCursorascursorto continue.DELETE /api/serp-snapshot/{id}removes a snapshot and returns{"ok":true}. Members can delete their own snapshots.