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 gerekir.

Bu yöntem, birçok farklı Analytics raporunu almanıza olanak tanır. Her istekte, kanal kimliği veya içerik sahibi, başlangıç tarihi, bitiş tarihi ve en az bir metrik belirtmek için sorgu parametreleri kullanılır. Ayrıca boyutlar, filtreler ve sıralama talimatları gibi ek sorgu parametreleri de sağlayabilirsiniz.

  • Metrikler, kullanıcı etkinliğinin ayrı ayrı ölçümleridir (ör. video görüntülemeleri veya derecelendirmeler (beğenmeler ve beğenmemeler)).
  • Boyutlar, verileri toplamak için kullanılan ortak ölçütlerdir. Örneğin, kullanıcı etkinliğinin gerçekleştiği tarih veya kullanıcıların bulunduğu ülke. Bir raporda, her veri satırının benzersiz bir boyut değerleri kombinasyonu vardır.
  • Filtreler, alınacak verileri belirten boyut değerleridir. Örneğin, belirli bir ülke, belirli bir video veya bir grup videoyla ilgili 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 örnekleri

İ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 istekleri aşağıdaki yetkilendirme kapsamlarını kullanır:

Kapsamlar
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 derecelendirme 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 finansal raporlarını görüntüleyin. Bu kapsam, kullanıcı etkinliği metriklerine, tahmini gelire 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 bu kapsamı kullanarak YouTube Analytics gruplarını ve grup öğelerini yönetir.
https://www.googleapis.com/auth/youtubepartner YouTube'daki YouTube öğelerini ve ilişkili içeriği görüntüleyin ve yönetin. İçerik sahipleri, YouTube Analytics API'de bu kapsamı kullanarak YouTube Analytics gruplarını ve grup öğelerini yönetir.

Parametreler

Aşağıdaki tablolarda, sorgu raporlarını almak için yapılan API isteklerinde kullanılan zorunlu ve isteğe bağlı sorgu parametreleri listelenmektedir. 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ılabildiği son güne kadar olan verileri içerir. Örneğin, istekte 5 Temmuz 2017 bitiş tarihi belirtiliyorsa ve istenen tüm metriklerin değerleri yalnızca 3 Temmuz 2017'ye kadar kullanılabiliyorsa yanıtın içerdiği son tarih bu olur. (Bu durum, istenen metriklerin bazılarının 4 Temmuz 2017'ye ait verileri mevcut olsa bile geçerlidir.)
Not: API'nin 1. sürümünde bu parametrenin adı end-date idi.
ids string
Verileri aldığınız YouTube kanalını veya içerik sahibini YouTube Analytics tanımlar.

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

metrics string
views veya likes,dislikes gibi YouTube Analytics metriklerin virgülle ayrılmış listesi. Alabileceğiniz raporların ve her raporda bulunan metriklerin listesi için kanal raporları veya içerik sahibi raporları ile ilgili belgelere bakın. (Metrikler belgesinde tüm metriklerin tanımları yer alır.)
startDate string
YouTube Analytics verilerinin getirilmeye başlandığı tarih. Değer, YYYY-MM-DD biçiminde olmalıdır.
Not: API'nin 1. sürümünde bu parametrenin adı start-date idi.
İsteğe bağlı parametreler
currency string
API'nin aşağıdaki 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 hesaplanan tahminlerdir. Bu metriklerden hiçbiri istenmiyorsa parametre yoksayılır.

Parametre değeri, aşağıdaki para birimleri listesinden alınan üç harfli bir ISO 4217 para birimi kodudur. Desteklenmeyen bir para birimi belirtilirse API hata döndürür. Varsayılan değer USD'dır.

dimensions string
video veya ageGroup,gender gibi virgülle ayrılmış YouTube Analytics boyutları listesi. Alabileceğiniz raporların listesi ve bu raporlarda kullanılan boyutlar 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ı ile ilgili dokümanlarda, her raporu filtrelemek için kullanılabilecek boyutlar belirtilir. Boyutlar dokümanında ise bu boyutlar tanımlanır.

