Reports: Query

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

Bu yöntem, birçok farklı Analytics raporunu almanızı sağlar. 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. Boyutlar, filtreler ve sıralama talimatları gibi ek sorgu parametreleri de sağlayabilirsiniz.

  • Metrikler, video etkinliğinin veya kullanıcı oylarının (beğenme ve beğenmeme sayısı) gibi kullanıcı etkinliğinin ayrı ayrı ölçümleridir.
  • Boyutlar, kullanıcı etkinliğinin gerçekleştiği tarih veya kullanıcıların bulunduğu ülke gibi verileri toplamak için kullanılan yaygın ölçütlerdir. Bir raporda, her veri satırının boyut değerlerinin benzersiz bir kombinasyonu vardır.
  • Filtreler, alınacak verileri belirten boyut değerleridir. Örneğin, belirli bir ülkeye, belirli bir videoya veya bir grup videoya ait 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ılavuzunda, yetkilendirme jetonlarını almak için OAuth 2.0 protokolünün nasıl kullanılacağı açıklanmaktadır.

YouTube Analytics API isteklerinde aşağıdaki yetkilendirme kapsamları kullanılır:

Nişan dürbünleri
https://www.googleapis.com/auth/yt-analytics.readonly YouTube içeriğiniz için 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ğiniz için YouTube Analytics mali raporlarını görüntüleyin. Bu kapsam, kullanıcı etkinliği metriklerine ve tahmini gelir ile reklam performansı metriklerine erişim sağlar.
https://www.googleapis.com/auth/youtube YouTube hesabınızı yönetin. YouTube Analytics API'de kanal sahipleri, 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çerikleri görüntüleyin ve yönetin. YouTube Analytics API'de, içerik sahipleri bu kapsamı YouTube Analytics gruplarını ve grup öğelerini yönetmek için kullanır.

Parametreler

Aşağıdaki tablolarda, API isteklerinin sorgu raporlarını alması için gerekli ve isteğe bağlı sorgu parametreleri gösterilmektedir. Tabloda listelenen standart sorgu parametreleri de isteğe bağlıdır ve birçok Google API'si tarafından desteklenir.

Parametreler
Zorunlu Parametreler
endDate string
YouTube Analytics verilerinin getirilmesinin bitiş tarihi. Değer YYYY-MM-DD biçiminde olmalıdır.

API yanıtı, sorgudaki tüm metriklerin sorgudaki mevcut olduğu son güne kadar olan verileri içerir. Örneğin, istek 5 Temmuz 2017'de bir bitiş tarihi belirtiyorsa ve istenen tüm metriklere ait değerler yalnızca 3 Temmuz 2017'ye kadar mevcutsa bu, yanıta verilerin dahil edileceği son tarih olur. (İstenen metriklerden bazılarının verileri 4 Temmuz 2017 için mevcut olsa bile bu durum geçerlidir.)
Not: Bu parametre, API'nin 1. sürümünde end-date olarak adlandırılıyordu.
ids string
YouTube Analytics verilerini aldığınız YouTube kanalını veya içerik sahibini tanımlar.

  • Bir YouTube kanalının verilerini istemek için 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 sahibi için veri isteğinde bulunmak amacıyla ids parametre değerini contentOwner==OWNER_NAME olarak ayarlayın. 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 bulunan metriklerin listesi için kanal raporları veya içerik sahibi raporları dokümanlarına bakın. (Metrikler dokümanı, tüm metriklerin tanımlarını içerir.)
startDate string
YouTube Analytics verilerinin getirilmesi için başlangıç tarihi. Değer YYYY-MM-DD biçiminde olmalıdır.
Not: Bu parametre, API'nin 1. sürümünde start-date olarak adlandırılıyordu.
İsteğe Bağlı Parametreler
currency string
API'nin şu tahmini gelir metriklerini belirtmek için kullanacağı para birimi: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, brütGelir, bgbm, playbackbasedCpm. API'nin bu metrikler için döndürdüğü değerler, günlük olarak değişen döviz kurları kullanılarak hesaplanan tahminlerdir. Bu metriklerden hiçbiri istenmemişse parametre yoksayılır.

