Reports: Query

Önemli: Bu yönteme yönelik API istekleri için artık https://www.googleapis.com/auth/youtube.readonly kapsamına erişim gerekiyor.

Bu yöntem sayesinde birçok farklı Analytics raporu alabilirsiniz. Her istek, bir kanal kimliği veya içerik sahibi, başlangıç tarihi, bitiş tarihi ve en az bir metrik belirtmek için sorgu parametrelerini kullanır. Ayrıca boyutlar, filtreler ve sıralama talimatları gibi ek sorgu parametreleri de sağlayabilirsiniz.

  • Metrikler, video görüntüleme sayısı veya derecelendirmeler (beğenme ve beğenmeme sayısı) gibi kullanıcı etkinliğinin ayrı ayrı ölçümlerdir.
  • Boyutlar, verileri birleştirmek için yaygın olarak kullanılan ölçütlerdir (ör. kullanıcı etkinliğinin gerçekleştiği tarih veya kullanıcıların bulunduğu ülke). Raporlarda, her veri satırında benzersiz bir boyut değerleri kombinasyonu bulunur.
  • Filtreler, alınacak verileri belirten boyut değerleridir. Örneğin, belirli bir ülke, belirli bir video veya bir video grubuna ilişkin verileri alabilirsiniz.

Not: İçerik sahibi raporlarına yalnızca YouTube İş Ortağı Programı'na katılan YouTube içerik iş ortakları erişebilir.

Yaygın kullanım alanları

İstek

HTTP isteği

GET https://youtubeanalytics.googleapis.com/v2/reports

Tüm YouTube Analytics API istekleri yetkilendirilmelidir. Yetkilendirme kılavuzu, yetkilendirme jetonlarını almak için OAuth 2.0 protokolünün nasıl kullanılacağını açıklar.

YouTube Analytics API istekleri aşağıdaki yetkilendirme kapsamlarını kullanır:

Nişan dürbünleri
https://www.googleapis.com/auth/yt-analytics.readonly YouTube içeriğinize ilişkin YouTube Analytics raporlarını görüntüleyin. Bu kapsam, görüntüleme sayısı ve puan sayısı gibi kullanıcı etkinliği metriklerine erişim sağlar.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly YouTube içeriğinize ilişkin YouTube Analytics mali raporlarını görüntüleyin. Bu kapsam, kullanıcı etkinliği metriklerinin yanı sıra tahmini gelir ve reklam performansı metriklerine erişim sağlar.
https://www.googleapis.com/auth/youtube YouTube hesabınızı yönetin. Kanal sahipleri, YouTube Analytics API'de YouTube Analytics gruplarını ve grup öğelerini yönetmek için bu kapsamı kullanır.
https://www.googleapis.com/auth/youtubepartner YouTube öğelerini ve YouTube'daki ilişkili içeriği görüntüleyin ve yönetin. İçerik sahipleri, YouTube Analytics API'de YouTube Analytics gruplarını ve grup öğelerini yönetmek için bu kapsamı kullanır.

Parametreler

Aşağıdaki tablolarda, sorgu raporlarını almak amacıyla API istekleri için gerekli ve isteğe bağlı sorgu parametreleri listelenmiştir. Tabloda listelenen standart sorgu parametreleri de isteğe bağlıdır ve birçok Google API'si tarafından desteklenir.

Parametreler
Gerekli parametreler
endDate string
YouTube Analytics verilerinin getirilmesi için bitiş tarihi. Değer YYYY-MM-DD biçiminde olmalıdır.

API yanıtı, sorgu sırasında sorgudaki tüm metriklerin kullanılabilir olduğu son güne kadar olan verileri içerir. Bu nedenle, örneğin istek 5 Temmuz 2017 bitiş tarihini belirtiyorsa ve istenen tüm metriklerin değerleri yalnızca 3 Temmuz 2017'ye kadar kullanılabiliyorsa bu tarih, verilerin yanıta dahil edileceği son tarih olur. (İstenen metriklerden bazılarının verileri 4 Temmuz 2017 için kullanılabilir olsa bile bu durum geçerlidir.)
Not: API'nin 1. sürümünde bu parametrenin adı end-date olarak değiştirildi.
ids string
YouTube Analytics verilerini aldığınız YouTube kanalını veya içerik sahibini tanımlar.

  • Bir YouTube kanalı için veri istemek üzere ids parametre değerini channel==MINE veya channel==CHANNEL_ID olarak ayarlayın. Burada CHANNEL_ID, kimliği doğrulanmış kullanıcının YouTube kanalını tanımlar.
  • Bir YouTube içerik sahibine ait verileri istemek için ids parametre değerini contentOwner==OWNER_NAME olarak ayarlayın. Burada OWNER_NAME, kullanıcı için content owner ID değeridir.

