분석 - GetQR Docs

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d&unique=true" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=countries&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "clicks": 142
}

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d&unique=true" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=countries&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "clicks": 142
}

GetQR API는 베타 버전이며 일부 워크스페이스에서만 사용할 수 있습니다. 정식 출시 전에 세부 사항이 변경될 수 있습니다.

QR 코드 하나 또는 워크스페이스 전체를 대상으로 스캔 합계와 국가, 기기, 브라우저 등의 세부 분류를 조회합니다.

메서드	경로	설명
`GET`	`/api/v1/qrs/{qrId}/analytics`	QR 코드 분석 조회
`GET`	`/api/v1/analytics`	워크스페이스 분석 조회

QR 코드별로 정리된 요약이 필요하면 보고서를 참조하세요.

수치의 의미

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

헤더

string

필수

Bearer 뒤에 API 키를 붙입니다. 인증을 참조하세요.

쿼리 매개변수

두 엔드포인트 모두 다음 매개변수를 받습니다. 모두 선택 사항입니다.

string

기본값:"count"

세부 분류 기준입니다. count는 합계를 반환합니다. 모든 값과 응답 구조는 세부 분류를 참조하세요.

string

기본값:"30d"

미리 정의된 기간: 24h, 7d, 30d, 90d, 1y, mtd, qtd, ytd, all. 기간을 참조하세요. start를 보내면 무시됩니다.

string

사용자 지정 기간의 시작(ISO 8601)입니다. 예: 2026-08-01 또는 2026-08-01T00:00:00Z. interval보다 우선합니다. end보다 앞서야 합니다.

string

사용자 지정 기간의 종료(ISO 8601)입니다. 기본값은 오늘의 끝입니다. start 또는 interval=all과 함께 사용하며, 다른 interval에서는 무시됩니다.

string

기본값:"UTC"

timeseries 버킷을 맞추는 데 사용하는 IANA 시간대입니다. 예: America/New_York. 알 수 없는 시간대는 422를 반환합니다.

boolean

기본값:"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일 때의 응답:

{ "clicks": 142 }

groupBy=countries일 때의 응답:

[
  { "country": "US", "city": "*", "clicks": 87 },
  { "country": "DE", "city": "*", "clicks": 31 },
  { "country": "GB", "city": "*", "clicks": 24 }
]

QR 코드 분석 조회

GET /api/v1/qrs/{qrId}/analytics QR 코드 하나의 스캔 통계를 해당 단축 링크 범위에서 반환합니다. 위의 쿼리 매개변수와 차원 필터를 받습니다.

string

필수

QR 코드의 ID입니다. QR 코드의 목록 조회 또는 생성 응답에서 가져오세요.

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d&unique=true" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=countries&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "clicks": 142
}

워크스페이스 분석 조회

GET /api/v1/analytics 워크스페이스의 모든 QR 코드를 대상으로 스캔 통계를 반환합니다. 위의 쿼리 매개변수와 차원 필터에 더해 다음 범위 지정 매개변수를 받습니다.

string

key와 함께 사용하여 이 도메인의 단축 링크로 결과를 제한합니다. 예: getqr.sh. 도메인은 워크스페이스에 속해야 합니다.

string

단축 링크 슬러그입니다. 예: x7Kd2p1. domain과 함께 사용하세요. 둘 다 QR 코드 객체에 있습니다.

string

포함할 QR 코드 유형을 쉼표로 구분해 지정합니다: website, pdf, image, video, whatsapp, social, wifi, app, feedback, vcard, sms, payment, location, multilink, email, event. QR 코드 유형을 참조하세요.

curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=30d&qrType=website" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/analytics?groupBy=count&domain=getqr.sh&key=x7Kd2p1" \
  -H "Authorization: Bearer $GETQR_API_KEY"

[
  { "device": "Mobile", "clicks": 980 },
  { "device": "Desktop", "clicks": 240 }
]

자주 발생하는 문제

400 "QR has no associated link."

QR 코드에 단축 링크가 없으므로 집계할 스캔이 없습니다.

domain과 key로 필터링하면 404가 반환됩니다

해당 도메인과 슬러그를 가진 단축 링크가 워크스페이스에 없습니다. QR 코드 객체에서 domain과 key를 복사하세요.

groupBy, interval 또는 필터에서 422가 반환됩니다

지원하지 않는 값입니다. 오류 메시지에 매개변수 이름과 유효한 값 목록이 표시됩니다.

수치가 대시보드와 일치하지 않습니다

같은 기간과 시간대를 사용하는지, 고유 스캔(unique=true)과 전체 스캔 중 무엇을 집계하는지 확인하세요.

API

분석

수치의 의미

헤더

쿼리 매개변수

기간

차원 필터

세부 분류

QR 코드 분석 조회

워크스페이스 분석 조회

자주 발생하는 문제

다음 단계

보고서

QR 코드

앱의 분석

요청 한도

​수치의 의미

​헤더

​쿼리 매개변수

​기간

​차원 필터

​세부 분류

​QR 코드 분석 조회

​워크스페이스 분석 조회

​자주 발생하는 문제

​다음 단계

보고서

QR 코드

앱의 분석

요청 한도

수치의 의미

헤더

쿼리 매개변수

기간

차원 필터

세부 분류

QR 코드 분석 조회

워크스페이스 분석 조회

자주 발생하는 문제

다음 단계