# SERP Snapshot

> Capture search results for a keyword and compare markets.

Canonical: https://docs.georanker.com/docs/seo-tools-api-serp-snapshot

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.

```bash
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

```bash
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.

```json
{
  "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](https://docs.georanker.com/docs/first-page-countries-1)

[SEO Tools API overview](https://docs.georanker.com/docs/seo-tools-api)
