GeoRanker Docs
SEO Tools APIReport guides

Rank Tracker

Track keyword positions and compare results over time.

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).

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.

InputMeaning
keywordsRequired array, up to 200 strings.
locationsUp to 50 entries. Supply a location string or an object. The server reads name, then raw, then code as fallbacks.
engines, deviceUp to 10 engine identifiers. The default engine is google. The device is desktop (default) or mobile.
advanced.trackTopSearch depth from 1 to 100, default 10. A missing domain can still rank below that depth.
isRecurring, scheduleDaysDefaults are false and 1 day. At creation, a recurring interval can be 1 to 365 days.
fetchKeywordDataSet to true to request search-volume data. Defaults to false.
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.

{
  "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.

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

SEO Tools API overview