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

# Statistiche

> Statistiche delle scansioni per un singolo QR code o per l'intero workspace.

> [!NOTE]
>
> L'API di GetQR è in beta ed è disponibile per alcuni workspace selezionati. I dettagli possono cambiare prima del rilascio generale.

Ottieni i totali delle scansioni e le suddivisioni per paese, dispositivo, browser e altro, per un singolo QR code o per tutto il workspace.

| Metodo | Percorso | Descrizione |
| - | - | - |
| `GET` | `/api/v1/qrs/{qrId}/analytics` | [Ottieni le statistiche di un QR code](#ottieni-le-statistiche-di-un-qr-code) |
| `GET` | `/api/v1/analytics` | [Ottieni le statistiche del workspace](#ottieni-le-statistiche-del-workspace) |

Per un riepilogo pronto per ogni QR code, consulta [Report](https://docs.getqr.com/it/api/endpoints/reports.md).

## Cosa significano i numeri

* **Scansioni.** Ogni conteggio si trova nel campo `clicks`. Una scansione viene conteggiata ogni volta che qualcuno apre il link breve del QR code.
* **Scansioni uniche.** Con `unique=true`, ogni visitatore viene conteggiato una sola volta nell'intervallo di date.
* **Ambito.** I numeri provengono dal link breve del QR code. Un QR code senza link breve non ha scansioni da conteggiare.
* **Cronologia.** Le statistiche non possono essere azzerate tramite l'API. L'eliminazione di un QR code non cancella i dati storici delle sue scansioni.

## Header

**Authorization** `string` *required*

`Bearer` seguito dalla tua chiave API. Consulta [Autenticazione](https://docs.getqr.com/it/api/authentication.md).

## Parametri di query

Entrambi gli endpoint accettano questi parametri. Sono tutti facoltativi.

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

Dimensione di suddivisione. `count` restituisce il totale. Consulta [Suddivisioni](#suddivisioni) per tutti i valori e la struttura della risposta.

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

Intervallo di date predefinito: `24h`, `7d`, `30d`, `90d`, `1y`, `mtd`, `qtd`, `ytd` o `all`. Consulta [Intervalli di date](#intervalli-di-date). Ignorato quando invii `start`.

**start** `string`

Inizio di un intervallo personalizzato, ISO 8601, ad esempio `2026-08-01` o `2026-08-01T00:00:00Z`. Ha la precedenza su `interval`. Deve essere precedente a `end`.

**end** `string`

Fine di un intervallo personalizzato, ISO 8601. Predefinito: la fine della giornata di oggi. Si usa insieme a `start` o a `interval=all`, e viene ignorato con gli altri intervalli.

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

Fuso orario IANA usato per allineare i periodi di `timeseries`, ad esempio `America/New_York`. Un fuso orario sconosciuto restituisce `422`.

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

`true` conteggia le scansioni uniche invece delle scansioni totali.

Puoi anche inviare [filtri di dimensione](#filtri-di-dimensione).

## Intervalli di date

| `interval` | Copre | Periodi di `timeseries` |
| - | - | - |
| `24h` | Le ultime 24 ore | Ore |
| `7d` | Gli ultimi 7 giorni, oggi incluso | Giorni |
| `30d` | Gli ultimi 30 giorni, oggi incluso | Giorni |
| `90d` | Gli ultimi 90 giorni, oggi incluso | Giorni |
| `1y` | Gli ultimi 365 giorni, oggi incluso | Mesi |
| `mtd` | Dall'inizio del mese | Giorni |
| `qtd` | Dall'inizio del trimestre | Giorni |
| `ytd` | Dall'inizio dell'anno | Giorni, o mesi oltre i 180 giorni |
| `all` | Dalla creazione del tuo workspace | Giorni, o mesi oltre i 180 giorni |

Per un intervallo personalizzato, invia `start` e, se vuoi, `end`. Gli intervalli fino a 2 giorni usano periodi orari, quelli oltre i 180 giorni periodi mensili, e tutti gli altri periodi giornalieri.

## Filtri di dimensione

Limita i risultati alle scansioni che corrispondono a un filtro. Filtri diversi vengono combinati con AND. Quando un filtro accetta più valori, separali con virgole: i valori vengono combinati con OR.

| Filtro | Valore | Più valori |
| - | - | - |
| `country` | Codice paese ISO 3166-1 alpha-2, ad esempio `US` | Sì |
| `region` | Codice regione ISO 3166-2, ad esempio `US-CA` | Sì |
| `city` | Nome della città, ad esempio `New York` | Sì |
| `continent` | `AF`, `AN`, `AS`, `EU`, `NA`, `OC` o `SA` | Sì |
| `device` | Tipo di dispositivo, ad esempio `Mobile` o `Desktop` | Sì |
| `browser` | Nome del browser, ad esempio `Chrome` | Sì |
| `os` | Sistema operativo, ad esempio `iOS` o `Windows` | Sì |
| `url` | URL di destinazione | Sì |
| `referer` | Referrer, ad esempio `google.com` | No |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` | Valore UTM, fino a 190 caratteri | No |

Un codice paese o continente sconosciuto restituisce `422`. I nomi di dispositivi, browser e sistemi operativi vengono confrontati con l'iniziale maiuscola, quindi `mobile` funziona come `Mobile`.

Ad esempio, le scansioni da Stati Uniti o Canada su dispositivi mobili: `?country=US,CA&device=Mobile`.

## Suddivisioni

`count` restituisce un oggetto. Tutti gli altri valori restituiscono un array, ordinato per `clicks` dal più alto al più basso (`timeseries` è ordinato per tempo).

| `groupBy` | Ogni elemento contiene |
| - | - |
| `count` | `clicks` (un oggetto, non un array) |
| `timeseries` | `start` (inizio del periodo), `clicks` |
| `continents` | `continent`, `clicks` |
| `regions` | `region`, `country`, `clicks` |
| `countries` | `country`, `city` (sempre `*`), `clicks` |
| `cities` | `city`, `country`, `clicks` |
| `devices` | `device`, `clicks` |
| `browsers` | `browser`, `clicks` |
| `os` | `os`, `clicks` |
| `triggers` | `trigger` (`qr` o `link`), `clicks` |
| `referers` | `referer` (`(direct)` se sconosciuto), `clicks` |
| `referer_urls` | `refererUrl` (`(direct)` se sconosciuto), `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` | Il valore UTM (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term` o `utm_content`), `clicks` |

Un `groupBy` sconosciuto restituisce `422` con l'elenco dei valori validi.

Risposta con `groupBy=count`:

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

Risposta con `groupBy=countries`:

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

## Ottieni le statistiche di un QR code

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

Restituisce le statistiche delle scansioni di un QR code, limitate al suo link breve. Accetta i [parametri di query](#parametri-di-query) e i [filtri di dimensione](#filtri-di-dimensione) descritti sopra.

**qrId** `string` *required*

ID del QR code. Prendilo dalla risposta dell'elenco o della creazione dei [QR code](https://docs.getqr.com/it/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
}
```

## Ottieni le statistiche del workspace

`GET /api/v1/analytics`

Restituisce le statistiche delle scansioni di tutti i QR code del tuo workspace. Accetta i [parametri di query](#parametri-di-query) e i [filtri di dimensione](#filtri-di-dimensione) descritti sopra, più questi parametri per limitare l'ambito.

**domain** `string`

Insieme a `key`, limita i risultati al link breve con questo dominio, ad esempio `getqr.sh`. Il dominio deve appartenere al tuo workspace.

**key** `string`

Slug del link breve, ad esempio `x7Kd2p1`. Usalo insieme a `domain`. Entrambi si trovano nell'[oggetto QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md).

**qrType** `string`

Tipi di QR code da includere, separati da virgole: `website`, `pdf`, `image`, `video`, `whatsapp`, `social`, `wifi`, `app`, `feedback`, `vcard`, `sms`, `payment`, `location`, `multilink`, `email` o `event`. Consulta [Tipi di QR](https://docs.getqr.com/it/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 }
]
```

## Problemi comuni

> [accordion] 400 "QR has no associated link."
>
> Il QR code non ha un link breve, quindi non ci sono scansioni da conteggiare.

> [accordion] 404 quando filtro per domain e key
>
> Nel tuo workspace non esiste un link breve con quel dominio e quello slug. Copia `domain` e `key` dall'oggetto QR code.

> [accordion] 422 su groupBy, interval o un filtro
>
> Il valore non è supportato. Il messaggio di errore indica il parametro ed elenca i valori validi.

> [accordion] I numeri non corrispondono a quelli della dashboard
>
> Verifica di usare lo stesso intervallo di date e lo stesso fuso orario, e se stai conteggiando le scansioni uniche (`unique=true`) o quelle totali.

## Passaggi successivi

> [card] [Report](https://docs.getqr.com/it/api/endpoints/reports.md)

> [card] [QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md)

> [card] [Statistiche nell'app](https://docs.getqr.com/it/analytics/overview.md)

> [card] [Limiti di frequenza](https://docs.getqr.com/it/api/rate-limits.md)


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