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

# 分析

> 1 つの QR コードまたはワークスペース全体のスキャン統計。

> [!NOTE]
>
> GetQR API はベータ版で、一部のワークスペースでのみご利用いただけます。正式リリースまでに内容が変更される場合があります。

1 つの QR コード、またはワークスペース全体について、スキャンの合計と、国、デバイス、ブラウザなどの内訳を取得します。

| メソッド | パス | 説明 |
| - | - | - |
| `GET` | `/api/v1/qrs/{qrId}/analytics` | [QR コードの分析を取得する](#qr-コードの分析を取得する) |
| `GET` | `/api/v1/analytics` | [ワークスペースの分析を取得する](#ワークスペースの分析を取得する) |

QR コードごとにまとめられた集計が必要な場合は、[レポート](https://docs.getqr.com/ja/api/endpoints/reports.md) をご覧ください。

## 数値の意味

* **スキャン。** すべてのカウントは `clicks` フィールドに入ります。スキャンは、誰かが QR コードの短縮リンクを開くたびにカウントされます。
* **ユニークスキャン。** `unique=true` を指定すると、期間内で各訪問者が 1 回だけカウントされます。
* **対象範囲。** 数値は QR コードの短縮リンクから集計されます。短縮リンクのない QR コードには、カウントするスキャンがありません。
* **履歴。** API で分析をリセットすることはできません。QR コードを削除しても、過去のスキャンデータは消去されません。

## ヘッダー

**Authorization** `string` *required*

`Bearer` の後に API キーを続けます。[認証](https://docs.getqr.com/ja/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` と組み合わせて使い、それ以外の interval では無視されます。

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

`timeseries` のバケットを揃えるための IANA タイムゾーン。例：`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` | OS。例：`iOS`、`Windows` | 可 |
| `url` | リンク先の URL | 可 |
| `referer` | リファラー。例：`google.com` | 不可 |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` | UTM の値。最大 190 文字 | 不可 |

不明な国コードや大陸コードは `422` を返します。デバイス、ブラウザ、OS の名前は先頭を大文字にして照合されるため、`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`

1 つの QR コードのスキャン統計を、その短縮リンクの範囲で返します。上記の [クエリパラメータ](#クエリパラメータ) と [ディメンションフィルター](#ディメンションフィルター) を受け付けます。

**qrId** `string` *required*

QR コードの ID。[QR コード](https://docs.getqr.com/ja/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
}
```

## ワークスペースの分析を取得する

`GET /api/v1/analytics`

ワークスペースのすべての QR コードを対象にスキャン統計を返します。上記の [クエリパラメータ](#クエリパラメータ) と [ディメンションフィルター](#ディメンションフィルター) に加えて、次の範囲指定パラメータを受け付けます。

**domain** `string`

`key` と組み合わせて、このドメインの短縮リンクに結果を絞り込みます。例：`getqr.sh`。ドメインはワークスペースに属している必要があります。

**key** `string`

短縮リンクのスラッグ。例：`x7Kd2p1`。`domain` と組み合わせて使います。どちらも [QR コードオブジェクト](https://docs.getqr.com/ja/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/ja/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 }
]
```

## よくある問題

> [accordion] 400 "QR has no associated link."
>
> QR コードに短縮リンクがないため、カウントするスキャンがありません。

> [accordion] domain と key で絞り込むと 404 になる
>
> そのドメインとスラッグの短縮リンクは、ワークスペースに存在しません。QR コードオブジェクトから `domain` と `key` をコピーしてください。

> [accordion] groupBy、interval、フィルターで 422 になる
>
> その値はサポートされていません。エラーメッセージに、パラメータ名と有効な値の一覧が示されます。

> [accordion] 数値がダッシュボードと一致しない
>
> 同じ期間とタイムゾーンを使っているか、ユニークスキャン（`unique=true`）と総スキャンのどちらをカウントしているかを確認してください。

## 次のステップ

> [card] [レポート](https://docs.getqr.com/ja/api/endpoints/reports.md)

> [card] [QR コード](https://docs.getqr.com/ja/api/endpoints/qr-codes.md)

> [card] [アプリでの分析](https://docs.getqr.com/ja/analytics/overview.md)

> [card] [レート制限](https://docs.getqr.com/ja/api/rate-limits.md)


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