> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据分析

> 单个二维码或整个工作区的扫描统计数据。

> [!NOTE]
>
> GetQR API 目前处于 Beta 阶段，仅向部分工作区开放。正式发布前，细节可能会有所变化。

获取单个二维码或整个工作区的扫描总数，以及按国家/地区、设备、浏览器等维度的细分数据。

| 方法 | 路径 | 说明 |
| - | - | - |
| `GET` | `/api/v1/qrs/{qrId}/analytics` | [获取单个二维码的分析数据](#获取单个二维码的分析数据) |
| `GET` | `/api/v1/analytics` | [获取工作区分析数据](#获取工作区分析数据) |

如需每个二维码的现成汇总，请参阅[报告](https://docs.getqr.com/zh/api/endpoints/reports.md)。

## 数据的含义

* **扫描。** 所有计数都在 `clicks` 字段中。每当有人打开二维码的短链接，就会计为一次扫描。
* **唯一扫描。** 使用 `unique=true` 时，每位访问者在日期范围内只计一次。
* **范围。** 数据来自二维码的短链接。没有短链接的二维码没有可统计的扫描。
* **历史数据。** 分析数据无法通过 API 重置。删除二维码不会清除其历史扫描数据。

## 请求头

**Authorization** `string` *required*

`Bearer` 后跟您的 API 密钥。请参阅[身份验证](https://docs.getqr.com/zh/api/authentication.md)。

## 查询参数

两个端点都接受以下参数，全部为可选。

**groupBy** `string` (default: count)

细分维度。`count` 返回总数。所有取值及其响应结构请参阅[细分维度](#细分维度)。

**interval** `string` (default: 30d)

预设日期范围：`24h`、`7d`、`30d`、`90d`、`1y`、`mtd`、`qtd`、`ytd` 或 `all`。请参阅[日期范围](#日期范围)。发送 `start` 时会被忽略。

**start** `string`

自定义范围的开始时间，ISO 8601 格式，例如 `2026-08-01` 或 `2026-08-01T00:00:00Z`。优先于 `interval`。必须早于 `end`。

**end** `string`

自定义范围的结束时间，ISO 8601 格式。默认为今天结束时。与 `start` 或 `interval=all` 一起使用，搭配其他区间时会被忽略。

**timezone** `string` (default: UTC)

用于对齐 `timeseries` 时间段的 IANA 时区，例如 `America/New_York`。未知时区会返回 `422`。

**unique** `boolean` (default: false)

为 `true` 时统计唯一扫描数，而不是扫描总数。

您还可以发送[维度过滤器](#维度过滤器)。

## 日期范围

| `interval` | 覆盖范围 | `timeseries` 时间段 |
| - | - | - |
| `24h` | 过去 24 小时 | 小时 |
| `7d` | 过去 7 天，含今天 | 天 |
| `30d` | 过去 30 天，含今天 | 天 |
| `90d` | 过去 90 天，含今天 | 天 |
| `1y` | 过去 365 天，含今天 | 月 |
| `mtd` | 本月至今 | 天 |
| `qtd` | 本季度至今 | 天 |
| `ytd` | 本年至今 | 天；超过 180 天后为月 |
| `all` | 自工作区创建以来 | 天；超过 180 天后为月 |

如需自定义范围，请发送 `start`，并可选择发送 `end`。不超过 2 天的范围按小时划分时间段，超过 180 天的范围按月划分，介于两者之间的按天划分。

## 维度过滤器

将结果限定为符合过滤条件的扫描。不同的过滤器之间以 AND 组合。如果某个过滤器接受多个值，请用逗号分隔：这些值之间以 OR 组合。

| 过滤器 | 值 | 多个值 |
| - | - | - |
| `country` | ISO 3166-1 alpha-2 国家/地区代码，例如 `US` | 是 |
| `region` | ISO 3166-2 地区代码，例如 `US-CA` | 是 |
| `city` | 城市名称，例如 `New York` | 是 |
| `continent` | `AF`、`AN`、`AS`、`EU`、`NA`、`OC` 或 `SA` | 是 |
| `device` | 设备类型，例如 `Mobile` 或 `Desktop` | 是 |
| `browser` | 浏览器名称，例如 `Chrome` | 是 |
| `os` | 操作系统，例如 `iOS` 或 `Windows` | 是 |
| `url` | 目标 URL | 是 |
| `referer` | 来源，例如 `google.com` | 否 |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` | UTM 值，最多 190 个字符 | 否 |

未知的国家/地区或大洲代码会返回 `422`。设备、浏览器和操作系统名称按首字母大写的形式匹配，因此 `mobile` 与 `Mobile` 效果相同。

例如，来自美国或加拿大、使用移动设备的扫描：`?country=US,CA&device=Mobile`。

## 细分维度

`count` 返回一个对象。其他所有取值都返回一个数组，按 `clicks` 从高到低排序（`timeseries` 按时间排序）。

| `groupBy` | 每项包含 |
| - | - |
| `count` | `clicks`（对象，而不是数组） |
| `timeseries` | `start`（时间段的开始时间）、`clicks` |
| `continents` | `continent`、`clicks` |
| `regions` | `region`、`country`、`clicks` |
| `countries` | `country`、`city`（始终为 `*`）、`clicks` |
| `cities` | `city`、`country`、`clicks` |
| `devices` | `device`、`clicks` |
| `browsers` | `browser`、`clicks` |
| `os` | `os`、`clicks` |
| `triggers` | `trigger`（`qr` 或 `link`）、`clicks` |
| `referers` | `referer`（未知时为 `(direct)`）、`clicks` |
| `referer_urls` | `refererUrl`（未知时为 `(direct)`）、`clicks` |
| `top_links` | `id`、`domain`、`key`、`shortLink`、`url`、`createdAt`、`qr`（`id`、`qrType`、`title`）、`clicks` |
| `top_urls` | `url`、`clicks` |
| `top_types` | `qr_type`、`clicks` |
| `utm_sources`, `utm_mediums`, `utm_campaigns`, `utm_terms`, `utm_contents` | UTM 值（`utm_source`、`utm_medium`、`utm_campaign`、`utm_term` 或 `utm_content`）、`clicks` |

未知的 `groupBy` 会返回 `422`，并列出有效的取值。

当 `groupBy=count` 时的响应：

```json theme={null}
{ "clicks": 142 }
```

当 `groupBy=countries` 时的响应：

```json theme={null}
[
  { "country": "US", "city": "*", "clicks": 87 },
  { "country": "DE", "city": "*", "clicks": 31 },
  { "country": "GB", "city": "*", "clicks": 24 }
]
```

## 获取单个二维码的分析数据

`GET /api/v1/qrs/{qrId}/analytics`

返回单个二维码的扫描统计数据，范围限定为其短链接。接受上文的[查询参数](#查询参数)和[维度过滤器](#维度过滤器)。

**qrId** `string` *required*

二维码的 ID。可从[二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)的列表或创建接口的响应中获取。

```bash Total scans, last 30 days theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash Unique scans theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d&unique=true" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash By country, last 7 days theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=countries&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "clicks": 142
}
```

## 获取工作区分析数据

`GET /api/v1/analytics`

返回工作区内所有二维码的扫描统计数据。接受上文的[查询参数](#查询参数)和[维度过滤器](#维度过滤器)，另外还接受以下用于限定范围的参数。

**domain** `string`

与 `key` 一起使用，将结果限定为使用此域名的短链接，例如 `getqr.sh`。该域名必须属于您的工作区。

**key** `string`

短链接路径，例如 `x7Kd2p1`。请与 `domain` 一起使用。两者都可以在[二维码对象](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)中找到。

**qrType** `string`

要包含的二维码类型，以逗号分隔：`website`、`pdf`、`image`、`video`、`whatsapp`、`social`、`wifi`、`app`、`feedback`、`vcard`、`sms`、`payment`、`location`、`multilink`、`email` 或 `event`。请参阅[二维码类型](https://docs.getqr.com/zh/api/guides/qr-types.md)。

```bash Devices, last 7 days theme={null}
curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash Devices, website QR codes only theme={null}
curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=30d&qrType=website" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash One short link theme={null}
curl "https://getqr.com/api/v1/analytics?groupBy=count&domain=getqr.sh&key=x7Kd2p1" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
[
  { "device": "Mobile", "clicks": 980 },
  { "device": "Desktop", "clicks": 240 }
]
```

## 常见问题

> [accordion] 400 "QR has no associated link."
>
> 该二维码没有短链接，因此没有可统计的扫描。

> [accordion] 按 domain 和 key 过滤时返回 404
>
> 您的工作区中不存在使用该域名和路径的短链接。请从二维码对象中复制 `domain` 和 `key`。

> [accordion] groupBy、interval 或过滤器返回 422
>
> 该值不受支持。错误消息会指出参数名，并列出有效的取值。

> [accordion] 数据与控制台中的不一致
>
> 请确认您使用的日期范围和时区相同，并确认统计的是唯一扫描数（`unique=true`）还是扫描总数。

## 后续步骤

> [card] [报告](https://docs.getqr.com/zh/api/endpoints/reports.md)

> [card] [二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)

> [card] [应用中的数据分析](https://docs.getqr.com/zh/analytics/overview.md)

> [card] [速率限制](https://docs.getqr.com/zh/api/rate-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.