---
title: Query click map
description: "Returns click counts for one page URL, grouped by the CSS selector of the clicked element or by page coordinate, ranked by count. Filter by device viewport b…"
product: general
lang: en
last_updated: 2026-10-05
token_estimate: 2302
---
# Query click map

## Query click map

**POST** `/v1/projects/{project_id}/heatmaps/click-map`

Full URL: `https://developer-api.amplitude.com/v1/projects/{project_id}/heatmaps/click-map`

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

**Servers:**
- Production (US): `https://developer-api.amplitude.com/v1/projects/{project_id}/heatmaps/click-map`
- Production (EU): `https://developer-api.eu.amplitude.com/v1/projects/{project_id}/heatmaps/click-map`

Query click map

Returns click counts for one page URL, grouped by the CSS selector of the
clicked element or by page coordinate, ranked by count. Filter by device
viewport band and date range. Results reflect the authenticated caller's
project access and data access controls.

This POST computes a result and does not mutate state. It is therefore a
read operation and does not require an `Idempotency-Key`.

Omitting `time_range` uses the last 30 days in the project timezone. The
span of `time_range` cannot exceed 90 days.

## Authorizations

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| Authorization | string | Yes | — | http |

## Path parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| project_id (path) | string | Yes | 12345 | Amplitude project identifier, backed by the canonical app ID. Constraints: pattern: ^[0-9]+$ |

## Body (application/json)

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| page_url | string | Yes | https://example.com/pricing | Page URL to analyze. Accepts `http` and `https` URLs; a URL without a scheme is treated as `https`. The query string and fragment are removed before matching, so `https://example.com/pricing?utm=x` and `https://example.com/pricing` are the same page. Constraints: min length: 1, max length: 2048 |
| url_match | string | No | is | How `page_url` is matched against the page URL recorded on each event. `is` matches the exact URL, `contains` matches any URL containing it, `has_prefix` matches URLs starting with it, and `glob` treats `*` as a wildcard. Allowed values: is, contains, has_prefix, glob |
| device_type | string | No | desktop | Viewport band to include, matching the device selector in the product: `desktop` is at least 1440 px wide, `laptop` is 900 to 1440 px, `tablet` is 500 to 900 px, `mobile` is at most 500 px. Use `custom` with `viewport_width` to match one exact width. Allowed values: desktop, laptop, tablet, mobile, custom |
| viewport_width | integer | No | — | Exact viewport width in pixels. Required when `device_type` is `custom` and not accepted otherwise. Constraints: min: 1, max: 20000 |
| time_range | object | No | — | — |
| time_range.start | string | Yes | — | Inclusive start date (project timezone unless `timezone` is set on query). Constraints: format: date |
| time_range.end | string | Yes | — | Inclusive end date. Constraints: format: date |
| group_by | string | No | selector | `selector` groups clicks by the CSS selector of the clicked element; `pixel` groups them by page coordinate. Allowed values: selector, pixel |
| metric | string | No | totals | `totals` counts every click; `uniques` counts distinct users who clicked. Allowed values: totals, uniques |
| limit | integer | No | 50 | Maximum number of rows returned after ranking by `count`. Constraints: min: 1, max: 200 |

## Response (application/json)

