Dokumen ini memberikan referensi lengkap baik untuk kueri maupun respons untuk Core Reporting API versi 3.0.
Pengantar
Anda mengajukan kueri Core Reporting API untuk data laporan Google Analytics. Setiap kueri memerlukan ID tampilan (profil), tanggal mulai dan akhir, serta setidaknya satu metrik. Anda juga dapat memberikan parameter kueri tambahan seperti dimensi, filter, dan segmen untuk menyaring kueri. Lihat Panduan Ringkasan untuk memahami cara kerja semua konsep ini.
Permintaan
API ini menyediakan satu metode untuk meminta data:
analytics.data.ga.get()
Metode ini diekspos di berbagai library klien dan memiliki antarmuka khusus bahasa untuk menetapkan parameter kueri.
API juga dapat dikueri sebagai endpoint REST-ful:
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
Setiap parameter kueri URL menentukan parameter kueri API yang harus dienkode ke URL.
Ringkasan Parameter Kueri
Tabel berikut meringkas semua parameter kueri yang diterima oleh Core Reporting API. Klik setiap nama parameter untuk melihat deskripsi mendetail.
Nama | Nilai | Wajib | Ringkasan |
---|---|---|---|
ids |
string |
ya | ID tabel unik dalam formulir ga:XXXX, dengan XXXX adalah ID tampilan (profil) Analytics yang datanya akan diambil oleh kueri. |
start-date |
string |
ya |
Tanggal mulai untuk mengambil data Analytics. Permintaan dapat menentukan tanggal mulai yang diformat sebagai YYYY-MM-DD , atau sebagai tanggal relatif (misalnya, today , yesterday , atau NdaysAgo dengan N adalah bilangan bulat positif).
|
end-date |
string |
ya |
Tanggal akhir pengambilan data Analytics. Permintaan dapat menentukan tanggal akhir dalam format YYYY-MM-DD , atau sebagai tanggal relatif (mis.,
today , yesterday , atau NdaysAgo
dengan N adalah bilangan bulat positif).
|
metrics |
string |
ya |
Daftar metrik yang dipisahkan koma, seperti ga:sessions,ga:bounces .
|
dimensions |
string |
no |
Daftar dimensi yang dipisahkan koma untuk data Analytics Anda, seperti
ga:browser,ga:city .
|
sort |
string |
no | Daftar dimensi dan metrik yang dipisahkan koma yang menunjukkan tata urutan dan arah pengurutan untuk data yang ditampilkan. |
filters |
string |
no | Filter dimensi atau metrik yang membatasi data yang ditampilkan untuk permintaan Anda. |
segment |
string |
no | Membuat segmentasi data yang ditampilkan untuk permintaan Anda. |
samplingLevel |
string |
no | Tingkat sampling yang diinginkan. Nilai yang Diizinkan:
|
include-empty-rows |
boolean |
no | Defaultnya adalah true; jika ditetapkan ke false, baris yang semua nilai metriknya bernilai nol akan dihilangkan dari respons. |
start-index |
integer |
no |
Baris pertama data yang akan diambil, mulai dari 1. Gunakan parameter ini sebagai mekanisme penomoran halaman
bersama dengan parameter max-results .
|
max-results |
integer |
no | Jumlah baris maksimum yang akan disertakan dalam respons. |
output |
string |
no |
Jenis output yang diinginkan untuk data Analytics yang ditampilkan dalam respons.
Nilai yang dapat diterima adalah json dan
dataTable . Default: json .
|
fields |
string |
no | Pemilih yang menentukan subset kolom untuk disertakan dalam respons. |
prettyPrint |
string |
no |
Menampilkan respons dengan indentasi dan baris baru. false default.
|
userIp |
string |
no | Menentukan alamat IP pengguna akhir yang panggilan API-nya dibuat. Digunakan untuk membatasi penggunaan per IP. |
quotaUser |
string |
no | Alternatif untuk userIp jika alamat IP pengguna tidak diketahui. |
access_token |
string |
no | Salah satu cara yang memungkinkan untuk memberikan token OAuth 2.0. |
callback |
string |
no | Nama fungsi callback JavaScript yang menangani respons. Digunakan dalam permintaan JSON-P JavaScript. |
key |
string |
no | Digunakan untuk otorisasi OAuth 1.0a guna menentukan aplikasi Anda agar mendapatkan kuota. Contoh:
key=AldefliuhSFADSfasdfasdfASdf . |
Detail Parameter Kueri
ids
ids=ga:12345
ga:
namespace dengan ID tampilan (profil) Analytics. Anda dapat mengambil ID tampilan (profil) menggunakan
metode analytics.management.profiles.list
, yang menyediakan id
dalam resource Tampilan (Profil)
di
Google
Analytics Management API.
tanggal-mulai
start-date=2009-04-20
start-date
dan end-date
dalam permintaan, server akan menampilkan error. Nilai tanggal dapat untuk tanggal tertentu dengan menggunakan pola YYYY-MM-DD
atau relatif dengan menggunakan pola today
, yesterday
, atau NdaysAgo
.
Nilai harus cocok dengan
[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
.
start-date
valid paling awal adalah 2005-01-01
.
Tidak ada batasan atas untuk suatu tanggal mulai.Contoh rentang tanggal selama 7 hari terakhir (mulai kemarin) menggunakan tanggal relatif:
&start-date=7daysAgo &end-date=yesterday
tanggal-akhir
end-date=2009-05-20
start-date
dan end-date
dalam permintaan, server akan menampilkan error. Nilai tanggal dapat untuk tanggal tertentu dengan menggunakan pola YYYY-MM-DD
atau relatif dengan menggunakan pola today
, yesterday
, atau NdaysAgo
.
Nilai harus cocok dengan
[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
.
end-date
valid paling awal adalah
2005-01-01
. Tidak ada batasan atas untuk
end-date
. Contoh rentang tanggal selama 10 hari terakhir (mulai hari ini) menggunakan tanggal relatif:
&start-date=9daysAgo &end-date=today
dimensi
dimensions=ga:browser,ga:city
dimensions
mengelompokkan metrik berdasarkan kriteria umum; misalnya, menurut ga:browser
atau ga:city
.
Meskipun Anda dapat menanyakan
jumlah total kunjungan halaman ke situs, mungkin akan
lebih menarik untuk menanyakan jumlah kunjungan halaman yang dikelompokkan berdasarkan
browser. Dalam hal ini, Anda akan melihat jumlah kunjungan halaman dari
Firefox, Internet Explorer, Chrome, dan sebagainya.
Saat menggunakan dimensions
dalam permintaan data, perhatikan batasan berikut:
- Anda dapat memberikan maksimum 7 dimensi dalam kueri apa pun.
- Anda tidak dapat mengirim kueri yang hanya terdiri dari dimensi: Anda harus menggabungkan dimensi yang diminta dengan setidaknya satu metrik.
- Hanya dimensi tertentu yang dapat dikueri dalam kueri yang sama. Gunakan alat kombinasi yang valid dalam Referensi Dimensi dan Metrik untuk melihat dimensi mana yang dapat digunakan bersama.
metrics
metrics=ga:sessions,ga:bounces
dimensions
, metrik yang ditampilkan akan memberikan nilai gabungan untuk rentang tanggal yang diminta, seperti kunjungan halaman secara keseluruhan atau total pantulan. Namun, saat dimensi diminta, nilai akan disegmentasikan menurut nilai dimensi. Misalnya, ga:pageviews
yang diminta dengan
ga:country
akan menampilkan total kunjungan halaman per negara.
Saat meminta metrik, perlu diingat:
- Setiap permintaan harus menyediakan setidaknya satu metrik; permintaan tidak boleh hanya terdiri dari dimensi.
- Anda dapat menyediakan maksimum 10 metrik untuk kueri apa pun.
- Sebagian besar kombinasi metrik dari beberapa kategori dapat digunakan bersama, asalkan tidak ada dimensi yang ditentukan.
- Metrik dapat digunakan bersama dimensi atau metrik lainnya, tetapi hanya jika kombinasi yang valid diterapkan untuk metrik tersebut. Lihat Referensi Dimensi dan Metrik untuk mengetahui detailnya.
sort
sort=ga:country,ga:browser
Daftar metrik dan dimensi yang menunjukkan tata urutan dan arah pengurutan untuk data yang ditampilkan.
- Pengurutan urutan ditentukan oleh urutan kiri ke kanan metrik dan dimensi yang tercantum.
- Mengurutkan direction secara default adalah menaik dan dapat diubah menjadi menurun menggunakan awalan tanda minus (
-
) pada kolom yang diminta.
Mengurutkan hasil kueri memungkinkan Anda mengajukan berbagai
pertanyaan tentang data. Misalnya, untuk menjawab pertanyaan
"Apa negara teratas saya, dan browser mana yang paling sering mereka gunakan?"
Anda dapat membuat kueri dengan parameter berikut. Pengurutan ini diurutkan
pertama menurut
ga:country
, lalu menurut ga:browser
, keduanya dalam
urutan menaik:
sort=ga:country,ga:browser
Untuk menjawab pertanyaan terkait "Apa browser teratas saya dan negara mana yang paling sering menggunakannya?", Anda dapat membuat kueri dengan parameter berikut. Pengurutan ini diurutkan pertama berdasarkan
ga:browser
lalu
ga:country
, keduanya dalam urutan menaik:
sort=ga:browser,ga:country
Saat menggunakan parameter sort
, perhatikan hal berikut:
- Hanya urutkan berdasarkan nilai dimensi atau metrik yang telah Anda gunakan dalam parameter
dimensions
ataumetrics
. Jika permintaan Anda mengurutkan pada kolom yang tidak ditunjukkan dalam parameter dimensi atau metrik, Anda akan menerima error. - Secara default, string diurutkan dalam urutan abjad menaik dalam lokal en-US.
- Angka diurutkan dalam urutan numerik menaik secara default.
- Tanggal diurutkan dalam urutan menaik berdasarkan tanggal secara {i>default<i}.
filter
filters=ga:medium%3D%3Dreferral
Parameter string kueri filters
membatasi data yang ditampilkan dari permintaan Anda. Untuk menggunakan parameter filters
, berikan dimensi atau metrik yang akan difilter, diikuti
dengan ekspresi filter. Misalnya, kueri berikut
meminta ga:pageviews
dan ga:browser
untuk
tampilan (profil) 12134
, dengan dimensi
ga:browser
dimulai dengan string Firefox
:
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
Kueri yang difilter membatasi baris yang menyertakan (atau tidak) disertakan dalam hasil. Setiap baris dalam hasil diuji terhadap filter: jika filter cocok, baris akan dipertahankan, dan jika tidak cocok, baris akan dihapus.
- Encoding URL: Library klien Google API secara otomatis mengenkode operator filter.
- Pemfilteran dimensi: Pemfilteran terjadi sebelum dimensi apa pun digabungkan, sehingga metrik yang ditampilkan hanya mewakili total untuk dimensi yang relevan. Pada contoh di atas, jumlah kunjungan halaman hanya akan menunjukkan kunjungan halaman jika Firefox adalah browser.
- Pemfilteran metrik: Pemfilteran metrik terjadi setelah metrik digabungkan.
- Kombinasi yang valid: Anda dapat memfilter dimensi atau metrik yang bukan bagian dari kueri Anda, asalkan semua dimensi/metrik dalam permintaan dan filternya merupakan kombinasi yang valid. Misalnya, Anda mungkin ingin membuat kueri untuk daftar kunjungan halaman yang bertanggal, dengan memfilter di browser tertentu. Lihat Referensi Dimensi dan Metrik untuk informasi selengkapnya.
Filter Sintaksis
Satu filter menggunakan bentuk:
ga:name operator expression
Dalam sintaksis ini:
- name — nama dimensi atau metrik yang akan difilter. Misalnya:
ga:pageviews
memfilter metrik kunjungan halaman. - operator — menentukan jenis pencocokan filter yang akan digunakan. Operator bersifat khusus untuk dimensi atau metrik.
- expression — menyatakan nilai yang akan disertakan dalam atau dikecualikan dari hasil. Ekspresi menggunakan sintaksis ekspresi reguler.
Operator Filter
Ada enam operator filter untuk dimensi dan enam operator filter untuk metrik. Operator harus dienkode ke URL agar dapat disertakan dalam string kueri URL.
Tips: Gunakan Penjelajah Kueri Feed Data untuk mendesain filter yang memerlukan encoding URL, karena Penjelajah Kueri secara otomatis mengenkode URL yang berisi string dan spasi.
Operator | Deskripsi | Formulir yang Dienkode URL | Contoh |
---|---|---|---|
== |
Sama dengan | %3D%3D |
Menampilkan hasil dengan waktu di halaman tepat sepuluh detik:filters=ga:timeOnPage%3D%3D10 |
!= |
Tidak sama dengan | !%3D |
Menampilkan hasil dengan waktu di halaman bukan sepuluh detik:filters=ga:timeOnPage!%3D10 |
> |
Lebih dari | %3E |
Menampilkan hasil dengan waktu di halaman yang benar-benar lebih besar dari sepuluh detik:filters=ga:timeOnPage%3E10 |
< |
Kurang dari | %3C |
Menampilkan hasil dengan waktu di halaman yang benar-benar kurang dari sepuluh detik:filters=ga:timeOnPage%3C10 |
>= |
Lebih dari atau sama dengan | %3E%3D |
Menampilkan hasil dengan waktu di halaman sepuluh detik atau lebih:filters=ga:timeOnPage%3E%3D10 |
<= |
Kurang dari atau sama dengan | %3C%3D |
Menampilkan hasil dengan waktu di halaman sepuluh detik atau kurang:filters=ga:timeOnPage%3C%3D10 |
Operator | Deskripsi | Formulir yang Dienkode URL | Contoh |
---|---|---|---|
== |
Pencocokan persis | %3D%3D |
Metrik agregat dengan kota Irvine:filters=ga:city%3D%3DIrvine |
!= |
Tidak cocok | !%3D |
Metrik agregat jika kota bukan Irvine:filters=ga:city!%3DIrvine |
=@ |
Berisi substring | %3D@ |
Metrik gabungan yang kotanya berisi York:filters=ga:city%3D@York |
!@ |
Tidak berisi substring | !@ |
Metrik agregat jika kota tidak berisi York:filters=ga:city!@York |
=~ |
Berisi kecocokan untuk ekspresi reguler | %3D~ |
Metrik agregat dengan kota yang diawali dengan Baru:filters=ga:city%3D~%5ENew.* (%5E adalah URL yang dienkode dari karakter ^ yang menambatkan pola ke awal string.) |
!~ |
Tidak cocok dengan regular expression | !~ |
Metrik agregat yang kotanya tidak dimulai dengan Baru: filters=ga:city!~%5ENew.* |
Ekspresi Filter
Ada beberapa aturan penting untuk ekspresi filter:
- Karakter yang dicadangkan URL — Karakter seperti
&
harus dienkode URL dengan cara biasa. - Karakter yang dicadangkan — Titik koma dan koma harus di-escape garis miring terbalik saat muncul dalam ekspresi:
- titik koma
\;
- koma
\,
- titik koma
- Ekspresi Reguler — Anda juga dapat menggunakan ekspresi reguler dalam ekspresi filter
menggunakan operator
=~
dan!~
. Sintaksisnya mirip dengan ekspresi reguler Perl dan memiliki aturan tambahan berikut:- Panjang maksimum 128 karakter — Ekspresi reguler yang lebih dari 128 karakter menghasilkan kode status
400 Bad Request
yang ditampilkan dari server. - Peka huruf besar/kecil — Pencocokan ekspresi reguler tidak peka huruf besar/kecil.
- Panjang maksimum 128 karakter — Ekspresi reguler yang lebih dari 128 karakter menghasilkan kode status
Menggabungkan Filter
Filter dapat digabungkan menggunakan logika boolean OR
dan AND
. Hal ini memungkinkan Anda memperluas batas ekspresi filter sebanyak 128 karakter.
ATAU
Operator OR
ditentukan menggunakan koma (,
).
Operator ini lebih diutamakan daripada operator AND
dan TIDAK dapat digunakan
untuk menggabungkan dimensi dan metrik dalam ekspresi yang sama.
Contoh: (masing-masing harus dienkode ke URL)
Negara adalah (Amerika Serikat ATAU Kanada):
ga:country==United%20States,ga:country==Canada
Pengguna Firefox yang menggunakan sistem operasi (Windows ATAU Macintosh):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh
DAN
Operator AND
ditentukan menggunakan titik koma (;
).
Operator ini didahului oleh operator OR
dan CANGGIH digunakan untuk menggabungkan
dimensi dan metrik dalam ekspresi yang sama.
Contoh: (masing-masing harus dienkode ke URL)
Negara adalah Amerika Serikat DAN browser adalah Firefox:
ga:country==United%20States;ga:browser==Firefox
Negara adalah Amerika Serikat DAN bahasa tidak diawali dengan 'en':
ga:country==United%20States;ga:language!~^en.*
Sistem operasi adalah (Windows ATAU Macintosh) DAN browser adalah (Firefox ATAU Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome
Negara adalah Amerika Serikat DAN sesi lebih besar dari 5:
ga:country==United%20States;ga:sessions>5
segmen
segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
Untuk detail selengkapnya tentang cara meminta segmen di Core Reporting API, lihat Panduan Developer Segmen.
Untuk ringkasan konseptual tentang segmen, lihat Referensi Fitur Segmen dan Segmen di Pusat Bantuan.
Dimensi dan Metrik yang diizinkan dalam segmen.
Tidak semua dimensi dan metrik dapat digunakan dalam segmen. Untuk meninjau
dimensi dan metrik yang diizinkan dalam segmen, kunjungi
Penjelajah Dimensi dan Metrik.
samplingLevel
samplingLevel=DEFAULT
DEFAULT
— Menampilkan respons dengan ukuran sampel yang menyeimbangkan kecepatan dan akurasi.FASTER
— Menampilkan respons cepat dengan ukuran sampel yang lebih kecil.HIGHER_PRECISION
— Menampilkan respons yang lebih akurat menggunakan ukuran sampel yang besar, tetapi hal ini dapat menyebabkan respons menjadi lebih lambat.
DEFAULT
akan
digunakan.sertakan-baris-kosong
include-empty-rows=true
start-index
start-index=10
1
. (Indeks hasil berbasis 1. Artinya, baris pertama adalah baris 1
, bukan baris 0
.) Gunakan parameter ini sebagai mekanisme penomoran halaman bersama dengan parameter max-results
untuk situasi saat totalResults
melebihi 10.000 dan Anda ingin mengambil baris yang diindeks pada 10.001 dan seterusnya.max-results
max-results=100
start-index
untuk mengambil subset elemen, atau menggunakannya sendiri untuk membatasi jumlah elemen yang ditampilkan, dimulai dari yang pertama.
Jika max-results
tidak diberikan, kueri akan menampilkan jumlah maksimum default 1.000 baris.ga:country
. Jadi, saat melakukan segmentasi hanya
berdasarkan negara, Anda tidak bisa mendapatkan lebih dari 300 baris, meskipun
menetapkan max-results
ke nilai yang lebih tinggi.hasil
output=dataTable
json
— Menghasilkan propertirows
default dalam respons, yang berisi objek JSON.dataTable
— Menghasilkan propertidataTable
dalam respons, yang berisi objek Tabel Data. ObjekData Table
ini dapat digunakan langsung dengan visualisasi Google Chart.
fields
fields=rows,columnHeaders(name,dataType)
Menentukan kolom yang akan ditampilkan dalam respons sebagian. Jika Anda hanya menggunakan subset kolom dalam respons API, Anda dapat menggunakan parameter fields
untuk menentukan kolom yang akan disertakan.
Format nilai parameter permintaan kolom umumnya didasarkan pada sintaksis XPath. Sintaksis yang didukung dirangkum di bawah ini.
- Gunakan daftar yang dipisahkan koma untuk memilih beberapa kolom.
- Gunakan
a/b
untuk memilih kolom b yang bertingkat dalam kolom a; gunakana/b/c
untuk memilih kolom c yang bertingkat di dalam b. - Gunakan sub-selektor untuk meminta kumpulan sub-kolom spesifik dari array atau objek dengan menempatkan ekspresi dalam tanda kurung
"( )"
.
Misalnya:fields=columnHeaders(name,dataType)
hanya menampilkan kolomname
dandataType
dalam arraycolumnHeaders
. Anda juga dapat menentukan satu subkolom, denganfields=columnHeader(name)
setara denganfields=columnHeader/name
.
prettyPrint
prettyPrint=false
Menampilkan respons dalam format yang dapat dibaca manusia jika true
.
Nilai default: false
.
quotaUser
quotaUser=4kh4r2h4
Memungkinkan Anda menerapkan kuota per pengguna dari aplikasi sisi server meskipun alamat IP pengguna tidak diketahui. Hal ini dapat terjadi, misalnya, pada aplikasi yang menjalankan cron job di App Engine atas nama pengguna. Anda dapat memilih string arbitrer apa pun yang secara unik mengidentifikasi pengguna, tetapi dibatasi hingga 40 karakter.
Tindakan ini akan menggantikan userIp
jika keduanya disediakan.
Respons
Jika berhasil, permintaan ini akan menampilkan isi respons dengan struktur JSON yang ditentukan di bawah ini. Jika parameter output ditetapkan ke dataTable
, permintaan akan menampilkan isi respons dengan struktur JSON (Tabel Data) yang ditentukan di bawah ini.
Catatan: istilah "results" mengacu pada seluruh kumpulan baris yang cocok dengan kueri, sedangkan "respons" mengacu pada kumpulan baris yang ditampilkan pada halaman hasil saat ini. Parameter dapat berbeda jika jumlah total hasil lebih besar dari ukuran halaman untuk respons saat ini, seperti yang dijelaskan dalam itemsPerPage.
{
"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,
...
}
]
}
Kolom Respons
Properti struktur isi respons didefinisikan sebagai berikut:
Nama Properti | Nilai | Deskripsi |
---|---|---|
kind |
string |
Jenis resource. Nilainya adalah "analytics#gaData". |
id |
string |
ID untuk respons data ini. |
query |
object |
Objek ini berisi semua nilai yang diteruskan sebagai parameter ke kueri. Arti setiap kolom dijelaskan dalam deskripsi parameter kueri terkaitnya. |
query.start-date |
string |
Tanggal mulai. |
query.end-date |
string |
Tanggal akhir. |
query.ids |
string |
ID tabel unik. |
query.dimensions[] |
list |
Daftar dimensi analisis. |
query.metrics[] |
list |
Daftar metrik analisis. |
query.samplingLevel |
string |
Requested sampling level. |
query.include-empty-rows |
boolean |
Defaultnya adalah true; jika ditetapkan ke false, baris dengan semua nilai metrik nol akan dihilangkan dari respons. |
query.sort[] |
list |
Daftar metrik atau dimensi yang digunakan untuk mengurutkan data. |
query.filters |
string |
Daftar filter metrik atau dimensi yang dipisahkan koma. |
query.segment |
string |
Segmen Analytics. |
query.start-index |
integer |
Mulai indeks. |
query.max-results |
integer |
Hasil maksimum per halaman. |
startIndex |
integer |
Indeks awal baris yang ditentukan oleh parameter kueri start-index . Nilai defaultnya adalah 1. |
itemsPerPage |
integer |
Jumlah maksimum baris yang dapat ditampung respons,
berapa pun jumlah sebenarnya baris yang ditampilkan. Jika parameter kueri max-results ditentukan, nilai itemsPerPage adalah yang lebih kecil dari max-results atau 10.000. Nilai default
itemsPerPage adalah 1.000.
|
totalResults |
integer |
Jumlah total baris dalam hasil kueri, berapa pun jumlah baris yang ditampilkan dalam respons. Untuk kueri yang menghasilkan baris dalam jumlah besar, totalResults bisa lebih besar dari itemsPerPage .
Lihat Paging untuk penjelasan lebih lanjut tentang totalResults dan itemsPerPage untuk kueri besar.
|
startDate |
string |
Tanggal mulai kueri data, seperti yang ditentukan oleh parameter start-date . |
endDate |
string |
Tanggal akhir untuk kueri data, seperti yang ditentukan oleh parameter end-date . |
selfLink |
string |
Tautkan ke halaman hasil untuk kueri data ini. |
previousLink |
string |
Link ke halaman hasil sebelumnya untuk kueri data ini. |
nextLink |
string |
Tautan ke halaman hasil berikutnya untuk kueri data ini. |
profileInfo |
object |
Informasi tentang tampilan (profil) yang datanya diminta. Data Tampilan (Profil) tersedia melalui Google Analytics Management API. |
profileInfo.profileId |
string |
ID Tampilan (Profil), seperti 1174 . |
profileInfo.accountId |
string |
ID Akun yang mencakup tampilan (profil) ini, seperti
30481 . |
profileInfo.webPropertyId |
string |
ID Properti Web tempat tampilan (profil) ini berada, seperti UA-30481-1 . |
profileInfo.internalWebPropertyId |
string |
ID internal untuk properti web tempat tampilan (profil) ini berada, seperti UA-30481-1 . |
profileInfo.profileName |
string |
Nama tampilan (profil). |
profileInfo.tableId |
string |
ID tabel untuk tampilan (profil), yang terdiri dari "ga:" diikuti dengan ID tampilan (profil). |
containsSampledData |
boolean |
Benar jika respons berisi data diambil sampel. |
sampleSize |
string |
Jumlah sampel yang digunakan untuk menghitung data diambil sampel. |
sampleSpace |
string |
Total ukuran ruang pengambilan sampel. Hal ini menunjukkan total ukuran ruang sampel yang tersedia tempat sampel dipilih. |
columnHeaders[] |
list |
Header kolom yang mencantumkan nama dimensi, diikuti dengan nama metrik. Urutan dimensi dan metrik sama dengan urutan yang ditentukan dalam permintaan melalui parameter metrics dan dimensions . Jumlah header adalah jumlah dimensi + jumlah metrik. |
columnHeaders[].name |
string |
Nama dimensi atau metrik. |
columnHeaders[].columnType |
string |
Jenis kolom. "DIMENSION" atau "METRIK". |
columnHeaders[].dataType |
string |
Jenis data. Header kolom dimensi hanya memiliki
STRING sebagai jenis data. Header kolom metrik memiliki jenis data untuk nilai metrik seperti INTEGER , PERCENT , TIME , CURRENCY , FLOAT , dll. Lihat respons API metadata untuk semua jenis data yang memungkinkan.
|
totalsForAllResults |
object |
Nilai total untuk metrik yang diminta sebagai key-value pair dari nama dan nilai metrik. Urutan total metrik sama dengan urutan metrik yang ditentukan dalam permintaan. |
rows[] |
list |
Baris data Analytics, dengan setiap baris berisi daftar nilai dimensi diikuti dengan nilai metrik. Urutan dimensi dan metrik sama dengan yang ditentukan dalam permintaan. Setiap baris memiliki daftar N kolom, dengan N = jumlah dimensi + jumlah metrik. |
{
"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,
...
}
]
}
Kolom Respons
Properti struktur isi respons didefinisikan sebagai berikut:
Nama Properti | Nilai | Deskripsi |
---|---|---|
kind |
string |
Jenis resource. Nilainya adalah "analytics#gaData". |
id |
string |
ID untuk respons data ini. |
query |
object |
Objek ini berisi semua nilai yang diteruskan sebagai parameter ke kueri. Arti setiap kolom dijelaskan dalam deskripsi parameter kueri terkaitnya. |
query.start-date |
string |
Tanggal mulai. |
query.end-date |
string |
Tanggal akhir. |
query.ids |
string |
ID tabel unik. |
query.dimensions[] |
list |
Daftar dimensi analisis. |
query.metrics[] |
list |
Daftar metrik analisis. |
query.samplingLevel |
string |
Requested sampling level. |
query.include-empty-rows |
boolean |
Defaultnya adalah true; jika ditetapkan ke false, baris dengan semua nilai metrik nol akan dihilangkan dari respons. |
query.sort[] |
list |
Daftar metrik atau dimensi yang digunakan untuk mengurutkan data. |
query.filters |
string |
Daftar filter metrik atau dimensi yang dipisahkan koma. |
query.segment |
string |
Segmen Analytics. |
query.start-index |
integer |
Mulai indeks. |
query.max-results |
integer |
Hasil maksimum per halaman. |
startIndex |
integer |
Indeks awal baris yang ditentukan oleh parameter kueri start-index . Nilai defaultnya adalah 1. |
itemsPerPage |
integer |
Jumlah maksimum baris yang dapat ditampung respons,
berapa pun jumlah sebenarnya baris yang ditampilkan. Jika parameter kueri max-results ditentukan, nilai itemsPerPage adalah yang lebih kecil dari max-results atau 10.000. Nilai default
itemsPerPage adalah 1.000.
|
totalResults |
integer |
Jumlah total baris dalam hasil kueri, berapa pun jumlah baris yang ditampilkan dalam respons. Untuk kueri yang menghasilkan baris dalam jumlah besar, totalResults bisa lebih besar dari itemsPerPage .
Lihat Paging untuk penjelasan lebih lanjut tentang totalResults dan itemsPerPage untuk kueri besar.
|
startDate |
string |
Tanggal mulai kueri data, seperti yang ditentukan oleh parameter start-date . |
endDate |
string |
Tanggal akhir untuk kueri data, seperti yang ditentukan oleh parameter end-date . |
selfLink |
string |
Tautkan ke halaman hasil untuk kueri data ini. |
previousLink |
string |
Link ke halaman hasil sebelumnya untuk kueri data ini. |
nextLink |
string |
Tautan ke halaman hasil berikutnya untuk kueri data ini. |
profileInfo |
object |
Informasi tentang tampilan (profil) yang datanya diminta. Data Tampilan (Profil) tersedia melalui Google Analytics Management API. |
profileInfo.profileId |
string |
ID Tampilan (Profil), seperti 1174 . |
profileInfo.accountId |
string |
ID Akun yang mencakup tampilan (profil) ini, seperti
30481 . |
profileInfo.webPropertyId |
string |
ID Properti Web tempat tampilan (profil) ini berada, seperti UA-30481-1 . |
profileInfo.internalWebPropertyId |
string |
ID internal untuk properti web tempat tampilan (profil) ini berada, seperti UA-30481-1 . |
profileInfo.profileName |
string |
Nama tampilan (profil). |
profileInfo.tableId |
string |
ID tabel untuk tampilan (profil), yang terdiri dari "ga:" diikuti dengan ID tampilan (profil). |
containsSampledData |
boolean |
Benar jika respons berisi data diambil sampel. |
sampleSize |
string |
Jumlah sampel yang digunakan untuk menghitung data diambil sampel. |
sampleSpace |
string |
Total ukuran ruang pengambilan sampel. Hal ini menunjukkan total ukuran ruang sampel yang tersedia tempat sampel dipilih. |
columnHeaders[] |
list |
Header kolom yang mencantumkan nama dimensi, diikuti dengan nama metrik. Urutan dimensi dan metrik sama dengan urutan yang ditentukan dalam permintaan melalui parameter metrics dan dimensions . Jumlah header adalah jumlah dimensi + jumlah metrik. |
columnHeaders[].name |
string |
Nama dimensi atau metrik. |
columnHeaders[].columnType |
string |
Jenis kolom. "DIMENSION" atau "METRIK". |
columnHeaders[].dataType |
string |
Jenis data. Header kolom dimensi hanya memiliki
STRING sebagai jenis data. Header kolom metrik memiliki jenis data untuk nilai metrik seperti INTEGER , PERCENT , TIME , CURRENCY , FLOAT , dll. Lihat respons API metadata untuk semua jenis data yang memungkinkan.
|
totalsForAllResults |
object |
Nilai total untuk metrik yang diminta sebagai key-value pair dari nama dan nilai metrik. Urutan total metrik sama dengan urutan metrik yang ditentukan dalam permintaan. |
dataTable |
object |
Objek Tabel Data yang dapat digunakan dengan Google Chart. |
dataTable.cols[] |
list |
Daftar deskripsi kolom untuk dimensi yang diikuti dengan metrik. Urutan
dimensi dan metrik sama dengan urutan yang ditentukan dalam
permintaan melalui parameter metrics dan
dimensions . Jumlah kolom adalah jumlah dimensi + jumlah metrik. |
dataTable.cols[].id |
string |
ID, yang dapat digunakan untuk merujuk ke kolom tertentu (sebagai alternatif penggunaan indeks kolom). ID dimensi atau metrik digunakan untuk menetapkan nilai ini. |
dataTable.cols[].label |
string |
Label untuk kolom (yang mungkin ditampilkan melalui visualisasi). ID dimensi atau metrik digunakan untuk menetapkan nilai ini. |
dataTable.cols[].type |
string |
Jenis data untuk kolom ini. |
dataTable.rows[] |
list |
Baris data Analytics dalam format Tabel Data, di mana setiap baris merupakan objek yang berisi daftar nilai sel untuk dimensi yang diikuti dengan metrik. Urutan dimensi dan metrik sama seperti yang ditentukan dalam permintaan. Setiap sel memiliki daftar kolom N, dengan N = jumlah dimensi + jumlah metrik. |
Kode Error
Core Reporting API menampilkan kode status HTTP 200
jika permintaan berhasil. Jika terjadi error saat memproses kueri, API akan menampilkan kode dan deskripsi error.
Setiap aplikasi yang menggunakan analytics API harus menerapkan logika penanganan error yang tepat. Untuk mengetahui detail tentang kode error dan cara menanganinya, baca
Panduan referensi Respons Error.
Cobalah!
Anda dapat mencoba kueri ke Core Reporting API.
-
Untuk melihat kombinasi metrik dan dimensi yang valid dalam kueri, masukkan contoh nilai untuk parameter di Query Explorer. Hasil kueri contoh ditampilkan sebagai tabel dengan nilai untuk semua metrik dan dimensi yang ditentukan.
-
Untuk membuat permintaan pada data live dan melihat respons dalam format JSON, coba metode
analytics.data.ga.get
di Google Data APIs Explorer.
Pengambilan Sampel
Google Analytics menghitung kombinasi dimensi dan metrik tertentu dengan cepat. Untuk menampilkan data dalam waktu yang wajar, Google Analytics hanya dapat memproses sampel data.
Anda dapat menentukan tingkat pengambilan sampel yang akan digunakan untuk permintaan dengan menetapkan parameter samplingLevel.
Jika respons Core Reporting API berisi sampel data, kolom respons containsSampledData
akan menjadi true
.
Selain itu, 2 properti akan memberikan informasi tentang tingkat sampling untuk kueri: sampleSize
dan sampleSpace
.
Dengan 2 nilai ini, Anda dapat menghitung persentase sesi yang digunakan
untuk kueri. Misalnya, jika sampleSize
adalah 201,000
dan sampleSpace
adalah 220,000
,laporan didasarkan pada (201.000 / 220.000) * 100 = 91,36% sesi.
Lihat bagian Pengambilan sampel untuk mengetahui deskripsi umum tentang pengambilan sampel dan cara penggunaannya di Google Analytics.
Menangani Hasil Data yang Besar
Jika Anda memperkirakan kueri akan menampilkan kumpulan hasil besar, gunakan panduan di bawah ini untuk membantu Anda mengoptimalkan kueri API, menghindari error, dan meminimalkan kelebihan kuota. Perhatikan bahwa kami menetapkan dasar pengukuran performa dengan mengizinkan maksimum 7 dimensi dan 10 metrik dalam satu permintaan API. Meskipun beberapa kueri yang menentukan sejumlah besar metrik dan dimensi mungkin membutuhkan waktu pemrosesan yang lebih lama daripada yang lain, membatasi jumlah metrik yang diminta mungkin tidak cukup untuk meningkatkan performa kueri. Sebagai gantinya, Anda dapat menggunakan teknik berikut untuk mendapatkan hasil performa terbaik.
Mengurangi Dimensi per Kueri
API memungkinkan penentuan hingga 7 dimensi dalam satu permintaan. Sering kali, Google Analytics harus menghitung hasil kueri kompleks ini dengan cepat. Proses ini dapat sangat memakan waktu jika jumlah baris yang dihasilkan tinggi. Misalnya, kueri untuk kata kunci, berdasarkan kota per jam mungkin cocok dengan jutaan baris data. Anda dapat meningkatkan performa dengan mengurangi jumlah baris yang perlu diproses Google Analytics dengan membatasi jumlah dimensi dalam kueri Anda.
Memisahkan Kueri berdasarkan Rentang Tanggal
Pertimbangkan untuk membuat kueri terpisah selama satu minggu — atau bahkan
satu hari — pada satu waktu, bukan menelusuri hasil dengan kunci tanggal pada satu rentang
tanggal yang panjang. Tentu saja, untuk set data besar, bahkan permintaan untuk data satu hari mungkin menampilkan lebih dari max-results
, dalam hal ini paging tidak dapat dihindari. Namun,
bagaimanapun juga, jika jumlah baris yang cocok untuk kueri Anda lebih tinggi
dari max-results
, memisahkan rentang tanggal dapat
mengurangi total waktu untuk mengambil hasilnya. Pendekatan ini dapat meningkatkan performa kueri thread tunggal dan paralel.
Paging
Paging hasil dapat menjadi cara berguna untuk membagi kumpulan hasil yang besar
menjadi potongan-potongan yang mudah dikelola. Kolom totalResults
menunjukkan jumlah baris yang cocok, dan itemsPerPage
menunjukkan jumlah maksimum baris yang dapat ditampilkan dalam hasil.
Jika ada rasio totalResults
terhadap itemsPerPage
yang tinggi, setiap kueri mungkin akan memerlukan waktu lebih lama dari yang diperlukan. Jika hanya memerlukan baris dalam jumlah
terbatas, seperti untuk tujuan tampilan, akan lebih mudah bagi Anda untuk menetapkan
batas eksplisit ukuran respons melalui
parameter max-results
. Namun, jika aplikasi Anda
perlu memproses sekumpulan besar hasil secara keseluruhan, meminta baris maksimum yang diizinkan mungkin lebih efisien.
Menggunakan gzip
Cara yang mudah dan praktis untuk mengurangi bandwidth yang diperlukan untuk setiap permintaan adalah dengan mengaktifkan kompresi gzip. Meskipun hal ini memerlukan waktu CPU tambahan
untuk membuka hasil, namun kompromi dengan biaya jaringan biasanya
menjadikannya sangat bermanfaat. Untuk menerima respons yang dienkode dengan gzip, Anda harus melakukan dua hal: Menetapkan header Accept-Encoding
, dan mengubah agen pengguna Anda agar berisi string gzip
.
Berikut ini contoh header HTTP dengan format yang benar untuk mengaktifkan
kompresi gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)