Parametre değeri, aşağıdaki para birimi listesindeki üç harfli ISO 4217 para birimi kodudur. Desteklenmeyen bir para birimi belirtilirse API bir hata döndürür. Varsayılan değer: USD
dimensions string
video veya ageGroup,gender gibi YouTube Analytics boyutlarının virgülle ayrılmış listesi. Alabileceğiniz raporların ve bu raporlar için kullanılan boyutların listesi için kanal raporları veya içerik sahibi raporları dokümanlarına 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ı için dokümanlar, her bir raporu filtrelemek için kullanılabilecek boyutları tanımlar. Boyutlar belgesinde ise bu boyutlar tanımlanır.

Bir istek birden fazla filtre kullanıyorsa bunları noktalı virgülle (;) bir araya getirin. Döndürülen sonuç tablosu her iki filtreyi de karşılar. Örneğin, filters olan parametre değeri video==dMH0bHeiRNg;country==IT, sonuç grubunu İtalya'da söz konusu videonun verilerini içerecek şekilde kısıtlar.

Bir filtre için birden çok değer belirtme

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

Aynı filtre için birden fazla değer belirtirken bu filtreyi istek için belirttiğiniz boyutlar listesine de ekleyebilirsiniz. Filtre belirli bir raporda desteklenen boyut olarak listelenmese bile bu durum geçerlidir. Filtreyi boyut 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 şekline dayalı görüntüleme istatistikleri toplar. Ayrıca, isteğinizin filters parametre isteğinin, 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ının 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 izlenme süresini içermesi ve kanalların içerik sahibine bağlandığı tarihten önceki döneme ait verileri görüntülemesi gerekip gerekmediğini belirtir. Varsayılan parametre değeri false, API yanıtı olarak yalnızca kanalların içerik sahibine bağlandığı tarihlerdeki izlenme süresi ve görüntüleme verilerini içerir.

Farklı kanalların, farklı tarihlerde içerik sahiplerine bağlanmış olabileceğini unutmayın. API isteği birden fazla kanal için veri alıyorsa ve parametre değeri false ise API yanıtı, ilgili her 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: Bu parametre, API'nin 1. sürümünde include-historical-channel-data olarak adlandırılıyordu.
maxResults integer
Yanıta dahil edilecek maksimum satır sayısı.
Not: Bu parametre, API'nin 1. sürümünde max-results olarak adlandırılıyordu.
sort string
YouTube Analytics verilerinin sıralama düzenini belirleyen boyutların veya metriklerin virgülle ayrılmış listesi. Sıralama düzeni varsayılan olarak artan düzendedir. - ön eki, azalan sıralamaya neden olur.
startIndex integer
Alınacak ilk varlığın 1 tabanlı dizini. (Varsayılan değer: 1.) Bu parametreyi max-results parametresiyle birlikte sayfalara ayırma mekanizması olarak kullanın.
Not: Bu parametre, API'nin 1. sürümünde start-index olarak adlandırılıyordu.
Standart Parametreler
access_token Geçerli kullanıcı için OAuth 2.0 jetonu.
alt Bu parametre, yalnızca JSON yanıtlarını destekleyen API 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ı insan tarafından okunabilir bir biçimde döndürür.
  • Varsayılan değer: true.
  • Bu false olduğunda, yanıt yükü boyutunu küçülterek bazı ortamlarda daha iyi performans elde edebilirsiniz.
quotaUser Bu parametre, kullanımdan kaldırılan API'nin 1. sürümünde destekleniyordu. Bu parametre, API'nin 2. sürümünde desteklenmez.
userIp Bu parametre, kullanımdan kaldırılan API'nin 1. sürümünde destekleniyordu. Bu parametre, API'nin 2. sürümünde desteklenmez.

İstek metni

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övdesi hakkında 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 verilerin türünü belirtir. query yöntemi için kind özellik değeri youtubeAnalytics#resultTable olur. Ancak API diğer yöntemler için destek eklerse bu yöntemler için API yanıtları, diğer kind özellik değerlerini sunabilir.
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şiyor.