metrics string
views veya likes,dislikes gibi YouTube Analytics metriklerinin virgülle ayrılmış listesi. Alabileceğiniz raporların ve her bir raporda kullanılabilen metriklerin bir listesi için kanal raporları veya içerik sahibi raporları ile ilgili dokümanlara bakın. (Metrikler belgesinde tüm metriklerin tanımları yer alır.)
startDate string
YouTube Analytics verilerini getirmenin başlangıç tarihi. Değer YYYY-MM-DD biçiminde olmalıdır.
Not: API'nin 1. sürümünde bu parametrenin adı start-date olarak değiştirildi.
İsteğe Bağlı Parametreler
currency string
API'nin şu tahmini gelir metriklerini belirtmek için kullanacağı para birimi: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm. API'nin bu metrikler için döndürdüğü değerler, günlük olarak değişen döviz kurları kullanılarak hesaplanır. Bu metriklerin hiçbiri için istek yapılmazsa parametre yok sayılır.

Parametre değeri, aşağıdaki para birimi listesinde bulunan üç harfli ISO 4217 para birimi kodudur. Desteklenmeyen bir para birimi belirtilirse API hata döndürür. Varsayılan değer USD değeridir.
dimensions string
YouTube Analytics boyutlarının video veya ageGroup,gender gibi virgülle ayrılmış listesi. Alabileceğiniz raporların ve bu raporlar için kullanılan boyutların bir listesi için kanal raporları veya içerik sahibi raporları ile ilgili dokümanlara bakın. (Boyutlar belgesinde tüm boyutların tanımları yer alır.)
filters string
YouTube Analytics verileri alınırken uygulanması gereken filtrelerin listesi. Kanal raporları ve içerik sahibi raporlarına ilişkin dokümanlar, her bir raporu filtrelemek için kullanılabilecek boyutları ve Boyutlar dokümanında bu boyutları tanımlar.

Bir istekte birden fazla filtre kullanılıyorsa bu filtreleri noktalı virgülle (;) birleştirdiğinizde döndürülen sonuç tablosu her iki filtreyi de karşılayacaktır. Örneğin, filters parametre değeri video==dMH0bHeiRNg;country==IT olduğunda sonuç grubu İtalya'daki belirli bir videonun verilerini içerecek şekilde kısıtlar.

Bir filtre için birden fazla değer belirtme

API; video, playlist ve channel filtreleri için birden fazla değer belirtme özelliğini destekler. API yanıtının filtrelenmesi gereken video, oynatma listesi veya kanal kimliklerinin ayrı bir listesini belirtin. Örneğin, filters parametre değeri video==pd1FJh59zxQ,Zhawgd0REhA;country==IT ise sonuç grubunu İtalya'daki belirli videoların verilerini içerecek şekilde kısıtlar. Parametre değeri en fazla 500 kimlik belirtebilir.

Aynı filtre için birden çok değer belirtirken söz konusu filtreyi istek için belirttiğiniz boyutlar listesine de ekleyebilirsiniz. Bu, filtre belirli bir rapor için desteklenen boyut olarak listelenmemiş olsa bile geçerlidir. Filtreyi boyutlar listesine eklerseniz API, sonuçları gruplandırmak için filtre değerlerini de kullanır.

Örneğin, bir kanalın trafik kaynağı raporunu aldığınızı varsayalım. Bu rapor, izleyicilerin kanalın video içeriğine ulaşma yöntemine göre görüntüleme istatistiklerini toplar. Ayrıca, isteğinizin filters parametresi isteğinin, verilerinin döndürülmesi gereken 10 videonun listesini tanımladığını varsayalım.
  • dimensions parametresinin değerine video eklerseniz API yanıtı, 10 videonun her biri için ayrı trafik kaynağı istatistikleri sağlar.
  • dimensions parametresinin değerine video eklemezseniz API yanıtı, 10 videonun tamamına ilişkin trafik kaynağı istatistiklerini toplar.
includeHistoricalChannelData boolean
Not: Bu parametre yalnızca içerik sahibi raporları için geçerlidir.

API yanıtının, kanalların içerik sahibine bağlanmasından önceki döneme ait izlenme süresi ve görüntüleme verilerini içermesi gerekip gerekmediğini belirtir. Varsayılan parametre değeri olan false, API yanıtının yalnızca kanalların içerik sahibine bağlandığı tarihlere ait izlenme süresi ve görüntüleme verilerini içerdiği anlamına gelir.

