# Rank Tracker

> Track keyword positions and compare results over time.

Canonical: https://docs.georanker.com/docs/seo-tools-api-rank-tracker

Rank Tracker measures where a target domain appears for each combination of keyword, location and search engine. A weekly report can show whether a landing page is gaining ground in one market while losing visibility in another. Keep the engine, device and search depth consistent when comparing runs.

## Create a weekly report

Set `PROJECT_ID` to your project UUID and `SEO_TOOLS_API_KEY` to your API key. This example tracks two queries in one location on Google desktop. Each run requests two search engine results pages (SERPs).

```bash
curl -sS --fail-with-body https://seoapi.georanker.com/api/ranktracker \
  -H "Authorization: Bearer $SEO_TOOLS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{
  "payload": {
    "projectId": "$PROJECT_ID",
    "reportName": "Weekly running shoe rankings",
    "targetDomain": "example.com",
    "keywords": ["running shoes", "wide running shoes"],
    "locations": ["New York, United States"],
    "engines": ["google"],
    "device": "desktop",
    "advanced": {"trackTop": 20},
    "isRecurring": true,
    "scheduleDays": 7
  }
}
JSON
```

HTTP 200 returns an `id` and a `serpCount`. Save the UUID as `REPORT_ID`. The count is keywords x locations x engines. It measures requested searches, so a count of two does not tell you how many rankings have arrived.

| Input                         | Meaning                                                                                                                 |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `keywords`                    | Required array, up to 200 strings.                                                                                      |
| `locations`                   | Up to 50 entries. Supply a location string or an object. The server reads `name`, then `raw`, then `code` as fallbacks. |
| `engines`, `device`           | Up to 10 engine identifiers. The default engine is `google`. The device is `desktop` (default) or `mobile`.             |
| `advanced.trackTop`           | Search depth from 1 to 100, default 10. A missing domain can still rank below that depth.                               |
| `isRecurring`, `scheduleDays` | Defaults are `false` and 1 day. At creation, a recurring interval can be 1 to 365 days.                                 |
| `fetchKeywordData`            | Set to `true` to request search-volume data. Defaults to `false`.                                                       |

## Read rankings and inspect a search

```bash
curl -sS --fail-with-body "https://seoapi.georanker.com/api/ranktracker/$REPORT_ID/keywords" \
  -H "Authorization: Bearer $SEO_TOOLS_API_KEY"
```

The published schema names the result array `keywords`. The current SEO Tools viewer reads `items` and a `pending` count from the same endpoint. Read `items` when present, otherwise read `keywords`. Check that the value is an array before iterating through it. The viewer uses `keyword`, `location`, `engine`, `device`, `processed`, `currentRank`, `prevRank`, `bestRank` and `serpId` on its rows. Wait for a row to finish before recording a missing rank.

In this illustrative row, the domain moved from ninth to sixth for one mobile search. Its best recorded position was fourth.

```json
{
  "keyword": "running shoes",
  "location": "New York, United States",
  "engine": "google",
  "device": "mobile",
  "currentRank": 6,
  "prevRank": 9,
  "bestRank": 4,
  "serpId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
}
```

Set `SERP_ID` to the row's `serpId` to inspect the results behind a ranking. The viewer reads `organic` entries with `position`, `domain`, `url`, `title` and `text`. Use this to identify the page that overtook your target.

```bash
curl -sS --fail-with-body "https://seoapi.georanker.com/api/ranktracker/$REPORT_ID/keyword-serp/$SERP_ID" \
  -H "Authorization: Bearer $SEO_TOOLS_API_KEY"
```

## Manage the report

* `GET /api/ranktracker/{id}` returns the report detail under `serp`.
* `GET /api/projects/{projectId}/rank-tracker-reports` returns `items`, `total` and `nextCursor`. Pass `recurring=true` for scheduled reports or `mine=true` for your own. The default limit is 20, maximum 50. Pass the returned integer as `cursor` until `nextCursor` is null.
* `PATCH /api/ranktracker/{id}/recurring` accepts `{"is_recurring":true,"schedule_days":14}`. Set `is_recurring` to `false` to stop future runs. The response uses `ok`, `isRecurring` and `scheduleDays`.
* `DELETE /api/ranktracker/{id}` removes the report and returns `{"ok":true}`. Members can delete reports they created.

[Explore the interactive Rank Tracker example](https://docs.georanker.com/docs/ranktracker)

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