Temel Raporlama API'sı - Başvuru Kılavuzu

Bu belge, Core Reporting API 3.0 sürümü için hem sorgu hem de yanıta yönelik tam referans sağlar.

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 özgü arayüzlere sahiptir.

API, REST dolu 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 Parametrelerinin Özeti

Aşağıdaki tabloda, temel raporlama API'si tarafından kabul edilen tüm sorgu parametreleri özetlenmektedir. Ayrıntılı bir açıklama için her bir parametre 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 getirmenin 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 boyutların virgülle ayrılmış 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 metrikler 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ı bir 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 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.
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ıdır.
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 Seçici, yanıta dahil edilecek alanların bir alt kümesini belirtiyor.
prettyPrint string no Girintiler ve satır sonları 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 alternatiftir.
access_token string no OAuth 2.0 jetonu sağlamanın olası bir yoludur.
callback string no Yanıtı işleyen JavaScript geri çağırma işlevinin adı. JavaScript JSON-P isteklerinde kullanılır.
key string no Uygulamanızı kota alacak şekilde belirtmek amacıyla OAuth 1.0a yetkilendirmesinde 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 sağlayan analytics.management.profiles.list yöntemini kullanarak alabilirsiniz.

başlangıç-tarihi

start-date=2009-04-20
Zorunlu.
Tüm Analytics veri isteklerinde tarih aralığı belirtilmelidir. İsteğe start-date ve end-date parametrelerini dahil etmezseniz sunucu bir hata döndürür. Tarih değerleri, YYYY-MM-DD kalıbı kullanılarak belirli bir tarih ya da today, yesterday veya NdaysAgo kalıbı kullanılarak göreli 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, 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 tarihler kullanılarak son 7 gün (dünden başlayarak) için örnek tarih aralığı:

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

bitiş tarihi

end-date=2009-05-20
Zorunlu.
Tüm Analytics veri isteklerinde tarih aralığı belirtilmelidir. İsteğe start-date ve end-date parametrelerini dahil etmezseniz sunucu bir hata döndürür. Tarih değerleri, YYYY-MM-DD kalıbı kullanılarak belirli bir tarih ya da today, yesterday veya NdaysAgo kalıbı kullanılarak göreli 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, 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 kullanılarak son 10 gün için (bugünden başlamak üzere) ö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 sayfa görüntüleme sayısını öğrenmek daha ilginç olabilir. Bu durumda Firefox, Internet Explorer, Chrome ve benzerlerinden alınan 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.
Kullanıcıların sitenizdeki etkinlikleri (ör. tıklama veya sayfa görüntüleme sayısı) ile ilgili toplu istatistikler. Bir sorguda dimensions parametresi yoksa döndürülen metrikler, istenen tarih aralığı için genel sayfa görüntüleme sayısı veya toplam hemen çıkma sayısı gibi toplam değerler sağlar. Ancak, boyutlar istendiğinde, değerler boyut değerine göre segmentlere ayrılır. Örneğin, ga:country ile istenen ga:pageviews, ülke başına toplam sayfa görüntüleme sayısını döndürür. Metrik isterken aşağıdaki hususları göz önünde bulundurun:
  • 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, herhangi bir boyut belirtilmedikçe birlikte kullanılabilir.
  • Bir metrik, yalnızca o 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ı'na bakın.

sıralama

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

Döndürülen veriler için sıralama düzenini ve sıralama yönünü belirten metrik ve boyutların listesi.

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

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

sort=ga:country,ga:browser

"En popüler tarayıcılarım hangileri ve bunları en çok hangi ülkelerde kullanıyorlar?" sorusunu yanıtlamak için aşağıdaki parametreyle sorgu oluşturabilirsiniz. Önce ga:browser, ardından ga:country ölçütüne göre, 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 alana göre sıralanıyorsa hata mesajı 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
  1. Filtre Söz Dizimi
  2. Filtre Operatörleri
  3. İfadeleri Filtrele
  4. Filtreleri Birleştirme
İsteğe bağlı.

filters sorgu dizesi parametresi, isteğinizden döndürülen verileri kısıtlar. filters parametresini kullanmak için filtrenin uygulanacağı boyut veya metriği, 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

Filtrelenen sorgular, sonuca dahil edilen (veya sunulmayan) 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, herhangi bir boyut 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ülemelerin 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ıyı filtreleyen, tarihli bir sayfa görüntüleme listesi sorgulamak isteyebilirsiniz. Daha fazla bilgi için Boyutlar ve Metrikler Referansı'na bakın.

Filtre Söz Dizimi


Tek bir filtre şu biçimi kullanı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.
  • operatör — Kullanılacak filtre eşleşmesinin 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 Araştırma Aracı 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 Sayfada geçirilen sürenin tam olarak on saniye olduğu sonuçları döndür:
