> ## 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/ko/api/endpoints/reports.md)를 참조하세요.

## 수치의 의미

* **스캔.** 모든 집계는 `clicks` 필드에 담깁니다. 누군가 QR 코드의 단축 링크를 열 때마다 스캔이 집계됩니다.
* **고유 스캔.** `unique=true`를 지정하면 기간 내에서 방문자마다 한 번만 집계됩니다.
* **범위.** 수치는 QR 코드의 단축 링크에서 집계됩니다. 단축 링크가 없는 QR 코드에는 집계할 스캔이 없습니다.
* **기록.** API로 분석을 초기화할 수 없습니다. QR 코드를 삭제해도 과거 스캔 데이터는 지워지지 않습니다.

## 헤더

**Authorization** `string` *required*

`Bearer` 뒤에 API 키를 붙입니다. [인증](https://docs.getqr.com/ko/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` | 이번 달 1일부터 오늘까지 | 일 |
| `qtd` | 이번 분기 시작일부터 오늘까지 | 일 |
| `ytd` | 올해 1월 1일부터 오늘까지 | 일, 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`를 반환합니다. 기기, 브라우저, 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`

QR 코드 하나의 스캔 통계를 해당 단축 링크 범위에서 반환합니다. 위의 [쿼리 매개변수](#쿼리-매개변수)와 [차원 필터](#차원-필터)를 받습니다.

**qrId** `string` *required*

QR 코드의 ID입니다. [QR 코드](https://docs.getqr.com/ko/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/ko/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/ko/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/ko/api/endpoints/reports.md)

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

> [card] [앱의 분석](https://docs.getqr.com/ko/analytics/overview.md)

> [card] [요청 한도](https://docs.getqr.com/ko/api/rate-limits.md)


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