Core Reporting API - Başvuru Rehberi

Bu belgede, Core Reporting API 3.0 sürümü için hem sorgu hem de yanıt tam olarak belirtilmektedir.

Giriş

Google Analytics rapor verileri için Core Reporting API'yi sorgularsınız. Her sorgu için bir görünüm (profil) kimliği, başlangıç ile bitiş tarihi ve en az bir metrik gerekir. Ayrıca sorgunuzu hassaslaştırmak için boyutlar, filtreler ve segmentler gibi ek sorgu parametreleri de sağlayabilirsiniz. Tüm bu kavramların birlikte nasıl çalıştığını anlamak için Genel Bakış Kılavuzu'nu inceleyin.

İstek

API, veri istemek için tek bir yöntem sağlar:

analytics.data.ga.get()

Bu yöntem, çeşitli istemci kitaplıklarında gösterilir ve sorgu parametrelerini ayarlamak için dile özel arayüzlere sahiptir.

API, REST uyumlu uç nokta olarak da sorgulanabilir:

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

Her bir URL sorgu parametresi, URL kodlamalı olması gereken bir API sorgu parametresi belirtir.

Sorgu Parametreleri Özeti

Aşağıdaki tabloda, temel raporlama API'si tarafından kabul edilen tüm sorgu parametreleri özetlenmektedir. Ayrıntılı açıklama için her parametrenin adını tıklayın.

Ad Değer Gerekli Özet
ids string evet ga:XXXX formunun benzersiz tablo kimliği. Burada XXXX, sorgunun verileri alacağı Analytics görünümü (profil) kimliğidir.
start-date string evet Analytics verilerini getirme işleminin başlangıç tarihi. İstekler, YYYY-MM-DD olarak biçimlendirilmiş bir başlangıç tarihi veya göreli bir tarih (ör. today, yesterday veya NdaysAgo; burada N pozitif bir tam sayıdır).
end-date string evet Analytics verilerinin getirilmesi için bitiş tarihi. İstek, YYYY-MM-DD olarak biçimlendirilmiş bir bitiş tarihi veya göreli bir tarih (ör. today, yesterday veya NdaysAgo; burada N pozitif bir tam sayıdır).
metrics string evet ga:sessions,ga:bounces gibi virgülle ayrılmış metriklerin listesi.
dimensions string no Analytics verileriniz için virgülle ayrılmış boyutların listesi (ör. ga:browser,ga:city).
sort string no Döndürülen verilerin sıralama düzenini ve sıralama yönünü belirten, virgülle ayrılmış boyut ve metriklerin listesi.
filters string no İsteğiniz için döndürülen verileri kısıtlayan boyut veya metrik filtreleri.
segment string no İsteğiniz için döndürülen verileri segmentlere ayırır.
samplingLevel string no İstenen örnekleme düzeyi. İzin Verilen Değerler:
  • DEFAULT: Hız ve doğruluğu dengeleyen bir örnek boyutuyla yanıtı döndürür.
  • FASTER: Daha küçük örnek boyutuyla hızlı yanıt döndürür.
  • HIGHER_PRECISION: Büyük bir örnek boyutu kullanarak daha doğru bir yanıt döndürür ancak bu, yanıtın daha yavaş olmasına neden olabilir.
