GeoRanker Docs
SEO Tools APIReport guides

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 fieldHow to use it
pendingNumber of outstanding searches. While positive, read the same report again after a pause.
itemsArray of search results. The schema leaves individual item properties open.
items[].keyword, .engine, .device, .locationThe 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.

LocationPosition 1Position 2
United Statesexample.comexample.org
Canadaexample.caexample.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 a report object.
  • GET /api/projects/{projectId}/heatmaps returns items, total and nextCursor. Summary rows include id, title, engines, locations, status and lastUpdated. Use mine=true to filter by creator. The default limit is 20. Pass the returned nextCursor as cursor for the next page.
  • DELETE /api/heatmap/{id} removes the report and returns {"ok":true}. Members can delete reports they created.

Explore the interactive SEO Competitors example

SEO Tools API overview