数据分析

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d&unique=true" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=countries&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "clicks": 142
}

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d&unique=true" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=countries&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "clicks": 142
}

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

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

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

如需每个二维码的现成汇总，请参阅报告。

数据的含义

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

请求头

string

必填

Bearer 后跟您的 API 密钥。请参阅身份验证。

查询参数

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

string

默认值:"count"

细分维度。count 返回总数。所有取值及其响应结构请参阅细分维度。

string

默认值:"30d"

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

string

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

string

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

string

默认值:"UTC"

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

boolean

默认值:"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 时的响应：

{ "clicks": 142 }

当 groupBy=countries 时的响应：

[
  { "country": "US", "city": "*", "clicks": 87 },
  { "country": "DE", "city": "*", "clicks": 31 },
  { "country": "GB", "city": "*", "clicks": 24 }
]

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

GET /api/v1/qrs/{qrId}/analytics 返回单个二维码的扫描统计数据，范围限定为其短链接。接受上文的查询参数和维度过滤器。

string

必填

二维码的 ID。可从二维码的列表或创建接口的响应中获取。

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d&unique=true" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=countries&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "clicks": 142
}

获取工作区分析数据

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

string

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

string

短链接路径，例如 x7Kd2p1。请与 domain 一起使用。两者都可以在二维码对象中找到。

string

要包含的二维码类型，以逗号分隔：website、pdf、image、video、whatsapp、social、wifi、app、feedback、vcard、sms、payment、location、multilink、email 或 event。请参阅二维码类型。

curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=30d&qrType=website" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/analytics?groupBy=count&domain=getqr.sh&key=x7Kd2p1" \
  -H "Authorization: Bearer $GETQR_API_KEY"

[
  { "device": "Mobile", "clicks": 980 },
  { "device": "Desktop", "clicks": 240 }
]

常见问题

400 "QR has no associated link."

该二维码没有短链接，因此没有可统计的扫描。

按 domain 和 key 过滤时返回 404

您的工作区中不存在使用该域名和路径的短链接。请从二维码对象中复制 domain 和 key。

groupBy、interval 或过滤器返回 422

该值不受支持。错误消息会指出参数名，并列出有效的取值。

数据与控制台中的不一致

请确认您使用的日期范围和时区相同，并确认统计的是唯一扫描数（unique=true）还是扫描总数。

API

数据的含义

请求头

查询参数

日期范围

维度过滤器

细分维度

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

获取工作区分析数据

常见问题

后续步骤

报告

二维码

应用中的数据分析

速率限制

​数据的含义

​请求头

​查询参数

​日期范围

​维度过滤器

​细分维度

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

​获取工作区分析数据

​常见问题

​后续步骤

报告

二维码

应用中的数据分析

速率限制

数据的含义

请求头

查询参数

日期范围

维度过滤器

细分维度

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

获取工作区分析数据

常见问题

后续步骤