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. 현재 사용 중인 API 호출 조합
대시보드에서 실제로 사용하는 7가지 호출 조합입니다. 모두 ids=channel==MINE으로 고정합니다.
1. KPI 요약 (_fetch_kpi) — 현재/이전 기간 각 1회
| 파라미터 |
값 |
| dimensions |
(없음) |
| metrics |
views, likes, comments, shares, estimatedMinutesWatched, averageViewDuration, subscribersGained |
| filters |
video==ID1,ID2,... (업로드된 영상 ID 최대 30개) |
현재/이전 기간을 각각 호출하여 trend(증감률) 계산에 사용.
2. 월별 추이 차트 (_fetch_monthly_data) — 최근 12개월 / 이전 12개월 각 1회
| 파라미터 |
값 |
| dimensions |
month |
| metrics |
views |
| filters |
video==ID1,ID2,... |
| sort |
month |
3. 일별 추이 차트 (_fetch_daily_data) — 최근 30일 / 이전 30일 각 1회
| 파라미터 |
값 |
| dimensions |
day |
| metrics |
views |
| filters |
video==ID1,ID2,... |
| sort |
day |
4. 인기 영상 TOP 4 (_fetch_top_videos)
| 파라미터 |
값 |
| dimensions |
video |
| metrics |
views, likes, comments |
| filters |
video==ID1,ID2,... |
| sort |
-views |
| maxResults |
4 |
5. 시청자 연령/성별 분포 (_fetch_demographics) — 채널 전체 기준
| 파라미터 |
값 |
| dimensions |
ageGroup, gender |
| metrics |
viewerPercentage |
ageGroup, gender 차원은 video 필터와 혼용 불가 → 채널 전체 시청자 기준.
6. 지역별 조회수 TOP 5 (_fetch_region) — 채널 전체 기준
| 파라미터 |
값 |
| dimensions |
country |
| metrics |
views |
| sort |
-views |
| maxResults |
5 |
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) 발생
- 최신 데이터가 필요한 경우 이 점을 고려해야 함