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

# Analytiikka

> Skannaustilastot yhdelle QR-koodille tai koko työtilallesi.

> [!NOTE]
>
> GetQR API on beetavaiheessa, ja se on käytettävissä valituissa työtiloissa. Yksityiskohdat voivat muuttua ennen yleistä julkaisua.

Hae skannausten kokonaismäärät ja erittelyt maittain, laitteittain, selaimittain ja muilla tavoin yhdelle QR-koodille tai koko työtilallesi.

| Metodi | Polku | Kuvaus |
| - | - | - |
| `GET` | `/api/v1/qrs/{qrId}/analytics` | [Hae QR-koodin analytiikka](#hae-qr-koodin-analytiikka) |
| `GET` | `/api/v1/analytics` | [Hae työtilan analytiikka](#hae-työtilan-analytiikka) |

Valmis QR-koodikohtainen yhteenveto on kohdassa [Raportit](https://docs.getqr.com/fi/api/endpoints/reports.md).

## Mitä luvut tarkoittavat

* **Skannaukset.** Jokainen määrä on kentässä `clicks`. Skannaus lasketaan aina, kun joku avaa QR-koodin lyhytlinkin.
* **Yksilölliset skannaukset.** Parametrilla `unique=true` kukin kävijä lasketaan aikavälillä kerran.
* **Rajaus.** Luvut tulevat QR-koodin lyhytlinkistä. QR-koodilla, jolla ei ole lyhytlinkkiä, ei ole laskettavia skannauksia.
* **Historia.** Analytiikkaa ei voi nollata API:n kautta. QR-koodin poistaminen ei poista sen skannaushistoriaa.

## Otsakkeet

**Authorization** `string` *required*

`Bearer` ja sen perässä API-avaimesi. Katso [Todennus](https://docs.getqr.com/fi/api/authentication.md).

## Kyselyparametrit

Molemmat päätepisteet ottavat nämä parametrit. Kaikki ovat valinnaisia.

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

Erittelyulottuvuus. `count` palauttaa kokonaismäärän. Kaikki arvot ja niiden vastausten rakenne ovat kohdassa [Erittelyt](#erittelyt).

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

Esimääritetty aikaväli: `24h`, `7d`, `30d`, `90d`, `1y`, `mtd`, `qtd`, `ytd` tai `all`. Katso [Aikavälit](#aikavälit). Ohitetaan, kun lähetät parametrin `start`.

**start** `string`

Mukautetun välin alku, ISO 8601, esimerkiksi `2026-08-01` tai `2026-08-01T00:00:00Z`. Ohittaa parametrin `interval`. On oltava aiempi kuin `end`.

**end** `string`

Mukautetun välin loppu, ISO 8601. Oletus on kuluvan päivän loppu. Käytetään yhdessä parametrin `start` tai arvon `interval=all` kanssa, ja muiden aikavälien kanssa se ohitetaan.

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

IANA-aikavyöhyke, jonka mukaan `timeseries`-jaksot kohdistetaan, esimerkiksi `America/New_York`. Tuntematon aikavyöhyke palauttaa `422`.

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

`true` laskee yksilölliset skannaukset kaikkien skannausten sijaan.

Voit lähettää myös [ulottuvuussuodattimia](#ulottuvuussuodattimet).

## Aikavälit

| `interval` | Kattaa | `timeseries`-jaksot |
| - | - | - |
| `24h` | Viimeiset 24 tuntia | Tunnit |
| `7d` | Viimeiset 7 päivää tänään mukaan lukien | Päivät |
| `30d` | Viimeiset 30 päivää tänään mukaan lukien | Päivät |
| `90d` | Viimeiset 90 päivää tänään mukaan lukien | Päivät |
| `1y` | Viimeiset 365 päivää tänään mukaan lukien | Kuukaudet |
| `mtd` | Kuluva kuukausi tähän päivään asti | Päivät |
| `qtd` | Kuluva vuosineljännes tähän päivään asti | Päivät |
| `ytd` | Kuluva vuosi tähän päivään asti | Päivät, tai kuukaudet 180 päivän jälkeen |
| `all` | Työtilasi luomisesta lähtien | Päivät, tai kuukaudet 180 päivän jälkeen |

Lähetä mukautettua aikaväliä varten `start` ja halutessasi `end`. Enintään 2 päivän välit käyttävät tuntijaksoja, yli 180 päivän välit kuukausijaksoja ja kaikki siltä väliltä päiväjaksoja.

## Ulottuvuussuodattimet

Rajaa tulokset skannauksiin, jotka vastaavat suodatinta. Eri suodattimet yhdistetään AND-ehdolla. Kun suodatin ottaa useita arvoja, erottele ne pilkuilla: arvot yhdistetään OR-ehdolla.

| Suodatin | Arvo | Useita arvoja |
| - | - | - |
| `country` | ISO 3166-1 alpha-2 -maakoodi, esimerkiksi `US` | Kyllä |
| `region` | ISO 3166-2 -aluekoodi, esimerkiksi `US-CA` | Kyllä |
| `city` | Kaupungin nimi, esimerkiksi `New York` | Kyllä |
| `continent` | `AF`, `AN`, `AS`, `EU`, `NA`, `OC` tai `SA` | Kyllä |
| `device` | Laitetyyppi, esimerkiksi `Mobile` tai `Desktop` | Kyllä |
| `browser` | Selaimen nimi, esimerkiksi `Chrome` | Kyllä |
| `os` | Käyttöjärjestelmä, esimerkiksi `iOS` tai `Windows` | Kyllä |
| `url` | Kohde-URL | Kyllä |
| `referer` | Viittaaja, esimerkiksi `google.com` | Ei |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` | UTM-arvo, enintään 190 merkkiä | Ei |

Tuntematon maa- tai maanosakoodi palauttaa `422`. Laitteiden, selainten ja käyttöjärjestelmien nimet täsmätään isolla alkukirjaimella, joten `mobile` toimii kuten `Mobile`.

Esimerkiksi skannaukset Yhdysvalloista tai Kanadasta mobiililaitteilla: `?country=US,CA&device=Mobile`.

## Erittelyt

`count` palauttaa objektin. Kaikki muut arvot palauttavat taulukon, joka on lajiteltu `clicks`-arvon mukaan suurimmasta pienimpään (`timeseries` on lajiteltu ajan mukaan).

| `groupBy` | Kukin kohde sisältää |
| - | - |
| `count` | `clicks` (objekti, ei taulukko) |
| `timeseries` | `start` (jakson alku), `clicks` |
| `continents` | `continent`, `clicks` |
| `regions` | `region`, `country`, `clicks` |
| `countries` | `country`, `city` (aina `*`), `clicks` |
| `cities` | `city`, `country`, `clicks` |
| `devices` | `device`, `clicks` |
| `browsers` | `browser`, `clicks` |
| `os` | `os`, `clicks` |
| `triggers` | `trigger` (`qr` tai `link`), `clicks` |
| `referers` | `referer` (`(direct)`, kun tuntematon), `clicks` |
| `referer_urls` | `refererUrl` (`(direct)`, kun tuntematon), `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-arvo (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term` tai `utm_content`), `clicks` |

Tuntematon `groupBy` palauttaa `422` ja luettelon kelvollisista arvoista.

Vastaus, kun `groupBy=count`:

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

Vastaus, kun `groupBy=countries`:

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

## Hae QR-koodin analytiikka

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

Palauttaa yhden QR-koodin skannaustilastot rajattuna sen lyhytlinkkiin. Ottaa yllä kuvatut [kyselyparametrit](#kyselyparametrit) ja [ulottuvuussuodattimet](#ulottuvuussuodattimet).

**qrId** `string` *required*

QR-koodin tunnus. Ota se [QR-koodien](https://docs.getqr.com/fi/api/endpoints/qr-codes.md) listauksen tai luonnin vastauksesta.

```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
}
```

## Hae työtilan analytiikka

`GET /api/v1/analytics`

Palauttaa skannaustilastot kaikista työtilasi QR-koodeista. Ottaa yllä kuvatut [kyselyparametrit](#kyselyparametrit) ja [ulottuvuussuodattimet](#ulottuvuussuodattimet) sekä nämä rajausparametrit.

**domain** `string`

Yhdessä parametrin `key` kanssa rajaa tulokset lyhytlinkkiin, jolla on tämä verkkotunnus, esimerkiksi `getqr.sh`. Verkkotunnuksen on kuuluttava työtilaasi.

**key** `string`

Lyhytlinkin slug, esimerkiksi `x7Kd2p1`. Käytä sitä yhdessä parametrin `domain` kanssa. Molemmat löytyvät [QR-koodiobjektista](https://docs.getqr.com/fi/api/endpoints/qr-codes.md).

**qrType** `string`

Pilkuilla erotellut mukaan otettavat QR-koodityypit: `website`, `pdf`, `image`, `video`, `whatsapp`, `social`, `wifi`, `app`, `feedback`, `vcard`, `sms`, `payment`, `location`, `multilink`, `email` tai `event`. Katso [QR-tyypit](https://docs.getqr.com/fi/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 }
]
```

## Yleisiä ongelmia

> [accordion] 400 "QR has no associated link."
>
> QR-koodilla ei ole lyhytlinkkiä, joten laskettavia skannauksia ei ole.

> [accordion] 404, kun suodatan verkkotunnuksella ja avaimella
>
> Työtilassasi ei ole lyhytlinkkiä, jolla on tämä verkkotunnus ja slug. Kopioi `domain` ja `key` QR-koodiobjektista.

> [accordion] 422 parametrista groupBy, interval tai suodattimesta
>
> Arvoa ei tueta. Virheviesti nimeää parametrin ja luettelee kelvolliset arvot.

> [accordion] Luvut eivät täsmää hallintapaneelin kanssa
>
> Tarkista, että käytät samaa aikaväliä ja aikavyöhykettä ja lasketko yksilölliset skannaukset (`unique=true`) vai kaikki skannaukset.

## Mitä seuraavaksi

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

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

> [card] [Analytiikka sovelluksessa](https://docs.getqr.com/fi/analytics/overview.md)

> [card] [Käyttörajoitukset](https://docs.getqr.com/fi/api/rate-limits.md)


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