> ## 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]
>
> API GetQR перебуває в бета-версії та доступний для окремих робочих просторів. До загального релізу деталі можуть змінитися.

Отримуйте загальну кількість сканувань і розбивки за країною, пристроєм, браузером та іншими вимірами — для одного QR-коду або для всього робочого простору.

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

Готове зведення для кожного QR-коду див. у розділі [Звіти](https://docs.getqr.com/ua/api/endpoints/reports.md).

## Що означають числа

* **Сканування.** Кожна кількість міститься в полі `clicks`. Сканування зараховується щоразу, коли хтось відкриває коротке посилання QR-коду.
* **Унікальні сканування.** З `unique=true` кожен відвідувач рахується один раз у межах діапазону дат.
* **Охоплення.** Числа беруться з короткого посилання QR-коду. QR-код без короткого посилання не має сканувань, які можна порахувати.
* **Історія.** Аналітику не можна скинути через API. Видалення QR-коду не стирає історичні дані його сканувань.

## Заголовки

**Authorization** `string` *required*

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

Slug короткого посилання, наприклад `x7Kd2p1`. Використовуйте його разом із `domain`. Обидва значення є в [об'єкті QR-коду](https://docs.getqr.com/ua/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/ua/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
>
> У вашому робочому просторі немає короткого посилання з таким доменом і slug. Скопіюйте `domain` і `key` з об'єкта QR-коду.

> [accordion] 422 для groupBy, interval або фільтра
>
> Значення не підтримується. Повідомлення про помилку називає параметр і перелічує допустимі значення.

> [accordion] Числа не збігаються з панеллю керування
>
> Перевірте, що ви використовуєте той самий діапазон дат і часовий пояс, і чи рахуєте ви унікальні сканування (`unique=true`) або загальну кількість.

## Що далі

> [card] [Звіти](https://docs.getqr.com/ua/api/endpoints/reports.md)

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

> [card] [Аналітика в застосунку](https://docs.getqr.com/ua/analytics/overview.md)

> [card] [Обмеження частоти запитів](https://docs.getqr.com/ua/api/rate-limits.md)


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