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.
| 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
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 underserp.GET /api/projects/{projectId}/rank-tracker-reportsreturnsitems,totalandnextCursor. Passrecurring=truefor scheduled reports ormine=truefor your own. The default limit is 20, maximum 50. Pass the returned integer ascursoruntilnextCursoris null.PATCH /api/ranktracker/{id}/recurringaccepts{"is_recurring":true,"schedule_days":14}. Setis_recurringtofalseto stop future runs. The response usesok,isRecurringandscheduleDays.DELETE /api/ranktracker/{id}removes the report and returns{"ok":true}. Members can delete reports they created.