5.6 KiB

Raw Blame History

YouTube Analytics API: Core Metrics Dimensions

1. Core Metrics (측정항목)

API 요청 시 metrics 파라미터에 들어갈 수 있는 값들입니다. 이들은 모두 숫자로 반환됩니다.

A. 시청 및 도달 (Views Reach)

가장 기본이 되는 성과 지표입니다.

Metric ID	설명 (한글/영문)	단위	비고
`views`	조회수 (Views)	횟수	가장 기본 지표
`estimatedMinutesWatched`	예상 시청 시간	분 (Minutes)	초 단위가 아님에 주의
`averageViewDuration`	평균 시청 지속 시간	초 (Seconds)	영상 1회당 평균 시청 시간
`averageViewPercentage`	평균 시청 비율	% (0~100)	영상 길이 대비 시청 비율

B. 참여 및 반응 (Engagement)

시청자의 능동적인 행동 지표입니다.

Metric ID	설명 (한글/영문)	단위	비고
`likes`	좋아요 (Likes)	횟수
`dislikes`	싫어요 (Dislikes)	횟수
`comments`	댓글 수 (Comments)	횟수
`shares`	공유 수 (Shares)	횟수	공유 버튼 클릭 횟수
`subscribersGained`	신규 구독자	명	해당 영상으로 유입된 구독자
`subscribersLost`	이탈 구독자	명	해당 영상 시청 후 구독 취소

C. 수익 (Revenue) - 수익 창출 채널 전용(유튜브파트너프로그램(YPP) 사용자만 가능)

Metric ID	설명 (한글/영문)	단위	비고
`estimatedRevenue`	총 예상 수익	통화 (예: USD, KRW)	광고 + 유튜브 프리미엄 등 포함
`estimatedAdRevenue`	광고 수익	통화	순수 광고 수익
`monetizedPlaybacks`	수익 창출 재생 수	횟수	광고가 1회 이상 노출된 재생

2. Dimensions (차원)

API 요청 시 dimensions 파라미터에 들어갈 수 있는 값들입니다.

A. 시간 및 영상 기준 (Time Item)

가장 많이 사용되는 필수 차원입니다.

Dimension ID	설명	사용 예시 (Use Case)	필수 정렬(Sort)
`day`	일별 (Daily)	최근 30일 조회수 추이 그래프	`day`
`month`	월별 (Monthly)	월간 성장 리포트	`month`
`video`	영상별 (Per Video)	인기 영상 랭킹 (Top Content)	`-views`
(없음)	전체 합계 (Total)	프로젝트 전체 성과 요약 (KPI)	(없음)

B. 시청자 분석 (Demographics)

주의: 이 차원들은 대부분 video 차원과 함께 사용할 수 없으며, 별도로 호출해야 합니다.

Dimension ID	설명	사용 예시	비고
`ageGroup`	연령대	시청자 연령 분포 (18-24, 25-34...)	`video`와 혼용 불가
`gender`	성별	남녀 성비 (male, female)	`video`와 혼용 불가
`country`	국가	국가별 시청자 수 (KR, US...)	지도 차트용

C. 유입 및 기기 (Traffic Device)

Dimension ID	설명	반환 값 예시
`insightTrafficSourceType`	유입 경로	`YT_SEARCH` (검색), `RELATED_VIDEO` (추천)
`deviceType`	기기 유형	`MOBILE`, `DESKTOP`, `TV`

3. 자주 쓰는 조합 (Best Practice)

프로젝트 전체 요약 (KPI)

dimensions: (없음)
- metrics: views,likes,estimatedRevenue
- filters: video==ID1,ID2...

일별 성장 그래프 (Line Chart)

dimensions: day
- metrics: views
- filters: video==ID1,ID2...
- sort: day

인기 영상 랭킹 (Table)

dimensions: video
- metrics: views,averageViewDuration
- filters: video==ID1,ID2...
- sort: -views

4. API 사용 시 주의사항 및 제약사항

A. 영상 ID 개수 제한

권장: 최근 생성된 영상 20~30개(최대 50개)를 DB에서 가져오고 해당 목록을 API로 호출
Analytics API 공식 한도: 명시된 개수 제한은 없지만 URL 길이 제한 2000자 (이론상 최대 150개)
실질적 제한: Analytics API는 계산이 복잡하여 ID 150개를 한 번에 던지면, 유튜브 서버 응답 시간(Latency)이 길어지고 50개 이상일 때 문제가 발생한다는 StackOverflow의 보고가 있음
Data API 비교: 같은 유튜브의 Data API는 videos.list 50개 제한

B. 데이터 지연 (Latency)

Analytics API 데이터는 실시간이 아니며 24~48시간 지연(Latency) 발생
최신 데이터가 필요한 경우 이 점을 고려해야 함