Ö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ış veriler içeren bir dizidir. Virgülle ayrılmış veri alanlarının sırası, columnHeaders alanında listelenen sütunların sırası ile eşleşir.

Belirtilen sorgu için hiç veri yoksa rows öğesi yanıttan çıkarılır.

day boyutuna sahip bir sorgunun yanıtında son günlere ait satırlar 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 örnekte YouTube Analytics API'si, 2017 takvim yılında kullanıcının kanalı için yetkilendirilen günlük görüntüleme sayısı ve diğer metrikleri alır. Örnekte Google API'leri JavaScript istemci kitaplığı kullanılmaktadır.

Bu örneği ilk kez yerel olarak çalıştırmadan önce projeniz için yetkilendirme kimlik bilgilerini ayarlamanız gerekir:
  1. Google API Konsolu'nda proje oluşturun veya seçin.
  2. Projeniz için YouTube Analytics API'yi etkinleştirin.
  3. Kimlik bilgileri sayfasının üst kısmında OAuth izin ekranı sekmesini seçin. Bir e-posta adresi seçin, ayarlanmamışsa ürün adını girin ve Kaydet düğmesini tıklayın.
  4. Kimlik bilgileri sayfasında 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. Yetkili 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 şey kullanabilirsiniz. Yetkilendirilmiş 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 eklemeniz gereken istemci kimliğini kopyalayın.

Ardından, örneği yerel bir dosyaya kaydedin. Örnekte aşağıdaki satırı bulup yetkilendirme kimlik bilgilerinizi ayarlarken edindiğiniz istemci kimliğiyle YOUR_CLIENT_ID değerini değiştirin.

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

Artık örneği 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österen bir sayfa görürsünüz.
  2. Kullanıcı yetkilendirme akışını başlatmak için Yetkilendir ve yükle düğmesini tıklayın. Uygulamanın kanal verilerinizi alması için yetkilendirirseniz aşağıdaki satırların tarayıcıda konsola 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ığı şekilde koda yerleştirdiğinizi onaylayın.
  4. API'yi çağırmak için Yürüt düğmesini tıklayın. Tarayıcıda konsola bir response nesnesi yazdırılması gerekir. 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 örnekte YouTube Analytics API'si, 2017 takvim yılında kullanıcının kanalı için yetkilendirilen günlük görüntüleme sayısı ve diğer metrikleri alır. Örnekte Google API'leri Python istemci kitaplığı kullanılmaktadır.

Bu örneği ilk kez yerel olarak çalıştırmadan önce projeniz için yetkilendirme kimlik bilgilerini ayarlamanız gerekir:
  1. Google API Konsolu'nda proje oluşturun veya seçin.
  2. Projeniz için YouTube Analytics API'yi etkinleştirin.
  3. Kimlik bilgileri sayfasının üst kısmında OAuth izin ekranı sekmesini seçin. Bir e-posta adresi seçin, ayarlanmamışsa ürün adını girin ve Kaydet düğmesini tıklayın.
  4. Kimlik bilgileri sayfasında 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çin, "YouTube Analytics API Hızlı Başlangıç" adını girin ve 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'ı 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ı 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 test etmeye hazırsınız:

  1. Aşağıdaki kod örneğini çalışma dizininize kopyalayın.
  2. Örnekte, yetkilendirme kimlik bilgilerinizi ayarladıktan sonra indirdiğiniz dosyanın konumuyla eşleşecek şekilde CLIENT_SECRETS_FILE değişkeninin değerini güncelleyin.
  3. Örnek kodu bir terminal penceresinde ç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. Gerekirse yetkilendirme akışının sonunda, tarayıcıda görüntülenen yetkilendirme kodunu terminal pencerenize yapıştırın ve [iade] düğmesini tıklayın.
  5. API sorgusu yürütülür ve JSON yanıtı, terminal penceresine verilir.
# -*- 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ği ile yanıtını görmek için APIs Explorer özelliğini kullanın.