filters=ga:timeOnPage%3D%3D10
!= Eşit değildir !%3D Sayfadaki sürenin on saniye olmadığı sonuçları döndür:
filters=ga:timeOnPage!%3D10
> Büyüktür %3E Sayfadaki sürenin kesinlikle on saniyeden uzun olduğu sonuçları döndür:
filters=ga:timeOnPage%3E10
< Küçüktür %3C Sayfada geçirilen sürenin 10 saniyeden kısa olduğu sonuçları döndür:
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:
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:
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@ Şehrin York'u içerdiği 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 ifadeleri için iki ö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üklerinde 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 aşağıdaki ek kurallara sahiptir:
    • Maksimum 128 karakter uzunluğu: 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. Önünde 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 ise:
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'dir VE oturum sayısı 5'ten fazladır:
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 Raporlama API'sinde nasıl segment isteğinde bulunabileceğinizle 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 Özellik Referansı ve Segmentler'e bakın.

Segmentlerde izin verilen boyut ve metrikler.
Segmentlerde tüm 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ı) 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ı bir 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.
Bu bilgi 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; false (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 faydalı olabilir.

start-index

start-index=10
İsteğe bağlı.
Bu belirtilmediği takdirde, 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 durumlar için bu parametreyi max-results parametresiyle birlikte sayfalandı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ı ilkinden başlayarak sınırlandırmak için tek başına kullanabilirsiniz. max-results belirtilmezse sorgu, varsayılan maksimum 1.000 satırlık sınırı döndürür.
Analytics Core Reporting API, istediğiniz satır sayısı ne olursa olsun istek başına maksimum 10.000 satır döndürür. Ayrıca, beklediğiniz kadar çok 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ırma işlemi yaptığınızda max-results değerini 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, 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 Grafikler 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 döndürülecek alanları 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 bağlıdır. Desteklenen söz dizimi aşağıda özetlenmiştir.

  • Birden çok alan seçmek için virgülle ayrılmış bir liste kullanın.
  • a alanı içine yerleştirilmiş bir b alanını seçmek için a/b işlevini, b içine yerleştirilmiş bir c alanını seçmek için a/b/c işlevini kullanın.
  • Parantez "( )" içine ifadeler yerleştirerek dizi veya nesnelerin belirli bir alt alan kümesini 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. Ayrıca fields=columnHeader(name), fields=columnHeader/name ile eşdeğer olan tek bir alt alan da belirtebilirsiniz.

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ındaki bir 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 durumla karşılaşılabilir. Bir kullanıcıyı benzersiz olarak tanımlayan herhangi bir dizeyi seçebilirsiniz ancak bu dize 40 karakterle sınırlıdır.

Her ikisi de sağlanırsa bu ayar userIp öğesini 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 tüm satır grubunu, "yanıt" ise geçerli sonuç sayfasında döndürülen satır grubunu ifade eder. itemsPerPage bölümünde açıklandığı gibi, toplam sonuç sayısı geçerli yanıtın sayfa boyutundan büyükse sonuçlar 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 Başlangıç dizini.
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 değerinden daha küçüktür. itemsPerPage öğesinin varsayılan 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. Büyük sorgular için totalResults ve itemsPerPage ile ilgili daha fazla açıklama için Sayfalama bölümüne bakın.
startDate string Veri sorgusunun start-date parametresiyle belirtilen başlangıç tarihi.
endDate string Veri sorgusunun end-date parametresiyle belirtilen bitiş tarihi.
profileInfo object Verilerinin istendiği görünüm (profil) hakkında bilgi. Görünüm (Profil) verileri, Google Analytics Management API aracılığıyla kullanılabilir.
profileInfo.profileId string Görünüm (Profil) kimliği (ör. 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 UA-30481-1 gibi dahili kimliği.
profileInfo.profileName string Görünümün (profil) 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. Ö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ı, istekte metrics ve dimensions parametreleri aracılığıyla belirtilenlerle aynıdır. Başlık sayısı, boyut sayısı + metrik 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ı veri türü olarak yalnızca STRING içerir. Metrik sütunu başlıklarında INTEGER, PERCENT, TIME, CURRENCY, FLOAT vb. metrik değerleri için veri türleri bulunur. Olası tüm veri türleri için metadata API yanıtı bölümünü inceleyin.
totalsForAllResults object Metrik adları ve değerlerinden oluşan anahtar/değer çiftleri olarak, istenen metriklerin toplam değerleri. Metrik toplamlarının sırası, istekte belirtilen metrik sırası ile aynıdır.
rows[] list Her satırda, boyut değerleri ve ardından metrik değerlerinden oluşan bir liste içeren Analytics veri satırları. Boyut ve metriklerin sırası, istekte belirtilenle aynıdır. Her satırda, N alan içeren bir liste 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 Başlangıç dizini.
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 değerinden daha küçüktür. itemsPerPage öğesinin varsayılan 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. Büyük sorgular için totalResults ve itemsPerPage ile ilgili daha fazla açıklama için Sayfalama bölümüne bakın.
startDate string Veri sorgusunun start-date parametresiyle belirtilen başlangıç tarihi.
endDate string Veri sorgusunun end-date parametresiyle belirtilen bitiş tarihi.
profileInfo object Verilerinin istendiği görünüm (profil) hakkında bilgi. Görünüm (Profil) verileri, Google Analytics Management API aracılığıyla kullanılabilir.
profileInfo.profileId string Görünüm (Profil) kimliği (ör. 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 UA-30481-1 gibi dahili kimliği.
profileInfo.profileName string Görünümün (profil) 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. Ö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ı, istekte metrics ve dimensions parametreleri aracılığıyla belirtilenlerle aynıdır. Başlık sayısı, boyut sayısı + metrik 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ı veri türü olarak yalnızca STRING içerir. Metrik sütunu başlıklarında INTEGER, PERCENT, TIME, CURRENCY, FLOAT vb. metrik değerleri için veri türleri bulunur. Olası tüm veri türleri için metadata API yanıtı bölümünü inceleyin.
totalsForAllResults object Metrik adları ve değerlerinden oluşan anahtar/değer çiftleri olarak, istenen metriklerin toplam değerleri. Metrik toplamlarının sırası, istekte belirtilen metrik sırası ile aynıdır.
dataTable object Google Grafikler ile kullanılabilen bir Veri Tablosu nesnesi.
dataTable.cols[] list Boyutlar için sütun açıklayıcılarının listesi ve ardından metrikler gelir. 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 kimlik (sütun dizinlerini kullanmaya alternatif olarak) Bu değeri ayarlamak için boyut veya metrik kimliği kullanılır.
dataTable.cols[].label string Sütun için bir etiket (bir görselleştirme tarafından gösterilebilir). 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 Veri Tablosu biçimindeki Analytics veri satırları. Her satır, boyutların hücre değerlerinin listesini ve ardından metrikleri içeren bir nesnedir. Boyut ve metriklerin sırası, istekte belirtilenle aynıdır. Her hücrede, N alandan oluşan bir liste vardır. Bu listede N, boyut sayısı + metrik sayısı anlamına gelir.

Hata Kodları

Bir istek 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!

Temel Raporlama API'sına sorgu göndermeyi 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ı verilerle ilgili istek yapmak ve yanıtı JSON biçiminde görmek için Google Data APIs 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 2 özellik, sorgunun örnekleme düzeyi hakkında bilgi sağlar: sampleSize ve sampleSpace. Bu 2 değer ile sorgu için kullanılan oturumların yüzdesini hesaplayabilirsiniz. Örneğin, sampleSize değeri 201,000,sampleSpace değeri 220,000 ise rapor temel olarak (201.000 / 220.000) x 100 = % 91,36 oturuma dayanı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, hatalardan kaçınmanıza 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 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 Boyutları 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 işlem, özellikle sonuçta elde edilen satır sayısı yüksekse çok zaman alabilir. Örneğin, şehir bazında anahtar kelime sorguları milyonlarca veri satırıyla eşleşebilir. Sorgunuzdaki boyutların sayısını sınırlandırıp 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 veya tarih içeren sonuçlarına göz atmak yerine, aynı anda 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 verilerle ilgili bir istek bile max-results değerinden daha fazla sonuç döndürebilir. Bu durumda sayfalamadan kaçınılamaz. Ancak sorgunuzla eşleşen satırların sayısı max-results değerinden büyükse tarih aralığının ayrılması, sonuçların alınması için gereken toplam süreyi azaltabilir. 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 parçalara bölmek için faydalı bir yol olabilir. totalResults alanı, kaç eşleşen satır olduğunu bildirir ve itemsPerPage, sonuçta döndürülebilecek maksimum satır sayısını verir. totalResults/itemsPerPage oranı yüksekse tek tek sorgular gereğinden uzun sürebilir. Görüntüleme amaçları 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 belirlemek uygun olabilir. Bununla birlikte, uygulamanızın büyük bir sonuç grubunu bütünüyle 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ırmasını etkinleştirmektir. Sıkıştırılmış sonuçların açılması için ek CPU süresi gerekse de, ağ maliyetlerinin dengelenmesi genellikle çok değerlidir. 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. Burada, gzip sıkıştırmasını etkinleştirmek için düzgün şekilde oluşturulmuş bir HTTP üst bilgisi örneği verilmiştir:

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