유튜브 API - 19. Targeted Queries
지난 글에서 대량(Bulk)의 데이터를 조회하는 Reporting API를 살펴봤다.
본글에서는 원하는 분석 데이터를 골라서(Targeted) 조회(Query)하는 Analytics API를 살펴보자. (Analytics API에서도 보고서(Report)를 조회한다고 표현함)
유튜브 분석 API 소개 글에서 언급했듯이, 유튜에서 제공하는 분석을 위한 API는 Reporting API와 Analytics API로 구분된다.
Reporting API가 대량의 분석 데이터를 조회하기 위해서 존재한다면, Analytics API는 분석 데이터 중 필요한 부분만 찾아서 조회하고 싶을 때 필요하다.
예를 들어, 여러 개의 채널을 소유한 콘텐츠 소유자 MBC가 있다. 매일 아침 출근 전에 어제 하루 동안 MBC 모든 채널의 동영상 분석 정보(하루 동안의 조회수, 댓글 수, 좋아요 수, 평균 시청시간, 광고수익 등)를 정리한 임원용 보고서를 만들어야 한다면 Reporting API를 사용해야 한다. 그런데 모든 채널의 모든 동영상이 아닌, 수익 기준으로 상위 100개의 동영상 정보로 보고서를 만든다면 Analytics API를 사용하는 것이 훨씬 유리하다. 물론 Reporting API를 사용해도 가능은 하다. 하지만 여러 파일을 다운로드하고 열심히 가공해서 수익 기준 상위 100개의 동영상 정보를 추출하는 게 Analytics API 한번 호출하는 것보다 그다지 효율적이지는 않다. 하물며 다운로드한 파일을 무턱대고 메모리에 올려서 핸들링하다가는 힙(heap memory)과 많이 친해지는 기회가 될 수 있다.)
사실, 단일 채널이거나 채널 내 영상수가 몇 안 되는 경우 Reporting API와 Analytics API를 구분해서 사용할 이유가 많지는 않다.(굳이 찾는다면, 쿼터 최적화 정도랄까?!) 하지만, 채널을 많이 소유하고 채널 내 동영상이 많은 경우 API를 선택해서 사용해야 한다. 그렇지 않을 경우 쿼터 지옥에 빠지거나 성능 문제로 개고생의 길로 들어설 가능성이 농후하다.(맞다. 필자의 경험담이다 -_ -;)
본격적인 개발에 앞서 Analytics API의 특징에 대해 살펴보자.
Reporting API 비교
- dimesion과 metric 기준으로 데이터를 관리하는 건 두 API 모두 동일하다.
- Analytics API는 필터링, 정렬 등의 유용한 기능을 API의 매개변수로 제공하기 때문에, Reporting API 대비 Application 영역에서 처리하기 위한 코드가 상대적으로 줄어든다.
- 필터를 통해 특정 데이터만 포함되도록 조회하는 것도 가능하다.(최대 500개)
reports.query API
Analytics API는 reports.query API를 통해 호출하며, 이때 필수 매개변수가 존재한다.
> ids : YouTube 채널 또는 콘텐츠 소유자 아이디
> startDate, endDate : 조회하려는 데이터의 기간
> dimensions, metrics : 측정 항목
예를 들어, 특정 채널에서 6월~7월 동안 동영상이 어떤 기기로 얼마나 시청됐는지 조회한다고 가정하면 아래와 같이 매개변수를 설정할 수 있다.
- startDate : "2020-06-01"
- endDate : "2020-07-31"
- metrics : "views, estimatedMinutesWatched"
- dimensions : 다양한 경우의 수 조합이 가능하다.
1. "deviceType"
> 전체 기간 대해서 조회수와 시청시간(분)이 기기 유형별로 그룹 되어 조회된다.
예) 6/1~7/30까지 TV에서 시청한 정보, 6/1~7/30까지 휴대폰에서 시청한 정보 등
2. "day, deviceType"
> 조회수와 시청시간(분)이 일별, 기기 유형별로 그룹 되어 조회된다.
예) 6월 1일 휴대폰에서 시청한 정보, 7월 1일 휴대폰에서 시청한 정보 등
- filters : "channel==채널아이디"
> 채널 아이디는 콤마(,)로 최대 500개까지 한 번에 호출이 가능하다.
Analytics API 특징
- Reporting API와 비슷하게, 조회한 분석 데이터를 보고서(Report)라고 명명하며 종류가 정해져 있다.
(채널 보고서, 콘텐츠 소유자 보고서)
- reports.query API를 사용하며 매개변수를 설정한 GET 타입의 요청(HTTP Request)을 통해 데이터를 조회한다.
- dimensions과 metrics는 지원하는 보고서(채널, 콘텐츠 소유자) 별로 명시되어 있다.
> 채널 보고서 : https://developers.google.com/youtube/analytics/channel_reports
> 콘텐츠 소유자 보고서 : https://developers.google.com/youtube/analytics/content_owner_reports
- ids 매개변수는 아래 두 가지 중 하나로 입력함
> 채널 보고서 : channel==MINE, channel==CHANNEL_ID
> 콘텐츠 소유자 보고서 : channel==OWNER_NAME
- 보고서에는 헤더 데이터가 포함되어 있으며, 헤더의 순서가 바뀔 수 있으니 보고서를 조회할 때 헤더 값을 분석해서 어떤 순서대로 값이 들어있는지 반드시 확인해야 한다.
- 보고서에는 유튜브 리소스에 대한 메타 정보는 포함되어있지 않고, 이를 Data API로 찾을 수 있도록 아이디가 포함된다.(구글 정책에 따라 메타 정보는 30일 후에 반드시 지우거나 갱신해야 한다. 물론, 현실적으로 구글이 데이터의 보존 여부를 파악할 수는 없기 때문에, 추후 분쟁을 위한 대비책 정도라고 파악된다.)
- 보고서의 데이터는 태평양 표준시(UTC-8, 서머타임 -7) 기준으로 오전 12시부터 오후 11시 59분까지의 24시간 동안의 데이터가 포함된다. 즉 우리나라 기준으로 오후 5시에서 다음날 오후 4시 59분까지의 데이터인 셈(서머타임은 오후 4시 ~ 오후 3시 59분). 수집 시간 엄청 애매모호하기 때문에 수집 일자 기준을 명확히 세워야 한다. (필자의 경우 유튜브 스튜디오 분석 화면의 날짜 기준(PST)을 따랐다.)
- 보고서는 매일 새벽 04:30 ~ 05:00에 업데이트된다. 예를 들어 11/30(월) 04:30 ~ 05:00 사이에 검색하면, 11/27(금) 데이터가 조회된다. 그런데 11/27(금)은 태평양 표준시 기준이기 때문에 우리나라 시간으로 변경하면 11/27(금) 17:00 ~ 11/28(토) 16:59까지의 데이터가 11/30(월) 04:30~05:00 사이에 검색 가능하다.
Analytics API 주의점
- 삭제된 리소스에 대한 정보는 리소스 별로 조회할 경우 반환되지 않지만, 집계 데이터에는 포함된다. 예를 들어 채널 소유자가 동영상을 삭제하면 해당 동영상은 동영상 측정 항목을 반환하는 API에는 반환되지 않는다. 하지만 일자별 동영상 전체 정보를 집계하는 보고서에는 삭제된 항목과 관련된 내용이 포함된다. 때문에 집계 데이터가 항목별 데이터의 총합보다 수치가 높을 수 있다는 점을 유의해야 한다.
- 모든 데이터가 보고서에 포함되지는 않는다. 사용자의 익명성 보장하기 위해서 임계치를 충족하지 않는 값은 표시되지 않는다.(NULL 값으로 표시됨) 다음 데이터는 분석 보고서에서 제한될 수 있다.
연령 및 성별과 같은 인구 통계 데이터
국가 또는 지역과 같이 시청자가 위치한 국가 또는 지역과 관련된 측정 항목 또는 측정 기준을 포함한 지역 데이터
동영상 조회로 이어진 검색어 또는 외부 URL과 같은 특정 트래픽 소스와 관련된 측정 항목
이제 Analytics API를 사용해보자.
채널에서 특정 기간 동안 수익이 가장 많은 동영상 5개를 조회하기 위해 아래의 순서대로 진행해 보자.
1. OAuth2 인증
API를 사용하기 위해 Data API에서 사용하던 스코프 외에 아래의 스코프가 더 필요하다.
https://www.googleapis.com/auth/yt-analytics.readonly
- YouTube 콘텐츠에 대한 YouTube 분석 보고서를 조회
- 조회수 및 평점과 같은 사용자 활동 측정 항목에 대한 액세스를 제공함
https://www.googleapis.com/auth/yt-analytics-monetary.readonly
- YouTube 콘텐츠에 대한 YouTube 분석 수익 보고서를 조회
- 사용자 활동 측정 항목과 예상 수익 및 광고 실적 측정 항목에 대한 액세스를 제공함
채널 또는 콘텐츠 소유자의 권한이 있는 계정으로 Refresh token 받아서 저장한 뒤 API 호출 시 사용한다.
(인증 관련 자세한 내용은 “유튜브(Youtube) API — 5.인증받고 사용하기” 글을 참고한다.)
2. 수익 Top5 동영상 목록 조회
위에서 필수 매개변수라고 설명한 정보를 사용하여 reports.query API를 호출한다.
태평양 표준시 기준, 10월 14일부터 10월 19일 동안 가장 많은 수익을 올린 동영상 5개의 정보를 아래와 같이 확인할 수 있다.
지금까지 Analytics API를 통한 분석 데이터의 조회 방법을 살펴봤다.
Analytics API는 기존에 사용하던 Data API와 다르게, 유튜브에서 관리하는 분석 데이터의 보고서 타입과 생성 주기를 고려하여 설계를 진행해야 한다. 또한 데이터의 수집 기준 시간대가 태평양 표준시이기 때문에 콘텐츠 생성 및 배포 시점하고 비교할 때 주의해야 한다.