Farklı kanalların farklı tarihlerde bir içerik sahibine bağlanmış olabileceğini unutmayın. API isteği birden çok kanal için veri alıyorsa ve parametre değeri false ise API yanıtı, ilgili her bir kanalın bağlantı tarihine dayalı veriler içerir. Parametre değeri true ise API yanıtı, API isteğinde belirtilen tarihlerle eşleşen verileri içerir.
Not: API'nin 1. sürümünde bu parametrenin adı include-historical-channel-data olarak değiştirildi.
maxResults integer
Yanıta dahil edilecek maksimum satır sayısı.
Not: API'nin 1. sürümünde bu parametrenin adı max-results olarak değiştirildi.
sort string
YouTube Analytics verilerinin sıralama düzenini belirleyen boyut veya metriklerin virgülle ayrılmış listesi. Sıralama düzeni varsayılan olarak artan düzendedir. - öneki, azalan sıralama düzenine neden olur.
startIndex integer
Alınacak ilk varlığın 1 tabanlı dizini. (Varsayılan değer 1'tir.) Bu parametreyi, max-results parametresiyle birlikte sayfalara ayırma mekanizması olarak kullanın.
Not: API'nin 1. sürümünde bu parametrenin adı start-index olarak değiştirildi.
Standart Parametreler
access_token Geçerli kullanıcı için OAuth 2.0 jeton.
alt Bu parametre, yalnızca JSON yanıtlarını destekleyen API'nin 2. sürümünde desteklenmez. API yanıtının veri biçimi.
  • Geçerli değerler: json, csv
  • Varsayılan değer: json
callback Geri çağırma işlevi.
  • Yanıtı işleyen JavaScript geri çağırma işlevinin adı.
  • JavaScript JSON-P isteklerinde kullanılır.
prettyPrint

Girintiler ve satır sonları içeren yanıtı döndürür.

  • true ise yanıtı kullanıcıların okuyabileceği bir biçimde döndürür.
  • Varsayılan değer: true.
  • Bu false olduğunda yanıt yükü boyutunu azaltabilir ve bazı ortamlarda daha iyi performans sağlayabilir.
quotaUser Bu parametre, API'nin 1. sürümünde desteklenmekte olup kullanımdan kaldırılmıştır. Bu parametre, API'nin 2. sürümünde desteklenmez.
userIp Bu parametre, API'nin 1. sürümünde desteklenmekte olup kullanımdan kaldırılmıştır. Bu parametre, API'nin 2. sürümünde desteklenmez.

İstek içeriği

Bu yöntemi çağırırken istek gövdesi göndermeyin.

Yanıt

alt parametre tanımında belirtildiği gibi, API yanıtları JSON veya CSV biçiminde döndürebilir. Her tür için yanıt gövdesiyle ilgili bilgiler aşağıda gösterilmektedir:

JSON
{
  "kind": "youtubeAnalytics#resultTable",
  "columnHeaders": [
    {
      "name": string,
      "dataType": string,
      "columnType": string
    },
    ... more headers ...
  ],
  "rows": [
    [
      {value}, {value}, ...
    ]
  ]
}
Özellikler
kind string
Bu değer, API yanıtına dahil edilen veri türünü belirtir. query yöntemi için kind özellik değeri youtubeAnalytics#resultTable olur. Ancak API diğer yöntemleri desteklerse bu yöntemlerin API yanıtları, başka kind özellik değerlerini de beraberinde getirebilir.
columnHeaders[] list
Bu değer, rows alanlarında döndürülen verilerle ilgili bilgileri belirtir. columnHeaders listesindeki her öğe, virgülle ayrılmış verilerin listesini içeren rows değerinde döndürülen bir alanı tanımlar.

columnHeaders listesi, API isteğinde belirtilen boyutlarla başlar ve ardından API isteğinde belirtilen metrikler gelir. Hem boyutların hem de metriklerin sırası, API isteğindeki sıralamayla eşleşir.

Örneğin, API isteği dimensions=ageGroup,gender&metrics=viewerPercentage parametrelerini içeriyorsa API yanıtı, sütunları şu sırayla döndürür: ageGroup,gender,viewerPercentage.
columnHeaders[].name string
Boyut veya metriğin adı.
columnHeaders[].columnType string
Sütunun türü (DIMENSION veya METRIC).
columnHeaders[].dataType string
Sütundaki verilerin türü (STRING, INTEGER, FLOAT vb.).
rows[] list
Liste, sonuç tablosunun tüm satırlarını içerir. Listedeki her öğe, tek bir veri satırına karşılık gelen virgülle ayrılmış verileri içeren bir dizidir. Virgülle ayrılmış veri alanlarının sırası, columnHeaders alanında listelenen sütunların sıralamasıyla eşleşir.

Belirli bir sorgu için kullanılabilecek veri yoksa rows öğesi yanıttan çıkarılır.

day boyutu olan bir sorgunun yanıtında son günler için satır bulunmaz.

CSV
day, views, likes, ...
"2012-01-01", 12.0, 3, ...
"2012-01-02", 16.0, 2, ...
"2012-01-03", 18.0, 8, ...
...

Örnekler

Not: Aşağıdaki kod örnekleri, desteklenen tüm programlama dillerini temsil etmeyebilir. Desteklenen dillerin listesi için istemci kitaplıkları dokümanlarına bakın.

JavaScript

Bu örnek, 2017 takvim yılı için yetkilendiren kullanıcının kanalındaki günlük görüntüleme sayısını ve diğer metrikleri almak amacıyla YouTube Analytics API'yi çağırır. Örnekte, Google API'leri JavaScript istemci kitaplığı kullanılır.

Bu örneği yerel olarak ilk kez çalıştırmadan önce projeniz için yetkilendirme kimlik bilgilerini ayarlamanız gerekir:
  1. Google API Konsolu'nda bir proje oluşturun veya seçin.
  2. Projeniz için YouTube Analytics API'yi etkinleştirin.
  3. Kimlik bilgileri sayfasının en üstünde, OAuth izin ekranı sekmesini seçin. Bir E-posta adresi seçin, daha önce ayarlanmamışsa Ürün adı girin ve Kaydet düğmesini tıklayın.
  4. Credentials (Kimlik Bilgileri) sayfasında Create credentials (Kimlik bilgisi oluştur) düğmesini tıklayın ve Oauth istemci kimliği'ni seçin.
  5. Web uygulaması uygulama türünü seçin.
  6. Yetkilendirilmiş JavaScript kaynakları alanına kod örneğini sunacağınız URL'yi girin. Örneğin, http://localhost:8000 veya http://yourserver.example.com gibi bir değer kullanabilirsiniz. Yetkili yönlendirme URI'leri alanını boş bırakabilirsiniz.
  7. Kimlik bilgilerinizi oluşturma işlemini tamamlamak için Oluştur düğmesini tıklayın.
  8. İletişim kutusunu kapatmadan önce, kod örneğine girmeniz gereken istemci kimliğini kopyalayın.

Ardından, örneği yerel bir dosyaya kaydedin. Örnekte, aşağıdaki satırı bulun ve YOUR_CLIENT_ID kısmını yetkilendirme kimlik bilgilerinizi oluştururken aldığınız istemci kimliğiyle değiştirin.

gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});