include-empty-rows boolean no Varsayılan olarak doğru değerine ayarlanır. Yanlış değerine ayarlanırsa tüm metrik değerlerinin sıfır olduğu satırlar yanıttan çıkarılır.
start-index integer no Alınacak ilk veri satırı (1'den başlar). Bu parametreyi, max-results parametresiyle birlikte sayfalara ayırma mekanizması olarak kullanın.
max-results integer no Yanıta dahil edilecek maksimum satır sayısı.
output string no Yanıtta döndürülen Analytics verileri için istenen çıkış türü. Kabul edilebilir değerler json ve dataTable'dir. Varsayılan: json.
fields string no Yanıta dahil edilecek alanların bir alt kümesini belirten seçici.
prettyPrint string no Girintili ve satır sonu içeren yanıtı döndürür. Varsayılan false.
userIp string no API çağrısının yapıldığı son kullanıcının IP adresini belirtir. IP başına kullanımı sınırlamak için kullanılır.
quotaUser string no Kullanıcının IP adresinin bilinmediği durumlarda userIp'e alternatif.
access_token string no OAuth 2.0 jetonu sağlamanın olası bir yöntemidir.
callback string no Yanıtı işleyen JavaScript geri çağırma işlevinin adı. JavaScript JSON-P isteklerinde kullanılır.
key string no Kota almak üzere uygulamanızı belirtmek üzere OAuth 1.0a yetkilendirmesi için kullanılır. Örneğin: key=AldefliuhSFADSfasdfasdfASdf.

Sorgu Parametresi Ayrıntıları

ids

ids=ga:12345
Zorunlu.
Analytics verilerini almak için kullanılan benzersiz kimlik. Bu kimlik, ga: ad alanının Analytics görünüm (profil) kimliğiyle birleştirilmesidir. Görünüm (profil) kimliğini, Google Analytics Management API'deki Görünüm (Profil) kaynağında id öğesi sağlayan analytics.management.profiles.list yöntemini kullanarak alabilirsiniz.

başlangıç-tarihi

start-date=2009-04-20
Zorunlu.
Tüm Analytics veri isteklerinde bir tarih aralığı belirtilmelidir. İstekte start-date ve end-date parametrelerini dahil etmezseniz sunucu bir hata döndürür. Tarih değerleri, YYYY-MM-DD kalıbını kullanarak veya today, yesterday ya da NdaysAgo kalıbını kullanarak göreli bir tarih için olabilir. Değerler [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) ile eşleşmelidir.
Geçerli en erken start-date tarihi 2005-01-01. Başlangıç tarihi için üst sınır kısıtlaması yoktur.
Göreli tarihler her zaman sorgu anındaki geçerli tarihe göre belirlenir ve sorguda belirtilen görünümün (profilin) saat dilimini temel alır.

Göreli tarihleri kullanarak son 7 gün (dünden itibaren) için örnek tarih aralığı:

  &start-date=7daysAgo
  &end-date=yesterday

bitiş tarihi

end-date=2009-05-20
Zorunlu.
Tüm Analytics veri isteklerinde bir tarih aralığı belirtilmelidir. İstekte start-date ve end-date parametrelerini dahil etmezseniz sunucu bir hata döndürür. Tarih değerleri, YYYY-MM-DD kalıbını kullanarak veya today, yesterday ya da NdaysAgo kalıbını kullanarak göreli bir tarih için olabilir. Değerler [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) ile eşleşmelidir.
Geçerli en erken end-date tarihi: 2005-01-01. end-date için üst sınır kısıtlaması yoktur.
Göreli tarihler her zaman sorgu anındaki geçerli tarihe göre belirlenir ve sorguda belirtilen görünümün (profilin) saat dilimini temel alır.

Göreli tarihler kullanarak son 10 gün (bugünden itibaren) için örnek tarih aralığı:

  &start-date=9daysAgo
  &end-date=today

boyutlar

dimensions=ga:browser,ga:city
İsteğe bağlı.
dimensions parametresi, metrikleri ortak ölçütlere (ör. ga:browser veya ga:city) göre ayırır. Sitenizdeki toplam sayfa görüntüleme sayısını sorabilirsiniz, ancak tarayıcıya göre ayrılmış sayfa görüntüleme sayısını sormak daha ilginç olabilir. Bu durumda, Firefox, Internet Explorer, Chrome vb. kaynaklı sayfa görüntülemelerinin sayısını görürsünüz.

Bir veri isteğinde dimensions kullanırken aşağıdaki kısıtlamaları göz önünde bulundurun:

  • Herhangi bir sorguda en fazla 7 boyut sağlayabilirsiniz.
  • Yalnızca boyutlardan oluşan bir sorgu gönderemezsiniz: İstenen tüm boyutları en az bir metrikle birleştirmeniz gerekir.
  • Yalnızca belirli boyutlar aynı sorguda sorgulanabilir. Hangi boyutların birlikte kullanılabileceğini görmek için Boyutlar ve Metrikler Referansı'ndaki geçerli kombinasyon aracını kullanın.


metrics

metrics=ga:sessions,ga:bounces
Zorunlu.
Sitenizdeki kullanıcı etkinliklerine (ör. tıklama veya sayfa görüntüleme sayısı) ilişkin toplu istatistikler. Bir sorguda dimensions parametresi yoksa döndürülen metrikler, istenen tarih aralığı için toplam sayfa görüntüleme sayısı veya toplam hemen çıkma sayısı gibi toplam değerler sağlar. Bununla birlikte, boyutlar istendiğinde değerler boyut değerine göre segmentlere ayrılır. Örneğin, ga:country ile istenen ga:pageviews değeri, ülke başına toplam sayfa görüntüleme sayısını döndürür. Metrik isterken aşağıdakileri unutmayın:
  • Tüm istekler en az bir metrik sağlamalıdır. Bir istek yalnızca boyutlardan oluşamaz.
  • Herhangi bir sorgu için en fazla 10 metrik sağlayabilirsiniz.
  • Birden fazla kategorideki çoğu metrik kombinasyonu, hiçbir boyut belirtilmedikçe birlikte kullanılabilir.
  • Bir metrik, yalnızca söz konusu metrik için geçerli kombinasyonlar geçerli olduğunda diğer boyutlar veya metriklerle birlikte kullanılabilir. Ayrıntılar için Boyutlar ve Metrikler Referansı'nı inceleyin.


sıralama

sort=ga:country,ga:browser
İsteğe bağlı.

Döndürülen verilerin sıralama düzenini ve sıralama yönünü belirten metrik ve boyutların listesi.

  • Sıralama sırası, listelenen metrik ve boyutların soldan sağa doğru sıralamasıyla belirlenir.
  • direction sıralama işlemi, varsayılan olarak artan şeklinde yapılır ve istenen alanda eksi işareti (-) ön eki kullanılarak azalan olarak değiştirilebilir.

Bir sorgunun sonuçlarını sıralayarak verilerinizle ilgili farklı sorular sorabilirsiniz. Örneğin, "En popüler ülkelerim hangileri ve en çok hangi tarayıcıları kullanıyorlar?" sorusunu ele almak için aşağıdaki parametreyle bir sorgu yapabilirsiniz. Önce ga:country, ardından ga:browser ölçütüne göre ve her ikisi de artan düzende sıralanır:

sort=ga:country,ga:browser

"En popüler tarayıcılarım hangileri ve bunları en çok hangi ülkelerde kullanıyorlar?" sorusu için aşağıdaki parametreyle sorgu oluşturabilirsiniz. İlk olarak ga:browser, ardından ga:country ölçütüne göre ve her ikisi de artan düzende sıralanır:
sort=ga:browser,ga:country

sort parametresini kullanırken aşağıdakileri göz önünde bulundurun:

  • Yalnızca dimensions veya metrics parametrelerinde kullandığınız boyutlara ya da metrik değerlerine göre sıralayın. İsteğiniz, boyutlar veya metrikler parametresinde belirtilmeyen bir alanda sıralanıyorsa bir hata alırsınız.
  • Varsayılan olarak dizeler, en-US yerel ayarında artan alfabetik düzende sıralanır.
  • Sayılar varsayılan olarak artan sayısal düzende sıralanır.
  • Tarihler varsayılan olarak tarihe göre artan düzende sıralanır.

filtreler

filters=ga:medium%3D%3Dreferral
İsteğe bağlı.

filters sorgu dizesi parametresi, isteğinizden döndürülen verileri kısıtlar. filters parametresini kullanmak için önce filtre uygulanacak bir boyut veya metrik, ardından filtre ifadesini girin. Örneğin, aşağıdaki sorgu 12134 görünümü (profil) için ga:pageviews ve ga:browser isteğinde bulunur. Burada ga:browser boyutu, Firefox dizesiyle başlar:

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

Filtrelenmiş sorgular, sonuca dahil edilen (veya gösterilmeyen) satırları kısıtlar. Sonuçtaki her satır filtreye göre test edilir: Filtre eşleşirse satır korunur, eşleşmezse satır çıkarılır.

  • URL Kodlaması: Google API istemci kitaplıkları, filtre operatörlerini otomatik olarak kodlar.
  • Boyut filtreleme: Filtreleme, tüm boyutlar toplanmadan önce gerçekleşir. Böylece döndürülen metrikler yalnızca alakalı boyutların toplamını gösterir. Yukarıdaki örnekte, sayfa görüntüleme sayısı yalnızca Firefox'un tarayıcı olduğu sayfa görüntülemelerdir.
  • Metrik filtreleme: Metriklere göre filtreleme, metrikler toplandıktan sonra gerçekleşir.
  • Geçerli kombinasyonlar: İstekteki tüm boyutların/metriklerin ve filtrenin geçerli kombinasyonlar olması koşuluyla, sorgunuzun parçası olmayan bir boyut veya metrik için filtre uygulayabilirsiniz. Örneğin, belirli bir tarayıcıda filtreleyerek sayfa görüntülemelerinin tarihli bir listesini sorgulamak isteyebilirsiniz. Daha fazla bilgi için Boyutlar ve Metrikler Referansı'nı inceleyin.

Filtre Söz Dizimi


Tek bir filtrede şu biçim kullanılır:

ga:name operator expression

Bu söz diziminde:

  • ad: Filtre uygulanacak boyut veya metriğin adı. Örneğin: ga:pageviews, sayfa görüntüleme metriklerinde filtre uygular.
  • operator — Kullanılacak filtre eşleştirmesinin türünü tanımlar. Operatörler boyutlara veya metriklere özeldir.
  • ifade, sonuçlara dahil edilecek veya sonuçlardan hariç tutulacak değerleri belirtir. İfadeler, normal ifade söz dizimini kullanır.

Filtre Operatörleri


Boyutlar için altı filtre operatörü ve metrikler için altı filtre operatörü vardır. Operatörlerin URL sorgu dizelerine eklenebilmesi için URL olarak kodlanmış olmaları gerekir.

İpucu: Sorgu Gezgini dize ve boşluk içeren URL'leri otomatik olarak kodladığından, URL kodlaması gerektiren filtreler tasarlamak için Veri Feed'i Sorgu Gezgini'ni kullanın.

Metrik Filtreleri
Operatör Açıklama URL Kodlu Form Örnekler
== Şuna eşittir: %3D%3D Sayfadaki sürenin tam olarak on saniye olduğu sonuçları döndürür:
filters=ga:timeOnPage%3D%3D10
!= Eşit değildir !%3D Sayfada geçirilen sürenin on saniye olmadığı sonuçları döndürün:
filters=ga:timeOnPage!%3D10
> Büyüktür %3E Sayfadaki sürenin kesinlikle on saniyeden uzun olduğu sonuçları döndürün:
filters=ga:timeOnPage%3E10
< Küçüktür %3C Sayfada geçirilen sürenin kesinlikle on saniyeden kısa olduğu sonuçları döndürün:
filters=ga:timeOnPage%3C10
>= Büyüktür veya eşittir %3E%3D Sayfada geçirilen sürenin on saniye veya daha uzun olduğu sonuçları döndürün:
filters=ga:timeOnPage%3E%3D10
<= Küçüktür veya eşittir %3C%3D Sayfada geçirilen sürenin on saniye veya daha kısa olduğu sonuçları döndürün:
filters=ga:timeOnPage%3C%3D10

Boyut Filtreleri
Operatör Açıklama URL Kodlu Form Örnek
== Tam eşleme %3D%3D Şehrin Irvine olduğu toplu metrikler:
filters=ga:city%3D%3DIrvine
!= Eşleşmez !%3D Şehrin Irvine olmadığı toplu metrikler:
filters=ga:city!%3DIrvine
=@ Alt dize içerir %3D@ Şehirde York bulunan toplu metrikler:
filters=ga:city%3D@York
!@ Alt dize içermez !@ Şehirde York olmayan toplu metrikler:
filters=ga:city!@York
=~ Normal ifadeyle eşleşme içerir %3D~ Şehrin Yeni ile başladığı metrikleri toplayın:
filters=ga:city%3D~%5ENew.*
(%5E, bir kalıbı dizenin başına sabitleyen ^ karakterinden kodlanmış URL'dir.)
!~ Normal ifadeyle eşleşmez !~ Şehrin Yeni ile başlamadığı toplu metrikler:
filters=ga:city!~%5ENew.*

İfadeleri Filtrele

Filtre ifadelerine ilişkin birkaç önemli kural vardır:

  • URL ile ayrılmış karakterler: & gibi karakterler her zamanki gibi URL olarak kodlanmalıdır.
  • Ayrılmış karakterler: Noktalı virgül ve virgül, bir ifadede göründüğünde ters eğik çizgiden kaçınılmalıdır:
    • noktalı virgül \;
    • virgül \,
  • Normal İfadeler: =~ ve !~ operatörlerini kullanarak filtre ifadelerinde normal ifadeleri de kullanabilirsiniz. Söz dizimi, Perl normal ifadelerine benzer ve şu ek kurallara sahiptir:
    • Maksimum 128 karakter uzunluğunda: 128 karakterden uzun normal ifadeler, sunucudan bir 400 Bad Request durum kodu döndürülmesiyle sonuçlanır.
    • Büyük/küçük harfe duyarlılık: Normal ifade eşleşmesi büyük/küçük harfe duyarlı değildir.

Filtreleri Birleştirme

Filtreler, OR ve AND boole mantığı kullanılarak birleştirilebilir. Bu sayede, bir filtre ifadesinin 128 karakter sınırını etkili bir şekilde genişletebilirsiniz.

VEYA

OR operatörü, virgül (,) kullanılarak tanımlanır. AND operatörüne göre önceliklidir ve boyutlar ile metrikleri aynı ifadede birleştirmek için KULLANILAMAZ.

Örnekler: (her biri URL kodlamalı olmalıdır)

Ülke (ABD VEYA Kanada):
ga:country==United%20States,ga:country==Canada

(Windows VEYA Macintosh) işletim sistemlerinde Firefox kullanıcıları:
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

VE

AND operatörü, noktalı virgül (;) kullanılarak tanımlanır. Öncesinde OR operatörü bulunur ve CAN, boyutlar ile metrikleri aynı ifadede birleştirmek için kullanılabilir.

Örnekler: (her biri URL kodlamalı olmalıdır)

Ülke ABD VE tarayıcı Firefox:
ga:country==United%20States;ga:browser==Firefox

Ülke ABD ve dil "en" ile başlamıyor:
ga:country==United%20States;ga:language!~^en.*

İşletim sistemi (Windows VEYA Macintosh) VE tarayıcı (Firefox VEYA Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

Ülke ABD ve oturum sayısı 5'ten fazla:
ga:country==United%20States;ga:sessions>5



segmentlere ayır

segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
İsteğe bağlı.

Temel Reporting API'de segment istemeyle ilgili tüm ayrıntılar için Segmentler Geliştirici Kılavuzu'na bakın.

Segmentlere kavramsal bir genel bakış için Yardım Merkezi'ndeki Segmentler Özelliği Referansı ve Segmentler bölümlerini inceleyin.

Segmentlerde izin verilen boyut ve metrikler.
Segmentlerde bazı boyut ve metrikler kullanılamaz. Segmentlerde hangi boyutlara ve metriklere izin verildiğini incelemek için Boyut ve Metrik Gezgini'ni ziyaret edin.


samplingLevel

samplingLevel=DEFAULT
İsteğe bağlı.
Raporlama sorgusunun örnekleme düzeyini (sonucu hesaplamak için kullanılan oturum sayısını) ayarlamak için bu parametreyi kullanın. İzin verilen değerler web arayüzüyle tutarlıdır ve şunları içerir:
  • DEFAULT: Hız ve doğruluğu dengeleyen bir örnek boyutuyla yanıtı döndürür.
  • FASTER: Daha küçük örnek boyutuyla hızlı yanıt döndürür.
  • HIGHER_PRECISION: Büyük bir örnek boyutu kullanarak daha doğru bir yanıt döndürür ancak bu, yanıtın daha yavaş olmasına neden olabilir.
Sağlanmazsa DEFAULT örnekleme düzeyi kullanılır.
Bir sorgu için kullanılan oturumların yüzdesinin nasıl hesaplanacağıyla ilgili ayrıntılar için Örnekleme bölümünü inceleyin.

boş-satırları-dahil et

include-empty-rows=true
İsteğe bağlı.
Varsayılan olarak true (doğru) değerine ayarlanır. Yanlış değerine ayarlanırsa tüm metrik değerlerinin sıfır olduğu satırlar yanıttan çıkarılır. Örneğin, bir sorguya birden fazla metrik eklerseniz satırlar yalnızca tüm metrik değerleri sıfır olduğunda kaldırılır. Bu, geçerli satır sayısının beklenen boyut değerlerinden çok daha küçük olması beklenen bir istekte bulunurken yararlı olabilir.

start-index

start-index=10
İsteğe bağlı.
Bu değer sağlanmazsa başlangıç dizini 1 olur. (Sonuç dizinleri 1 tabanlıdır. Yani ilk satır 0 satırı değil, 1 satırıdır.) totalResults değerinin 10.000'i aştığı ve 10.001 ve ötesinde dizine eklenen satırları almak istediğiniz durumlarda bu parametreyi max-results parametresiyle birlikte sayfalara ayırma mekanizması olarak kullanın.

max-results

max-results=100
İsteğe bağlı.
Bu yanıta dahil edilecek maksimum satır sayısı. Öğelerin bir alt kümesini almak için bunu start-index ile birlikte kullanabilir veya döndürülen öğelerin sayısını kısıtlamak için ilkinden başlayarak tek başına kullanabilirsiniz. max-results sağlanmazsa sorgu varsayılan maksimum 1.000 satır değerini döndürür.
Analytics Core Reporting API, istediğiniz satır sayısından bağımsız olarak istek başına maksimum 10.000 satır döndürür. Ayrıca, beklediğiniz sayıda boyut segmenti yoksa istenenden daha az satır döndürebilir. Örneğin, ga:country için 300'den az olası değer vardır. Bu nedenle, yalnızca ülkeye göre segmentlere ayırırken max-results öğesini daha yüksek bir değere ayarlasanız bile 300'den fazla satır alamazsınız.

çıkış

output=dataTable
İsteğe bağlı.
Yanıtta döndürülen Analytics verilerinin çıkış türünü ayarlamak için bu parametreyi kullanın. İzin verilen değerler şunlardır:
  • json — Yanıtta bir JSON nesnesi içeren varsayılan rows özelliğini verir.
  • dataTable — Yanıtta Veri Tablosu nesnesi içeren bir dataTable özelliği çıkarır. Bu Data Table nesnesi doğrudan Google Charts görselleştirmeleri ile kullanılabilir.
Sağlanmazsa varsayılan JSON yanıtı kullanılır.

fields

fields=rows,columnHeaders(name,dataType)
İsteğe bağlı.

Kısmi yanıtta hangi alanların döndürüleceğini belirtir. API yanıtında alanların yalnızca bir alt kümesini kullanıyorsanız hangi alanların dahil edileceğini belirtmek için fields parametresini kullanabilirsiniz.

Alan istek parametresi değerinin biçimi, genel olarak XPath söz dizimine dayalıdır. Desteklenen söz dizimi aşağıda özetlenmiştir.

  • Birden çok alan seçmek için virgülle ayrılmış liste kullanın.
  • a alanı içine yerleştirilmiş bir b alanını seçmek için a/b işaretini, b içine yerleştirilmiş bir c alanını seçmek için a/b/c değerini kullanın.
  • İfadeleri parantez içine "( )" yerleştirerek dizi veya nesnelerin belirli alt alanlarını istemek için alt seçici kullanın.
    Örneğin: fields=columnHeaders(name,dataType), columnHeaders dizisinde yalnızca name ve dataType alanlarını döndürür. Tek bir alt alan da belirtebilirsiniz. Burada fields=columnHeader(name), fields=columnHeader/name ile eşdeğerdir.

prettyPrint

prettyPrint=false
İsteğe bağlı.

true ise yanıtı kullanıcıların okuyabileceği bir biçimde döndürür. Varsayılan değer: false.


quotaUser

quotaUser=4kh4r2h4
İsteğe bağlı.

Kullanıcının IP adresinin bilinmediği durumlarda bile sunucu tarafı uygulamadan kullanıcı başına kotaları zorunlu kılmanıza olanak tanır. Örneğin App Engine'de kullanıcı adına cron işleri çalıştıran uygulamalarda bu durum yaşanabilir. Bir kullanıcıyı benzersiz şekilde tanımlayan herhangi bir rastgele dize seçebilirsiniz. Ancak bu dize 40 karakterle sınırlıdır.

Bu ayar, her ikisi de sağlanırsa userIp politikasını geçersiz kılar.


Yanıt

Başarılı olursa bu istek, aşağıda tanımlanan JSON yapısına sahip bir yanıt gövdesi döndürür. output parametresi dataTable olarak ayarlanırsa istek, aşağıda tanımlanan JSON (Veri Tablosu) yapısına sahip bir yanıt gövdesi döndürür.

Not: "results" terimi, sorguyla eşleşen satır grubunun tamamını, "yanıt" ise geçerli sonuç sayfasında döndürülen satır grubunu ifade eder. Toplam sonuç sayısı, itemsPerPage bölümünde açıklandığı gibi mevcut yanıtın sayfa boyutundan büyükse bunlar farklı olabilir.

JSON
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

Yanıt Alanları

Yanıt gövde yapısının özellikleri aşağıdaki gibi tanımlanır:

Mülk Adı Değer Açıklama
kind string Kaynak türü. Değer "analytics#gaData"dır.
id string Bu veri yanıtı için bir kimlik.
query object Bu nesne, sorguya parametre olarak iletilen tüm değerleri içerir. Her alanın anlamı, karşılık gelen sorgu parametresinin açıklamasında açıklanmıştır.
query.start-date string Başlangıç tarihi.
query.end-date string Bitiş tarihi.
query.ids string Benzersiz tablo kimliği.
query.dimensions[] list Analiz boyutlarının listesi.
query.metrics[] list Analiz metriklerinin listesi.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean Varsayılan olarak true (doğru) değerine ayarlanır; false (yanlış) değerine ayarlanırsa tüm metrik değerlerinin sıfır olduğu satırlar yanıttan çıkarılır.
query.sort[] list Verilerin sıralandığı metriklerin veya boyutların listesi.
query.filters string Metrik veya boyut filtrelerinin virgülle ayrılmış listesi.
query.segment string Analytics segmenti.
query.start-index integer Dizini başlat.
query.max-results integer Sayfa başına maksimum sonuç sayısı.
startIndex integer start-index sorgu parametresi tarafından belirtilen satırların başlangıç dizini. Varsayılan değer 1'dir.
itemsPerPage integer Döndürülen gerçek satır sayısından bağımsız olarak yanıtın içerebileceği maksimum satır sayısı. max-results sorgu parametresi belirtilirse itemsPerPage değeri, max-results veya 10.000 aralığından en az olanı olur. Varsayılan itemsPerPage değeri 1.000'dir.
totalResults integer Yanıtta döndürülen satır sayısından bağımsız olarak, sorgu sonucundaki toplam satır sayısı. Çok sayıda satırla sonuçlanan sorgular için totalResults, itemsPerPage değerinden büyük olabilir. totalResults ile ilgili daha fazla açıklama için Çağrı ve büyük sorgular için itemsPerPage bölümlerine bakın.
startDate string Veri sorgusunun start-date parametresiyle belirtilen başlangıç tarihi.
endDate string Veri sorgusu için end-date parametresiyle belirtilen bitiş tarihi.
profileInfo object Verilerinin istendiği görünüm (profil) hakkındaki bilgiler. Görüntüleme (Profil) verilerine Google Analytics Management API aracılığıyla erişilebilir.
profileInfo.profileId string Görünüm (Profil) kimliği; örneğin, 1174.
profileInfo.accountId string Bu görünümün (profilin) ait olduğu hesap kimliği (ör. 30481).
profileInfo.webPropertyId string Bu görünümün (profilin) ait olduğu Web Mülkü Kimliği (örneğin, UA-30481-1).
profileInfo.internalWebPropertyId string Bu görünümün (profilin) ait olduğu web mülkünün dahili kimliği (örneğin, UA-30481-1).
profileInfo.profileName string Görünümün (profilin) adı.
profileInfo.tableId string Görünüm (profil) için "ga:" ve ardından görünüm (profil) kimliğinden oluşan tablo kimliği.
containsSampledData boolean Yanıt örneklenmiş veriler içeriyorsa doğru değerini alır.
sampleSize string Örneklenmiş verileri hesaplamak için kullanılan örnek sayısı.
sampleSpace string Toplam örnekleme alanı boyutu. Bu, örneklerin seçildiği toplam kullanılabilir örnek alanı boyutunu gösterir.
columnHeaders[] list Boyut adlarını ve ardından metrik adlarını listeleyen sütun başlıkları. Boyut ve metriklerin sırası, metrics ve dimensions parametreleri aracılığıyla istekte belirtilenlerle aynıdır. Başlık sayısı, boyutların sayısı ve metriklerin sayısıdır.
columnHeaders[].name string Boyut veya metriğin adı.
columnHeaders[].columnType string Sütun türü. "DIMENSION" veya "METRIC".
columnHeaders[].dataType string Veri türü. Boyut sütunu başlıklarında veri türü olarak yalnızca STRING bulunur. Metrik sütun başlıklarında INTEGER, PERCENT, TIME, CURRENCY, FLOAT gibi metrik değerleri için veri türleri bulunur. Olası tüm veri türleri için meta veri API yanıtı bölümünü inceleyin.
totalsForAllResults object Metrik adları ve değerlerinden oluşan anahtar/değer çiftleri olarak, istenen metrikler için toplam değerler. Metrik toplamlarının sırası, istekte belirtilen metrik sırası ile aynıdır.
rows[] list Her satırda, metrik değerlerinin ardından boyut değerlerinin bir listesini içeren Analytics veri satırları. Boyutların ve metriklerin sırası, istekte belirtilenle aynıdır. Her satırda N alan listesi bulunur. Bu listede N, boyut sayısı + metrik sayısı anlamına gelir.
JSON (Veri Tablosu)
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

Yanıt Alanları

Yanıt gövde yapısının özellikleri aşağıdaki gibi tanımlanır:

Mülk Adı Değer Açıklama
kind string Kaynak türü. Değer "analytics#gaData"dır.
id string Bu veri yanıtı için bir kimlik.
query object Bu nesne, sorguya parametre olarak iletilen tüm değerleri içerir. Her alanın anlamı, karşılık gelen sorgu parametresinin açıklamasında açıklanmıştır.
query.start-date string Başlangıç tarihi.
query.end-date string Bitiş tarihi.
query.ids string Benzersiz tablo kimliği.
query.dimensions[] list Analiz boyutlarının listesi.
query.metrics[] list Analiz metriklerinin listesi.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean Varsayılan olarak true (doğru) değerine ayarlanır; false (yanlış) değerine ayarlanırsa tüm metrik değerlerinin sıfır olduğu satırlar yanıttan çıkarılır.
query.sort[] list Verilerin sıralandığı metriklerin veya boyutların listesi.
query.filters string Metrik veya boyut filtrelerinin virgülle ayrılmış listesi.
query.segment string Analytics segmenti.
query.start-index integer Dizini başlat.
query.max-results integer Sayfa başına maksimum sonuç sayısı.
startIndex integer start-index sorgu parametresi tarafından belirtilen satırların başlangıç dizini. Varsayılan değer 1'dir.
itemsPerPage integer Döndürülen gerçek satır sayısından bağımsız olarak yanıtın içerebileceği maksimum satır sayısı. max-results sorgu parametresi belirtilirse itemsPerPage değeri, max-results veya 10.000 aralığından en az olanı olur. Varsayılan itemsPerPage değeri 1.000'dir.
totalResults integer Yanıtta döndürülen satır sayısından bağımsız olarak, sorgu sonucundaki toplam satır sayısı. Çok sayıda satırla sonuçlanan sorgular için totalResults, itemsPerPage değerinden büyük olabilir. totalResults ile ilgili daha fazla açıklama için Çağrı ve büyük sorgular için itemsPerPage bölümlerine bakın.
startDate string Veri sorgusunun start-date parametresiyle belirtilen başlangıç tarihi.
endDate string Veri sorgusu için end-date parametresiyle belirtilen bitiş tarihi.
profileInfo object Verilerinin istendiği görünüm (profil) hakkındaki bilgiler. Görüntüleme (Profil) verilerine Google Analytics Management API aracılığıyla erişilebilir.
profileInfo.profileId string Görünüm (Profil) kimliği; örneğin, 1174.
profileInfo.accountId string Bu görünümün (profilin) ait olduğu hesap kimliği (ör. 30481).
profileInfo.webPropertyId string Bu görünümün (profilin) ait olduğu Web Mülkü Kimliği (örneğin, UA-30481-1).
profileInfo.internalWebPropertyId string Bu görünümün (profilin) ait olduğu web mülkünün dahili kimliği (örneğin, UA-30481-1).
profileInfo.profileName string Görünümün (profilin) adı.
profileInfo.tableId string Görünüm (profil) için "ga:" ve ardından görünüm (profil) kimliğinden oluşan tablo kimliği.
containsSampledData boolean Yanıt örneklenmiş veriler içeriyorsa doğru değerini alır.
sampleSize string Örneklenmiş verileri hesaplamak için kullanılan örnek sayısı.
sampleSpace string Toplam örnekleme alanı boyutu. Bu, örneklerin seçildiği toplam kullanılabilir örnek alanı boyutunu gösterir.
columnHeaders[] list Boyut adlarını ve ardından metrik adlarını listeleyen sütun başlıkları. Boyut ve metriklerin sırası, metrics ve dimensions parametreleri aracılığıyla istekte belirtilenlerle aynıdır. Başlık sayısı, boyutların sayısı ve metriklerin sayısıdır.
columnHeaders[].name string Boyut veya metriğin adı.
columnHeaders[].columnType string Sütun türü. "DIMENSION" veya "METRIC".
columnHeaders[].dataType string Veri türü. Boyut sütunu başlıklarında veri türü olarak yalnızca STRING bulunur. Metrik sütun başlıklarında INTEGER, PERCENT, TIME, CURRENCY, FLOAT gibi metrik değerleri için veri türleri bulunur. Olası tüm veri türleri için meta veri API yanıtı bölümünü inceleyin.
totalsForAllResults object Metrik adları ve değerlerinden oluşan anahtar/değer çiftleri olarak, istenen metrikler için toplam değerler. Metrik toplamlarının sırası, istekte belirtilen metrik sırası ile aynıdır.
dataTable object Google Grafikleri ile kullanılabilecek bir Veri Tablosu nesnesi.
dataTable.cols[] list Metriklerin takip ettiği boyutlar için sütun tanımlayıcılarının bir listesi. Boyut ve metriklerin sırası, istekte metrics ve dimensions parametreleri aracılığıyla belirtilenlerle aynıdır. Sütun sayısı, boyut sayısı + metrik sayısıdır.
dataTable.cols[].id string Belirli bir sütuna referans vermek için kullanılabilen (sütun dizinlerini kullanmaya alternatif olarak) kimlik. Bu değeri ayarlamak için boyut veya metrik kimliği kullanılır.
dataTable.cols[].label string Sütun için bir etiket (görselleştirme tarafından görüntülenebilir). Bu değeri ayarlamak için boyut veya metrik kimliği kullanılır.
dataTable.cols[].type string Bu sütunun veri türü.
dataTable.rows[] list Her satırın, boyutların takip ettiği metriklerin hücre değerlerinin listesini içeren bir nesne olduğu Veri Tablosu biçimindeki Analytics veri satırları. Boyutların ve metriklerin sırası, istekte belirtilenle aynıdır. Her hücrede, N alandan oluşan bir liste bulunur. Bu listede N, boyut sayısı + metrik sayısı anlamına gelir.

Hata Kodları

İstek başarılı olursa Core Reporting API bir 200 HTTP durum kodu döndürür. Sorgu işlenirken hata oluşursa API bir hata kodu ve açıklama döndürür. Analytics API'yi kullanan her uygulamanın, doğru hata işleme mantığını uygulaması gerekir. Hata kodları ve bunların nasıl ele alınacağıyla ilgili ayrıntılar için Hata Yanıtları başvuru kılavuzunu okuyun.

Deneyin.

Core Reporting API'ye yapılan sorguları deneyebilirsiniz.

  • Bir sorguda geçerli metrik ve boyut kombinasyonlarını görmek amacıyla Sorgu Gezgini'nde parametreler için örnek değerler girin. Örnek sorgunun sonuçları, belirtilen tüm metrik ve boyutların değerlerini içeren bir tablo olarak gösterilir.

  • Canlı veriler hakkında istekte bulunmak ve yanıtı JSON biçiminde görmek için Google Data API Explorer'daki analytics.data.ga.get yöntemini deneyin.

Örneklendirme

Google Analytics belirli boyut ve metrik kombinasyonlarını anında hesaplar. Google Analytics, verileri makul bir sürede döndürmek için yalnızca verilerin bir örneğini işleyebilir.

samplingLevel parametresini ayarlayarak bir istek için kullanılacak örnekleme düzeyini belirtebilirsiniz.

Core Reporting API yanıtı örneklenmiş veriler içeriyorsa containsSampledData yanıt alanı true olur. Ayrıca şu 2 özellik, sorgunun örnekleme düzeyi hakkında bilgi sağlar: sampleSize ve sampleSpace. Bu 2 değeri kullanarak sorgu için kullanılan oturumların yüzdesini hesaplayabilirsiniz. Örneğin, sampleSize değeri 201,000 ve sampleSpace değeri 220,000 ise rapor,oturumların toplam sayısını (201.000 / 220.000) x 100 = % 91,36 'yı temel alır.

Örneklemenin genel bir açıklaması ve Google Analytics'te nasıl kullanıldığı için Örnekleme bölümüne bakın.


Büyük Veri Sonuçlarını İşleme

Sorgunuzun büyük bir sonuç kümesi döndürmesini bekliyorsanız API sorgunuzu optimize etmenize, hataları önlemenize ve kota aşımlarını en aza indirmenize yardımcı olacak aşağıdaki yönergeleri kullanın. Herhangi bir API isteğinde maksimum 7 boyuta ve 10 metriğe izin vererek bir performans temeli oluşturduğumuzu unutmayın. Çok sayıda metrik ve boyut belirten bazı sorguların işlenmesi diğerlerinden daha uzun sürebilir. Ancak, istenen metrik sayısının sınırlanması sorgu performansını iyileştirmek için yeterli olmayabilir. Bunun yerine, en iyi performans sonuçları için aşağıdaki teknikleri kullanabilirsiniz.

Sorgu Başına Boyut Azaltma

API, herhangi bir istekte en fazla 7 boyutun belirtilmesine olanak tanır. Çoğu zaman, Google Analytics bu karmaşık sorguların sonuçlarını anında hesaplamak zorundadır. Bu, özellikle sonuçta elde edilen satır sayısı yüksekse çok zaman alabilir. Örneğin, anahtar kelimeleri şehir bazında sorgulamak, milyonlarca veri satırıyla eşleşebilir. Sorgunuzdaki boyutların sayısını sınırlayarak Google Analytics'in işlemesi gereken satır sayısını azaltarak performansı artırabilirsiniz.

Sorguyu Tarih Aralığına Göre Bölme

Tek bir uzun tarih aralığının tarih içeren tarih içeren sonuçlarını incelemek yerine, her seferinde bir hafta, hatta bir gün için ayrı sorgular oluşturmayı deneyin. Elbette, büyük bir veri kümesinde tek bir güne ait veriler için yapılan bir istek bile max-results değerinden daha yüksek değer döndürebilir. Bu durumda sayfalamadan kaçınılamaz. Ancak sorgunuzla eşleşen satır sayısı max-results değerinden fazlaysa tarih aralığının ayrılması, sonuçların alınması için toplam süreyi kısaltabilir. Bu yaklaşım, hem tek iş parçacıklı hem de paralel sorgularda performansı artırabilir.

Sayfalama

Sonuçlara göz atmak, büyük sonuç kümelerini yönetilebilir gruplara bölmenin faydalı bir yolu olabilir. totalResults alanı, kaç tane eşleşen satır olduğunu belirtir ve itemsPerPage, sonuçta döndürülebilecek maksimum satır sayısını belirtir. totalResults/itemsPerPage oranı yüksekse tek tek sorgular gereğinden uzun sürebilir. Görüntüleme amacıyla olduğu gibi yalnızca sınırlı sayıda satıra ihtiyacınız varsa max-results parametresi aracılığıyla yanıt boyutu için açık bir sınır ayarlamak sizin için daha uygun olabilir. Bununla birlikte, uygulamanızın büyük bir sonuç grubunu bütün olarak işlemesi gerekiyorsa izin verilen maksimum satır sayısını istemek daha verimli olabilir.

gzip'i kullanma

Her bir istek için gereken bant genişliğini azaltmanın kolay ve rahat bir yolu, gzip sıkıştırmayı etkinleştirmektir. Sıkıştırılmış sonuçların açılması için fazladan CPU süresi gerekse de, ağ maliyetlerinin dengelenmesi genellikle buna çok değer. gzip kodlamalı bir yanıt almak için iki şey yapmanız gerekir: Bir Accept-Encoding üst bilgisi ayarlayın ve kullanıcı aracınızı gzip dizesini içerecek şekilde değiştirin. Aşağıda, gzip sıkıştırmasını etkinleştirmek için doğru şekilde oluşturulmuş bir HTTP üst bilgisi örneği verilmiştir:

Accept-Encoding: gzip
User-Agent: my program (gzip)