GeoRanker Docs
SEO Tools APIReport guides

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 fieldWhat to read
keyword, location, engine, deviceThe conditions for this search. Match them before comparing positions.
serpIdThe identifier of the captured search. The report can contain several searches.
organic[].position, organic[].domain, organic[].urlThe order and destination of each organic listing.
organic[].title, organic[].textThe 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 under report.
  • GET /api/projects/{projectId}/serp-snapshot-reports returns items, total and nextCursor. The summaries include id, title, engines, status and lastUpdated. The default page size is 20. Pass limit to select a page size and the returned nextCursor as cursor to continue.
  • DELETE /api/serp-snapshot/{id} removes a snapshot and returns {"ok":true}. Members can delete their own snapshots.

Explore the interactive SERP Snapshot example

SEO Tools API overview