Artık örneği gerçekten test etmeye hazırsınız:

  1. Yerel dosyayı bir web tarayıcısından açın ve tarayıcıda hata ayıklama konsolunu açın. İki düğme görüntüleyen bir sayfa görmeniz gerekir.
  2. Kullanıcı yetkilendirme akışını başlatmak için Yetkilendir ve yükle düğmesini tıklayın. Uygulamaya kanal verilerinizi alma yetkisi verirseniz tarayıcıda şu satırların yazdırıldığını görürsünüz: 
    Sign-in successful
GAPI client loaded for API
  3. Yukarıdaki satırlar yerine bir hata mesajı görürseniz komut dosyasını projeniz için ayarladığınız yetkili yönlendirme URI'sinden yüklediğinizi ve istemci kimliğinizi yukarıda açıklandığı gibi koda yerleştirdiğinizi onaylayın.
  4. API'yi çağırmak için execute düğmesini tıklayın. Tarayıcıda konsola yazdırılan bir response nesnesi görürsünüz. Bu nesnede result özelliği, API verilerini içeren bir nesneyle eşlenir.
<script src="https://apis.google.com/js/api.js"></script>
<script>
  function authenticate() {
    return gapi.auth2.getAuthInstance()
        .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"})
        .then(function() { console.log("Sign-in successful"); },
              function(err) { console.error("Error signing in", err); });
  }
  function loadClient() {
    return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2")
        .then(function() { console.log("GAPI client loaded for API"); },
              function(err) { console.error("Error loading GAPI client for API", err); });
  }
  // Make sure the client is loaded and sign-in is complete before calling this method.
  function execute() {
    return gapi.client.youtubeAnalytics.reports.query({
      "ids": "channel==MINE",
      "startDate": "2017-01-01",
      "endDate": "2017-12-31",
      "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained",
      "dimensions": "day",
      "sort": "day"
    })
        .then(function(response) {
                // Handle the results here (response.result has the parsed body).
                console.log("Response", response);
              },
              function(err) { console.error("Execute error", err); });
  }
  gapi.load("client:auth2", function() {
    gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
  });
