# Heatmap (SEO Competitors)

> Compare search positions and competitors across locations.

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

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.

```bash
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

```bash
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 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](https://docs.georanker.com/docs/heatmap-1)

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