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:
|
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
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
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.
start-date
, 2005-01-01
.
Başlangıç tarihi için üst sınır kısıtlaması yoktur.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
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.
end-date
, 2005-01-01
. end-date
için üst sınır kısıtlaması yoktur. 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
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
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
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
veyametrics
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
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.
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 |
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
\,
- noktalı 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.
- Maksimum 128 karakter uzunluğu: 128 karakterden uzun normal ifadeler, sunucudan bir
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
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
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.
DEFAULT
örnekleme düzeyi kullanılır.boş-satırları-dahil et
include-empty-rows=true
start-index
start-index=10
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
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.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
json
— Yanıtta, JSON nesnesi içeren varsayılanrows
özelliğini verir.dataTable
— Yanıtta Veri Tablosu nesnesi içeren birdataTable
özelliği çıkarır. BuData Table
nesnesi doğrudan Google Grafikler görselleştirmeleri ile kullanılabilir.
fields
fields=rows,columnHeaders(name,dataType)
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çina/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ızcaname
vedataType
alanlarını döndürür. Ayrıcafields=columnHeader(name)
,fields=columnHeader/name
ile eşdeğer olan tek bir alt alan da belirtebilirsiniz.
prettyPrint
prettyPrint=false
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
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.
{
"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. |
selfLink |
string |
Bu veri sorgusu için bu sonuç sayfasının bağlantısı. |
previousLink |
string |
Bu veri sorgusu için önceki sonuç sayfasının bağlantısı. |
nextLink |
string |
Bu veri sorgusu için sonraki sonuç sayfasının bağlantısı. |
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. |
{
"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. |
selfLink |
string |
Bu veri sorgusu için bu sonuç sayfasının bağlantısı. |
previousLink |
string |
Bu veri sorgusu için önceki sonuç sayfasının bağlantısı. |
nextLink |
string |
Bu veri sorgusu için sonraki sonuç sayfasının bağlantısı. |
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)