# 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)** 발생
- 최신 데이터가 필요한 경우 이 점을 고려해야 함