> ## 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.

# Аналитика

> Статистика сканирований для одного QR-кода или всего рабочего пространства.

> [!NOTE]
>
> GetQR API находится в бета-версии и доступен для отдельных рабочих пространств. До общего релиза детали могут измениться.

Получайте общее число сканирований и разбивки по странам, устройствам, браузерам и другим измерениям — для одного QR-кода или по всему рабочему пространству.

| Метод | Путь | Описание |
| - | - | - |
| `GET` | `/api/v1/qrs/{qrId}/analytics` | [Аналитика QR-кода](#аналитика-qr-кода) |
| `GET` | `/api/v1/analytics` | [Аналитика рабочего пространства](#аналитика-рабочего-пространства) |

Готовую сводку по каждому QR-коду см. в разделе [Отчёты](https://docs.getqr.com/ru/api/endpoints/reports.md).

## Что означают числа

* **Сканирования.** Все значения находятся в поле `clicks`. Сканирование засчитывается каждый раз, когда кто-то открывает короткую ссылку QR-кода.
* **Уникальные сканирования.** С `unique=true` каждый посетитель учитывается один раз за диапазон дат.
* **Охват.** Числа берутся из короткой ссылки QR-кода. У QR-кода без короткой ссылки нет сканирований для подсчёта.
* **История.** Аналитику нельзя сбросить через API. Удаление QR-кода не стирает историю его сканирований.

## Заголовки

**Authorization** `string` *required*

`Bearer` и ваш API-ключ. См. [Аутентификация](https://docs.getqr.com/ru/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)

Часовой пояс IANA для выравнивания интервалов `timeseries`, например `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 }
]
```

## Аналитика QR-кода

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

Возвращает статистику сканирований одного QR-кода по его короткой ссылке. Принимает описанные выше [параметры запроса](#параметры-запроса) и [фильтры по измерениям](#фильтры-по-измерениям).

**qrId** `string` *required*

ID QR-кода. Возьмите его из ответа на запрос списка или создания [QR-кодов](https://docs.getqr.com/ru/api/endpoints/qr-codes.md).

```bash Всего сканирований, последние 30 дней theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash Уникальные сканирования 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 По странам, последние 7 дней 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`

Возвращает статистику сканирований по всем QR-кодам вашего рабочего пространства. Принимает описанные выше [параметры запроса](#параметры-запроса) и [фильтры по измерениям](#фильтры-по-измерениям), а также эти параметры для ограничения выборки.

**domain** `string`

Вместе с `key` ограничивает результаты короткой ссылкой с этим доменом, например `getqr.sh`. Домен должен принадлежать вашему рабочему пространству.

**key** `string`

Слаг короткой ссылки, например `x7Kd2p1`. Используйте вместе с `domain`. Оба значения есть в [объекте QR-кода](https://docs.getqr.com/ru/api/endpoints/qr-codes.md).

**qrType** `string`

Типы QR-кодов через запятую: `website`, `pdf`, `image`, `video`, `whatsapp`, `social`, `wifi`, `app`, `feedback`, `vcard`, `sms`, `payment`, `location`, `multilink`, `email` или `event`. См. [Типы QR-кодов](https://docs.getqr.com/ru/api/guides/qr-types.md).

```bash Устройства, последние 7 дней theme={null}
curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash Устройства, только QR-коды website theme={null}
curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=30d&qrType=website" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash Одна короткая ссылка 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."
>
> У QR-кода нет короткой ссылки, поэтому считать нечего.

> [accordion] 404 при фильтрации по domain и key
>
> В вашем рабочем пространстве нет короткой ссылки с таким доменом и слагом. Скопируйте `domain` и `key` из объекта QR-кода.

> [accordion] 422 на groupBy, interval или фильтр
>
> Значение не поддерживается. Сообщение об ошибке называет параметр и перечисляет допустимые значения.

> [accordion] Числа не совпадают с панелью управления
>
> Проверьте, что используете тот же диапазон дат и часовой пояс, и что считаете: уникальные сканирования (`unique=true`) или все.

## Что дальше

> [card] [Отчёты](https://docs.getqr.com/ru/api/endpoints/reports.md)

> [card] [QR-коды](https://docs.getqr.com/ru/api/endpoints/qr-codes.md)

> [card] [Аналитика в приложении](https://docs.getqr.com/ru/analytics/overview.md)

> [card] [Ограничения частоты запросов](https://docs.getqr.com/ru/api/rate-limits.md)


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