**200** — Click map computed successfully.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| data | object | Yes | — | Ranked click counts for one page. Exactly one of `selectors` and `pixels` is populated, chosen by `group_by`; the other is `null`. Rows are sorted by `count` descending. Results reflect the caller's data access. |
| data.id | string | Yes | — | Identifier for this computation. |
| data.object | string | Yes | — | Resource-type discriminator. Always `click_map`. |
| data.project_id | string | Yes | — | Constraints: pattern: ^[0-9]+$ |
| data.page_url | string | Yes | — | The page URL after normalization. |
| data.url_match | string | Yes | is | How `page_url` is matched against the page URL recorded on each event. `is` matches the exact URL, `contains` matches any URL containing it, `has_prefix` matches URLs starting with it, and `glob` treats `*` as a wildcard. Allowed values: is, contains, has_prefix, glob |
| data.device_type | string | Yes | desktop | Viewport band to include, matching the device selector in the product: `desktop` is at least 1440 px wide, `laptop` is 900 to 1440 px, `tablet` is 500 to 900 px, `mobile` is at most 500 px. Use `custom` with `viewport_width` to match one exact width. Allowed values: desktop, laptop, tablet, mobile, custom |
| data.viewport_width | integer | Yes | — | Exact viewport width used when `device_type` is `custom`; otherwise `null`. Constraints: nullable |
| data.group_by | string | Yes | — | Allowed values: selector, pixel |
| data.metric | string | Yes | — | Allowed values: totals, uniques |
| data.time_range | object | Yes | — | — |
| data.time_range.start | string | Yes | — | Inclusive start date (project timezone unless `timezone` is set on query). Constraints: format: date |
| data.time_range.end | string | Yes | — | Inclusive end date. Constraints: format: date |
| data.timezone | string | Yes | — | IANA timezone used to resolve `time_range` day boundaries (the project timezone). |
| data.result_count | integer | Yes | — | Number of rows returned. Constraints: min: 0 |
| data.truncated | boolean | Yes | — | `true` when more rows were available than `limit` allowed. The underlying query is itself bounded, so `false` does not guarantee that every clicked element on the page is listed. |
| data.selectors | object[] | Yes | — | Constraints: nullable |
| data.pixels | object[] | Yes | — | Constraints: nullable |
| data.warnings | string[] | Yes | — | Non-fatal conditions, such as an empty result for the range. |

```json
{
  "data": {
    "id": "string",
    "object": "click_map",
    "project_id": "string",
    "page_url": "string",
    "url_match": "is",
    "device_type": "desktop",
    "viewport_width": 0,
    "group_by": "selector",
    "metric": "totals",
    "time_range": {
      "start": "2024-01-01",
      "end": "2024-01-01"
    },
    "timezone": "string",
    "result_count": 0,
    "truncated": true,
    "selectors": [
      {
        "selector": "string",
        "count": 0
      }
    ],
    "pixels": [
      {
        "x": 0,
        "y": 0,
        "count": 0
      }
    ],
    "warnings": [
      "string"
    ]
  }
}
```

**400**

**401**

**403**

**404**

**422**

**429**

**500**

**502**

**503**

**504**

## Code samples

### cURL

```bash
curl -X POST "https://developer-api.amplitude.com/v1/projects/12345/heatmaps/click-map" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY"
```

### Python

```python
import requests

response = requests.post(
    "https://developer-api.amplitude.com/v1/projects/12345/heatmaps/click-map",
    headers={
        "Content-Type": "application/json",
        "Authorization": "YOUR_API_KEY"
    }
)
data = response.json()
```

### JavaScript

```javascript
const response = await fetch("https://developer-api.amplitude.com/v1/projects/12345/heatmaps/click-map", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_KEY"
  }
});
const data = await response.json();
```

### PHP

```php
<?php
$ch = curl_init("https://developer-api.amplitude.com/v1/projects/12345/heatmaps/click-map");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
```

### Go

```go
package main

import (
  "bytes"
  "net/http"
)

func main() {
req, _ := http.NewRequest("POST", "https://developer-api.amplitude.com/v1/projects/12345/heatmaps/click-map", nil)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "YOUR_API_KEY")
  client := &http.Client{}
  resp, _ := client.Do(req)
  defer resp.Body.Close()
}
```

### Java

```java
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://developer-api.amplitude.com/v1/projects/12345/heatmaps/click-map"))
      .method("POST", HttpRequest.BodyPublishers.noBody())
.header("Content-Type", "application/json")
      .header("Authorization", "YOUR_API_KEY")
      .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
```

### Ruby

```ruby
require "net/http"
require "json"

uri = URI("https://developer-api.amplitude.com/v1/projects/12345/heatmaps/click-map")
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["Authorization"] = "YOUR_API_KEY"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end
```

