120 lines
5.6 KiB
Markdown
120 lines
5.6 KiB
Markdown
# 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)
|
|
|
|
1. **프로젝트 전체 요약 (KPI)**
|
|
- `dimensions`: (없음)
|
|
- `metrics`: `views,likes,estimatedRevenue`
|
|
- `filters`: `video==ID1,ID2...`
|
|
2. **일별 성장 그래프 (Line Chart)**
|
|
- `dimensions`: `day`
|
|
- `metrics`: `views`
|
|
- `filters`: `video==ID1,ID2...`
|
|
- `sort`: `day`
|
|
3. **인기 영상 랭킹 (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)** 발생
|
|
- 최신 데이터가 필요한 경우 이 점을 고려해야 함
|
|
|