Bir istekte birden fazla filtre kullanılıyorsa bunları noktalı virgülle (;) birleştirin. Döndürülen sonuç tablosu her iki filtreyi de karşılar. Örneğin, filters parametresinin video==dMH0bHeiRNg;country==IT değeri, sonuç kümesini İtalya'daki belirli 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. Bunu yapmak için API yanıtının filtrelenmesi gereken video, oynatma listesi veya kanal kimliklerinin ayrılmış bir listesini belirtin. Örneğin, filters parametresinin video==pd1FJh59zxQ,Zhawgd0REhA;country==IT değeri, sonuç kümesini İ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 fazla değer belirtirken bu filtreyi, istek için belirttiğiniz boyutlar listesine de ekleyebilirsiniz. Bu durum, 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, izleyicilerin kanalın video içeriğine ulaşma şekline göre görüntüleme istatistiklerini toplayan bir kanalın trafik kaynağı raporunu aldığınızı varsayalım. Ayrıca, isteğinizin filters parametre isteğinin, verilerin döndürülmesi gereken 10 videoluk bir liste tanımladığını varsayalım.
  • video parametresinin değerine dimensions eklerseniz API yanıtı, 10 videonun her biri için ayrı trafik kaynağı istatistikleri sağlar.
  • video parametresinin değerine dimensions eklemezseniz API yanıtı, 10 videonun tümü için 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 içerik sahibine bağlanmadan önceki dönemdeki kanalların izlenme süresi ve görüntüleme verilerini içerip içermeyeceğini belirtir. Varsayılan parametre değeri false'dır. Bu, API yanıtının yalnızca kanalların içerik sahibine bağlandığı tarihlerdeki 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 fazla kanal için veri alıyorsa ve parametre değeri false ise API yanıtı, her bir kanalın bağlantı tarihine göre 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 idi.
maxResults integer
Yanıtın içereceği maksimum satır sayısı.
Not: API'nin 1. sürümünde bu parametrenin adı max-results idi.
sort string
YouTube Analytics verilerinin sıralama düzenini belirleyen, virgülle ayrılmış boyut veya metrik listesi. Sıralama düzeni varsayılan olarak artandır. - öneki, azalan sıralama düzenine neden olur.
startIndex integer
Alınacak ilk öğenin 1 tabanlı dizini. (Varsayılan değer 1'dır.) Bu parametreyi max-results parametresiyle birlikte sayfalama mekanizması olarak kullanın.
Not: API'nin 1. sürümünde bu parametrenin adı start-index idi.
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'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

Yanıtı girintiler ve satır sonlarıyla döndürür.

  • true ise yanıtı okunabilir biçimde döndürür.
  • Varsayılan değer: true.
  • Bu ayar false olduğunda yanıt yükü boyutu küçülebilir ve bu da bazı ortamlarda daha iyi performansa yol açabilir.
quotaUser Bu parametre, API'nin 1. sürümünde destekleniyordu ancak bu sürüm artık kullanımdan kaldırıldı. Bu parametre, API'nin 2. sürümünde desteklenmez.
userIp Bu parametre, API'nin 1. sürümünde destekleniyordu ancak bu sürüm artık kullanımdan kaldırıldı. 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öntemler için destek eklerse bu yöntemlere yönelik API yanıtları başka kind özelliği değerleri içerebilir.
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 API isteğinde belirtilen metriklerle devam eder. 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
Boyutun 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ırasıyla eşleşir.

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

day boyutunun kullanıldığı bir sorgunun yanıtı, en son günlere ait satırları içermez.

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 kapsamayabilir. Desteklenen dillerin listesi için istemci kitaplıkları dokümanlarına bakın.

JavaScript

Bu örnek, yetkilendiren kullanıcının kanalının 2017 takvim yılına ait günlük görüntüleme sayılarını ve diğer metriklerini almak için YouTube Analytics API'sini çağırı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 bir 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, henüz ayarlanmadıysa bir ürün adı 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ı 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 ifade kullanabilirsiniz. Yetkilendirilmiş yönlendirme URI'leri alanını boş bırakabilirsiniz.
  7. Kimlik bilgilerinizi oluşturmayı tamamlamak için Oluştur düğmesini tıklayın.
  8. İletişim kutusunu kapatmadan önce, kod örneğine yerleştirmeniz 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 yerine yetkilendirme kimlik bilgilerinizi ayarlarken aldığınız istemci kimliğini girin.

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österen bir sayfa görmeniz gerekir.
  2. Kullanıcı yetkilendirme akışını başlatmak için yetkilendir ve yükle düğmesini tıklayın. Uygulamayı kanal verilerinizi alması için yetkilendirirseniz tarayıcıdaki konsola aşağıdaki 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üyorsanız 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 doğrulayın.
  4. API'yi çağırmak için execute (yürüt) düğmesini tıklayın. Tarayıcıdaki konsola bir response nesnesi yazdırıldığını görmelisiniz. 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>

Python

Bu örnek, yetkilendiren kullanıcının kanalının 2017 takvim yılına ait günlük görüntüleme sayılarını ve diğer metriklerini almak için YouTube Analytics API'sini çağırır. Örnekte Google API'leri Python istemci kitaplığı kullanılı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 bir 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, henüz ayarlanmadıysa bir ürün adı 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 Quickstart" adını girin ve Oluştur düğmesini tıklayın.
  6. Sonuçta ortaya çıkan 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 istemci 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, 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. Kimlik doğrulama akışı tarayıcınızda otomatik olarak yüklenebilir veya kimlik doğrulama URL'sini bir tarayıcı penceresine kopyalamanız gerekebilir. Yetkilendirme akışının sonunda, gerekirse tarayıcıda gösterilen yetkilendirme kodunu terminal pencerenize yapıştırın ve [return] tuşunu 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'
  )

Deneyin!

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