Heatmap (SEO Competitors)
Compare search positions and competitors across locations.
Heatmap compares the domains and pages appearing at each search position across selected locations. The SEO Tools interface calls this view SEO Competitors. Use it to see which competitors occupy the top spots across several markets and which ones appear in only one.
Create a competitor heatmap
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 follows the current SEO Tools form and requests the first five organic positions for a query in two countries.
curl -sS --fail-with-body https://seoapi.georanker.com/api/heatmap \
-H "Authorization: Bearer $SEO_TOOLS_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- <<JSON
{
"payload": {
"projectId": "$PROJECT_ID",
"reportName": "Running shoe competitors by country",
"keywords": ["wide running shoes"],
"engines": ["google"],
"device": "desktop",
"language": "en",
"resultsCount": 5,
"locations": [
{"name": "United States", "raw": "United States", "code": "US"},
{"name": "Canada", "raw": "Canada", "code": "CA"}
]
}
}
JSON
The form offers google, bing and yahoo, with desktop, mobile or both for the device. Its resultsCount setting ranges from 1 to 10. HTTP 201 returns id and serpCount. Save the UUID as REPORT_ID.
Compare positions by location
curl -sS --fail-with-body "https://seoapi.georanker.com/api/heatmap/$REPORT_ID/results" \
-H "Authorization: Bearer $SEO_TOOLS_API_KEY"
| Result field | How to use it |
|---|---|
pending | Number of outstanding searches. While positive, read the same report again after a pause. |
items | Array of search results. The schema leaves individual item properties open. |
items[].keyword, .engine, .device, .location | The fields the viewer uses to select comparable searches. |
items[].organic[] | The viewer maps position to each result's domain, url, title and snippet (text). |
An illustrative heatmap for one query might show these first two positions on Google desktop.
| Location | Position 1 | Position 2 |
|---|---|---|
| United States | example.com | example.org |
| Canada | example.ca | example.com |
For each location, take the three lowest numerical positions and list the domains occupying them. Check the URLs to see whether the same competitor wins with different country pages. Include the keyword, engine and device alongside this comparison.
Manage heatmaps
GET /api/heatmap/{id}returns metadata in areportobject.GET /api/projects/{projectId}/heatmapsreturnsitems,totalandnextCursor. Summary rows includeid,title,engines,locations,statusandlastUpdated. Usemine=trueto filter by creator. The defaultlimitis 20. Pass the returnednextCursorascursorfor the next page.DELETE /api/heatmap/{id}removes the report and returns{"ok":true}. Members can delete reports they created.