</script>
<button onclick="authenticate().then(loadClient)">authorize and load</button>
<button onclick="execute()">execute</button>

yt_analytics_v2.html

Python

Bu örnek, 2017 takvim yılı için yetkilendiren kullanıcının kanalındaki günlük görüntüleme sayısını ve diğer metrikleri almak amacıyla YouTube Analytics API'yi çağırır. Örnekte, Google API'leri Python istemci kitaplığı kullanılır.

Bu örneği yerel olarak ilk kez çalıştırmadan önce projeniz için yetkilendirme kimlik bilgilerini ayarlamanız gerekir:
  1. Google API Konsolu'nda bir proje oluşturun veya seçin.
  2. Projeniz için YouTube Analytics API'yi etkinleştirin.
  3. Kimlik bilgileri sayfasının en üstünde, OAuth izin ekranı sekmesini seçin. Bir E-posta adresi seçin, daha önce ayarlanmamışsa Ürün adı girin ve Kaydet düğmesini tıklayın.
  4. Credentials (Kimlik Bilgileri) sayfasında Create credentials (Kimlik bilgisi oluştur) düğmesini tıklayın ve Oauth istemci kimliği'ni seçin.
  5. Diğer uygulama türünü seçip "YouTube Analytics API Hızlı Başlangıç Kılavuzu" adını girip Oluştur düğmesini tıklayın.
  6. Açılan iletişim kutusunu kapatmak için Tamam'ı tıklayın.
  7. İstemci kimliğinin sağındaki (JSON'u indir) düğmesini tıklayın.
  8. İndirilen dosyayı çalışma dizininize taşıyın.

Ayrıca, Python için Google API'leri İstemci Kitaplığı'nı ve bazı ek kitaplıkları da yüklemeniz gerekir:

pip install --upgrade google-api-python-client
pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

Artık örneği gerçekten test etmeye hazırsınız:

  1. Aşağıdaki kod örneğini çalışma dizininize kopyalayın.
  2. Örnekte, CLIENT_SECRETS_FILE değişkeninin değerini, yetkilendirme kimlik bilgilerinizi ayarladıktan sonra indirdiğiniz dosyanın konumuyla eşleşecek şekilde güncelleyin.
  3. Bir terminal penceresinde örnek kodu çalıştırın: 
    python yt_analytics_v2.py
  4. Yetkilendirme akışını tamamlayın. Yetkilendirme akışı tarayıcınızda otomatik olarak yüklenebilir veya kimlik doğrulama URL'sini bir tarayıcı penceresine kopyalamanız gerekebilir. Gerekiyorsa, yetkilendirme akışının sonunda tarayıcıda görüntülenen yetkilendirme kodunu terminal pencerenize yapıştırın ve [return] düğmesini tıklayın.
  5. API sorgusu yürütülür ve JSON yanıtı terminal penceresine çıkar.
# -*- coding: utf-8 -*-

import os
import google.oauth2.credentials
import google_auth_oauthlib.flow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly']

API_SERVICE_NAME = 'youtubeAnalytics'
API_VERSION = 'v2'
CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json'
def get_service():
  flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES)
  credentials = flow.run_console()
  return build(API_SERVICE_NAME, API_VERSION, credentials = credentials)

def execute_api_request(client_library_function, **kwargs):
  response = client_library_function(
    **kwargs
  ).execute()

  print(response)

if __name__ == '__main__':
  # Disable OAuthlib's HTTPs verification when running locally.
  # *DO NOT* leave this option enabled when running in production.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  youtubeAnalytics = get_service()
  execute_api_request(
      youtubeAnalytics.reports().query,
      ids='channel==MINE',
      startDate='2017-01-01',
      endDate='2017-12-31',
      metrics='estimatedMinutesWatched,views,likes,subscribersGained'
      dimensions='day',
      sort='day'
  )

yt_analytics_v2.py

Deneyin.

Bu API'yi çağırmak ve API isteğini ve yanıtını görmek için APIs Explorer kullanın.