Core Reporting API - Panduan Referensi

Dokumen ini menyediakan referensi lengkap untuk kueri dan respons untuk Core Reporting API versi 3.0.

Pengantar

Anda membuat kueri Core Reporting API untuk data laporan Google Analytics. Setiap kueri memerlukan ID tampilan (profil), tanggal mulai dan akhir, dan setidaknya satu metrik. Anda juga dapat menyediakan parameter kueri tambahan seperti dimensi, filter, dan segmen untuk menyaring kueri Anda. Lihat Panduan Ringkasan untuk memahami cara kerja semua konsep ini.

Permintaan

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

Kueri ini juga dapat dikueri sebagai endpoint yang dipenuhi REST:

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 merangkum semua parameter kueri yang diterima oleh Core Reporting API. Klik setiap nama parameter untuk deskripsi mendetail.

Name Nilai Wajib Ringkasan
ids string ya ID tabel unik dalam bentuk ga:XXXX, XXXX adalah ID tampilan (profil) Analytics yang kuerinya akan mengambil data.
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 (mis., today, yesterday, atau NdaysAgo dengan N berupa bilangan bulat positif).
end-date string ya Tanggal akhir untuk mengambil data Analytics. Permintaan dapat menentukan tanggal akhir yang diformat sebagai YYYY-MM-DD, atau sebagai tanggal relatif (misalnya, today, yesterday, atau NdaysAgo dengan N sebagai bilangan bulat positif).
metrics string ya Daftar metrik yang dipisahkan koma, seperti ga:sessions,ga:bounces.
dimensions string tidak Daftar dimensi yang dipisahkan koma untuk data Analytics Anda, seperti ga:browser,ga:city.
sort string tidak Daftar dimensi dan metrik yang dipisahkan koma yang menunjukkan tata urutan dan arah pengurutan untuk data yang ditampilkan.
filters string tidak Filter dimensi atau metrik yang membatasi data yang ditampilkan untuk permintaan Anda.
segment string tidak Mengelompokkan data yang ditampilkan untuk permintaan Anda.
samplingLevel string tidak Level pengambilan sampel yang diinginkan. Nilai yang Diizinkan:
  • 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 yang lebih lambat.
include-empty-rows boolean tidak Nilai defaultnya adalah true. Jika ditetapkan ke false, baris yang semua nilai metriknya nol akan dihilangkan dari respons.
start-index integer tidak Baris pertama data yang akan diambil, mulai dari 1. Gunakan parameter ini sebagai mekanisme penomoran halaman bersama dengan parameter max-results.
max-results integer tidak Jumlah maksimum baris untuk disertakan dalam respons.
output string tidak Jenis output yang diinginkan untuk data Analytics yang ditampilkan dalam respons. Nilai yang dapat diterima adalah json dan dataTable. Default: json.
fields string tidak Pemilih yang menentukan subkumpulan kolom untuk disertakan dalam respons.
prettyPrint string tidak Menampilkan respons dengan indentasi dan jeda baris. Default false.
userIp string tidak Menentukan alamat IP pengguna akhir yang akan dibuat panggilan API. Digunakan untuk membatasi penggunaan per IP.
quotaUser string tidak Alternatif untuk userIp jika alamat IP pengguna tidak diketahui.
access_token string tidak Salah satu cara yang memungkinkan untuk menyediakan token OAuth 2.0.
callback string tidak Nama fungsi callback JavaScript yang menangani respons. Digunakan dalam permintaan JSON-P JavaScript.
key string tidak Digunakan untuk otorisasi OAuth 1.0a guna menentukan aplikasi Anda untuk mendapatkan kuota. Contoh: key=AldefliuhSFADSfasdfasdfASdf.

Detail Parameter Kueri

id

ids=ga:12345
Wajib diisi.
ID unik yang digunakan untuk mengambil data Analytics. ID ini adalah gabungan dari namespace ga: dengan ID tampilan (profil) Analytics. Anda dapat mengambil ID tampilan (profil) dengan menggunakan metode analytics.management.profiles.list, yang menyediakan id di resource View (Profile) di Google Analytics Management API.

tanggal mulai

start-date=2009-04-20
Wajib diisi.
Semua permintaan data Analytics harus menentukan rentang tanggal. Jika Anda tidak menyertakan parameter start-date dan end-date dalam permintaan, server akan menampilkan error. Nilai tanggal dapat ditetapkan untuk tanggal tertentu menggunakan pola YYYY-MM-DD atau relatif 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 paling awal yang valid adalah 2005-01-01. Tidak ada pembatasan batas atas untuk tanggal mulai.
Tanggal relatif selalu bersifat relatif terhadap tanggal saat ini pada saat kueri dan didasarkan pada zona waktu tampilan (profil) yang ditentukan dalam kueri.

Contoh rentang tanggal untuk 7 hari terakhir (mulai kemarin) menggunakan tanggal relatif:

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

tanggal akhir

end-date=2009-05-20
Wajib diisi.
Semua permintaan data Analytics harus menentukan rentang tanggal. Jika Anda tidak menyertakan parameter start-date dan end-date dalam permintaan, server akan menampilkan error. Nilai tanggal dapat ditetapkan untuk tanggal tertentu menggunakan pola YYYY-MM-DD atau relatif 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 yang paling awal dan valid adalah 2005-01-01. Tidak ada batasan atas untuk end-date.
Tanggal relatif selalu bersifat relatif terhadap tanggal saat ini pada saat kueri dan didasarkan pada zona waktu tampilan (profil) yang ditentukan dalam kueri.

Contoh rentang tanggal untuk 10 hari terakhir (mulai hari ini) menggunakan tanggal relatif:

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

dimensi

dimensions=ga:browser,ga:city
Opsional.
Parameter dimensions mengelompokkan metrik menurut kriteria umum; misalnya, menurut ga:browser atau ga:city. Meskipun Anda dapat meminta jumlah total kunjungan halaman ke situs, mungkin lebih menarik untuk meminta jumlah kunjungan halaman yang dikelompokkan oleh browser. Dalam hal ini, Anda akan melihat jumlah kunjungan halaman dari Firefox, Internet Explorer, Chrome, dan seterusnya.

Saat menggunakan dimensions dalam permintaan data, perhatikan batasan berikut:

  • Anda dapat memberikan maksimal 7 dimensi dalam kueri apa pun.
  • Anda tidak dapat mengirim kueri yang hanya terdiri dari dimensi: Anda harus menggabungkan setiap dimensi yang diminta dengan setidaknya satu metrik.
  • Hanya dimensi tertentu yang dapat dikueri dalam kueri yang sama. Gunakan alat kombinasi yang valid di Referensi Dimensi dan Metrik untuk melihat dimensi mana yang dapat digunakan bersama-sama.

metrik

metrics=ga:sessions,ga:bounces
Wajib diisi.
Statistik gabungan untuk aktivitas pengguna ke situs Anda, seperti klik atau kunjungan halaman. Jika kueri tidak memiliki parameter dimensions, metrik yang ditampilkan memberikan nilai gabungan untuk rentang tanggal yang diminta, seperti keseluruhan kunjungan halaman atau total pantulan. Namun, jika 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, perhatikan:
  • Setiap permintaan harus menyediakan setidaknya satu metrik; permintaan tidak boleh hanya terdiri dari dimensi.
  • Anda dapat memasukkan maksimum 10 metrik untuk kueri apa pun.
  • Sebagian besar kombinasi metrik dari beberapa kategori dapat digunakan bersama-sama, asalkan tidak ada dimensi yang ditentukan.
  • Metrik dapat digunakan bersama dengan dimensi atau metrik lainnya, tetapi hanya jika kombinasi yang valid diterapkan untuk metrik tersebut. Baca Referensi Dimensi dan Metrik untuk mengetahui detailnya.

mengurutkan

sort=ga:country,ga:browser
Opsional.

Daftar metrik dan dimensi yang menunjukkan tata urutan dan arah pengurutan untuk data yang ditampilkan.

  • Urutan urutan ditentukan oleh urutan metrik dari dimensi kiri ke kanan yang tercantum.
  • Pengurutan arah secara default ditetapkan ke menaik dan dapat diubah menjadi menurun menggunakan awalan tanda minus (-) di kolom yang diminta.

Dengan mengurutkan hasil kueri, Anda dapat mengajukan pertanyaan yang berbeda tentang data. Misalnya, untuk menjawab pertanyaan "Apa saja negara teratas saya, dan browser mana yang paling sering mereka gunakan“. Anda dapat membuat kueri dengan parameter berikut. Turunan ini mengurutkan terlebih dahulu 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. Turunan ini mengurutkan terlebih dahulu menurut ga:browser, lalu ga:country, dalam urutan menaik: 
sort=ga:browser,ga:country

Saat menggunakan parameter sort, perhatikan hal berikut:

  • Urutkan hanya menurut nilai dimensi atau metrik yang telah Anda gunakan dalam parameter dimensions atau metrics. Jika permintaan Anda mengurutkan kolom yang tidak ditunjukkan dalam parameter dimensi atau metrik, Anda akan menerima error.
  • Secara default, string diurutkan dalam urutan abjad menaik di lokalitas en-US.
  • Secara default, angka diurutkan dalam urutan numerik yang naik.
  • Tanggal diurutkan dalam urutan menaik menurut tanggal secara default.

filter

filters=ga:medium%3D%3Dreferral
  1. Sintaksis Filter
  2. Operator Filter
  3. Ekspresi Filter
  4. Menggabungkan Filter
Opsional.

Parameter string kueri filters membatasi data yang ditampilkan dari permintaan Anda. Untuk menggunakan parameter filters, masukkan dimensi atau metrik yang akan digunakan untuk memfilter, 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 (atau tidak) disertakan dalam hasil. Setiap baris dalam hasil diuji terhadap filter tersebut: jika filter cocok, baris dipertahankan dan jika tidak cocok, baris akan dihapus.

  • Encoding URL: Library klien Google API otomatis mengenkode operator filter.
  • Pemfilteran dimensi: Pemfilteran terjadi sebelum dimensi apa pun digabungkan, sehingga metrik yang ditampilkan mewakili total hanya untuk dimensi yang relevan. Pada contoh di atas, jumlah kunjungan halaman hanya akan menjadi kunjungan halaman tersebut dengan Firefox sebagai browser.
  • Pemfilteran metrik: Pemfilteran pada 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 filter adalah kombinasi yang valid. Misalnya, Anda mungkin ingin membuat kueri untuk daftar tanggal kunjungan halaman, yang memfilter di browser tertentu. Lihat Referensi Dimensi dan Metrik untuk informasi selengkapnya.

Sintaksis Filter


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 — menetapkan jenis pencocokan filter yang akan digunakan. Operator bersifat spesifik untuk dimensi atau metrik.
  • ekspresi — menyatakan nilai yang akan disertakan 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.

Filter Metrik
Operator Deskripsi Formulir URL yang Dienkode Contoh
== Sama dengan %3D%3D Tampilkan hasil jika waktu di halaman tepat sepuluh detik:
filters=ga:timeOnPage%3D%3D10
!= Tidak sama dengan !%3D Tampilkan hasil jika waktu di halaman tidak sepuluh detik:
filters=ga:timeOnPage!%3D10
> Lebih dari %3E Tampilkan hasil jika waktu di halaman benar-benar lebih dari sepuluh detik:
filters=ga:timeOnPage%3E10
< Kurang dari %3C Tampilkan hasil jika waktu di halaman kurang dari sepuluh detik:
filters=ga:timeOnPage%3C10
>= Lebih dari atau sama dengan %3E%3D Tampilkan hasil jika waktu di halaman adalah sepuluh detik atau lebih:
filters=ga:timeOnPage%3E%3D10
<= Kurang dari atau sama dengan %3C%3D Tampilkan hasil jika waktu di halaman adalah sepuluh detik atau kurang:
filters=ga:timeOnPage%3C%3D10

Filter Dimensi
Operator Deskripsi Formulir URL yang Dienkode Contoh
== Pencocokan persis %3D%3D Metrik gabungan dengan kota yang Irlandia:
filters=ga:city%3D%3DIrvine
!= Tidak cocok !%3D Metrik gabungan yang kotanya bukan Irlandia:
filters=ga:city!%3DIrvine
=@ Berisi substring %3D@ Metrik gabungan yang berisi York:
filters=ga:city%3D@York
!@ Tidak berisi substring !@ Metrik gabungan yang tidak berisi York:
filters=ga:city!@York
=~ Berisi pencocokan untuk ekspresi reguler %3D~ Metrik gabungan tempat kota dimulai 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 gabungan 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 ke URL dengan cara yang biasa.
  • Karakter yang dicadangkan — Titik koma dan koma harus di-escape dengan garis miring terbalik saat muncul dalam ekspresi:
    • titik koma \;
    • 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 panjang dari 128 karakter akan menghasilkan kode status 400 Bad Request yang ditampilkan dari server.
    • Sensitivitas huruf — Pencocokan ekspresi reguler tidak peka huruf besar/kecil.

Menggabungkan Filter

Filter dapat digabungkan menggunakan logika boolean OR dan AND. Hal ini memungkinkan Anda memperluas batas 128 karakter ekspresi filter secara efektif.

ATAU

Operator OR ditentukan menggunakan koma (,). Operator ini lebih diutamakan daripada operator AND dan TIDAK boleh 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 di sistem operasi (Windows OR Macintosh):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

DAN

Operator AND ditentukan menggunakan titik koma (;). Didahului oleh operator OR dan CAN dapat digunakan untuk menggabungkan dimensi dan metrik dalam ekspresi yang sama.

Contoh: (masing-masing harus dienkode ke URL)

Negara adalah Amerika Serikat DAN browsernya adalah Firefox:
ga:country==United%20States;ga:browser==Firefox

Negara Amerika Serikat DAN bahasa tidak dimulai dengan 'en':
ga:country==United%20States;ga:language!~^en.*

Sistem operasinya adalah (Windows OR Macintosh) AND browser adalah (Firefox OR 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
Opsional.

Untuk mengetahui detail lengkap tentang cara meminta segmen di Core Reporting API, lihat Panduan Developer Segmen.

Untuk ringkasan konseptual segmen, lihat Referensi Fitur Segmen dan Segmen di Pusat Bantuan.

Dimensi dan Metrik diizinkan di segmen.
Tidak semua dimensi dan metrik dapat digunakan dalam segmen. Untuk meninjau dimensi dan metrik yang diizinkan dalam segmen, kunjungi Penjelajah Dimensi dan Metrik.

Tingkat sampling

samplingLevel=DEFAULT
Opsional.
Gunakan parameter ini untuk menetapkan tingkat pengambilan sampel (yaitu jumlah sesi yang digunakan untuk menghitung hasil) untuk kueri pelaporan. Nilai yang diizinkan konsisten dengan antarmuka web dan mencakup:
  • 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 yang lebih lambat.
Jika tidak diberikan, tingkat pengambilan sampel DEFAULT akan digunakan.
Lihat bagian Pengambilan sampel untuk mengetahui detail cara menghitung persentase sesi yang digunakan untuk kueri.

sertakan-baris-kosong

include-empty-rows=true
Opsional.
Nilai defaultnya adalah benar; jika ditetapkan ke false, baris yang semua nilai metriknya nol akan dihilangkan dari respons. Misalnya, jika Anda menyertakan lebih dari satu metrik dalam kueri, baris hanya akan dihapus jika semua nilai metrik adalah nol. Hal ini dapat berguna saat membuat permintaan yang diperkirakan bahwa jumlah baris yang valid jauh lebih kecil daripada jumlah nilai dimensi yang diharapkan.

indeks awal

start-index=10
Opsional.
Jika tidak tersedia, indeks awal adalah 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.

hasil maks

max-results=100
Opsional.
Jumlah maksimum baris yang akan disertakan dalam respons ini. Anda dapat menggunakannya bersama start-index untuk mengambil subset elemen, atau menggunakannya sendiri untuk membatasi jumlah elemen yang ditampilkan, dimulai dengan elemen pertama. Jika max-results tidak disediakan, kueri akan menampilkan nilai maksimum default 1.000 baris.
Analytics Core Reporting API menampilkan maksimum 10.000 baris per permintaan, berapa pun jumlah yang Anda minta. Fitur ini juga dapat menampilkan baris yang lebih sedikit dari yang diminta, jika segmen dimensi tidak sebanyak yang Anda harapkan. Misalnya, nilai yang Anda tetapkan untuk ga:country kurang dari 300, sehingga jika menyegmentasikan hanya menurut negara, Anda tidak bisa mendapatkan lebih dari 300 baris, meskipun Anda menetapkan max-results ke nilai yang lebih tinggi.

hasil

output=dataTable
Opsional.
Gunakan parameter ini untuk menetapkan jenis output data Analytics yang ditampilkan dalam respons. Nilai yang diizinkan adalah:
  • json — Menghasilkan properti rows default dalam respons, yang berisi objek JSON.
  • dataTable — Menghasilkan properti dataTable dalam respons, yang berisi objek Tabel Data. Objek Data Table ini dapat digunakan langsung dengan visualisasi Google Chart.
Jika tidak diberikan, respons JSON default akan digunakan.

Fields

fields=rows,columnHeaders(name,dataType)
Opsional.

Menentukan kolom mana yang akan ditampilkan dalam respons parsial. Jika hanya menggunakan subkumpulan kolom dalam respons API, Anda dapat menggunakan parameter fields untuk menentukan kolom yang akan disertakan.

Format parameter value permintaan kolom secara longgar berdasarkan sintaksis XPath. Sintaksis yang didukung dirangkum di bawah.

  • Gunakan daftar yang dipisahkan koma untuk memilih beberapa kolom.
  • Gunakan a/b untuk memilih kolom b yang disarangkan dalam kolom a; gunakan a/b/c untuk memilih kolom c yang bertingkat di dalam b.
  • Gunakan sub-pemilih untuk meminta kumpulan sub-kolom tertentu dari array atau objek dengan menempatkan ekspresi dalam tanda kurung "( )".
    Misalnya: fields=columnHeaders(name,dataType) hanya menampilkan kolom name dan dataType dalam array columnHeaders. Anda juga dapat menentukan satu sub-kolom, dengan fields=columnHeader(name) yang setara dengan fields=columnHeader/name.

cukup cetak

prettyPrint=false
Opsional.

Menampilkan respons dalam format yang dapat dibaca manusia jika true. Nilai default: false.

kuotaPengguna

quotaUser=4kh4r2h4
Opsional.

Memungkinkan Anda memberlakukan kuota per pengguna dari aplikasi sisi server meskipun alamat IP pengguna tidak diketahui. Hal ini dapat terjadi, misalnya, pada aplikasi yang menjalankan cron job pada App Engine atas nama pengguna. Anda dapat memilih string arbitrer apa pun yang secara unik mengidentifikasi pengguna, tetapi string tersebut dibatasi hingga 40 karakter.

Ini akan menggantikan userIp jika keduanya diberikan.

Tanggapan

Jika berhasil, permintaan ini akan menampilkan isi respons dengan struktur JSON yang ditetapkan di bawah. Jika parameter output ditetapkan ke dataTable, permintaan akan menampilkan isi respons dengan struktur JSON (Tabel Data) yang ditentukan di bawah ini.

Catatan: istilah "hasil" mengacu pada keseluruhan rangkaian baris yang cocok dengan kueri, sedangkan "respons" merujuk pada kumpulan baris yang ditampilkan pada halaman hasil saat ini. Jumlahnya dapat berbeda jika jumlah total hasil lebih besar dari ukuran halaman untuk respons saat ini, seperti yang dijelaskan dalam itemsPerPage.

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,
      ...
    }
  ]
}

Kolom Respons

Properti struktur isi respons didefinisikan sebagai berikut:

Nama Properti Nilai Deskripsi
kind string Jenis fasilitas. Nilai adalah "analytics#gaData".
id string ID untuk respons data ini.
query object Objek ini berisi semua nilai yang diteruskan sebagai parameter ke kueri. Arti dari setiap kolom dijelaskan dalam deskripsi parameter kueri yang sesuai.
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 Setelan default-nya adalah true; jika disetel ke false, baris yang semua nilai metriknya nol akan dihilangkan dari respons.
query.sort[] list Daftar metrik atau dimensi tempat data diurutkan.
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 baris sebenarnya yang ditampilkan. Jika parameter kueri max-results ditentukan, nilai itemsPerPage akan lebih kecil dari max-results atau 10.000. Nilai default itemsPerPage adalah 1000.
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 dapat lebih besar dari itemsPerPage. Lihat Paging untuk penjelasan lebih lanjut tentang totalResults dan itemsPerPage untuk kueri besar.
startDate string Tanggal mulai untuk kueri data, seperti yang ditentukan oleh parameter start-date.
endDate string Tanggal akhir untuk kueri data, seperti yang ditentukan oleh parameter end-date.
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 memiliki tampilan (profil) ini, seperti 30481.
profileInfo.webPropertyId string ID Properti Web yang mencakup tampilan (profil) ini, seperti UA-30481-1.
profileInfo.internalWebPropertyId string ID internal untuk properti web yang memiliki tampilan (profil) ini, seperti UA-30481-1.
profileInfo.profileName string Nama tampilan (profil).
profileInfo.tableId string ID tabel untuk tampilan (profil), terdiri dari "ga:" diikuti dengan ID tampilan (profil).
containsSampledData boolean True jika respons berisi data dengan sampel.
sampleSize string Jumlah sampel yang digunakan untuk menghitung data dengan sampel.
sampleSpace string Total ukuran ruang pengambilan sampel. 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 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. "DIMENSI" 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, dsb. Lihat respons API metadata untuk semua jenis data yang memungkinkan.
totalsForAllResults object Nilai total untuk metrik yang diminta sebagai pasangan nilai kunci 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 kolom N, dengan N = jumlah dimensi + jumlah metrik.
JSON (Tabel Data)
{
  "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 fasilitas. Nilai adalah "analytics#gaData".
id string ID untuk respons data ini.
query object Objek ini berisi semua nilai yang diteruskan sebagai parameter ke kueri. Arti dari setiap kolom dijelaskan dalam deskripsi parameter kueri yang sesuai.
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 Setelan default-nya adalah true; jika disetel ke false, baris yang semua nilai metriknya nol akan dihilangkan dari respons.
query.sort[] list Daftar metrik atau dimensi tempat data diurutkan.
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 baris sebenarnya yang ditampilkan. Jika parameter kueri max-results ditentukan, nilai itemsPerPage akan lebih kecil dari max-results atau 10.000. Nilai default itemsPerPage adalah 1000.
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 dapat lebih besar dari itemsPerPage. Lihat Paging untuk penjelasan lebih lanjut tentang totalResults dan itemsPerPage untuk kueri besar.
startDate string Tanggal mulai untuk kueri data, seperti yang ditentukan oleh parameter start-date.
endDate string Tanggal akhir untuk kueri data, seperti yang ditentukan oleh parameter end-date.
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 memiliki tampilan (profil) ini, seperti 30481.
profileInfo.webPropertyId string ID Properti Web yang mencakup tampilan (profil) ini, seperti UA-30481-1.
profileInfo.internalWebPropertyId string ID internal untuk properti web yang memiliki tampilan (profil) ini, seperti UA-30481-1.
profileInfo.profileName string Nama tampilan (profil).
profileInfo.tableId string ID tabel untuk tampilan (profil), terdiri dari "ga:" diikuti dengan ID tampilan (profil).
containsSampledData boolean True jika respons berisi data dengan sampel.
sampleSize string Jumlah sampel yang digunakan untuk menghitung data dengan sampel.
sampleSpace string Total ukuran ruang pengambilan sampel. 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 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. "DIMENSI" 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, dsb. Lihat respons API metadata untuk semua jenis data yang memungkinkan.
totalsForAllResults object Nilai total untuk metrik yang diminta sebagai pasangan nilai kunci 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 dari menggunakan indeks kolom). ID dimensi atau metrik digunakan untuk menetapkan nilai ini.
dataTable.cols[].label string Label untuk kolom (yang mungkin ditampilkan oleh 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, dengan setiap baris berupa objek yang berisi daftar nilai sel untuk dimensi yang diikuti dengan metrik. Urutan dimensi dan metrik sama dengan 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 error dan deskripsi. 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 nilai sampel untuk parameter di Query Explorer. Hasil kueri sampel 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 API 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 data sampel, kolom respons containsSampledData akan menjadi true. Selain itu, 2 properti akan memberikan informasi tentang tingkat pengambilan sampel 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,maka laporan didasarkan pada (201.000 / 220.000) * 100 = 91,36% sesi.

Lihat Pengambilan sampel untuk mengetahui deskripsi umum tentang pengambilan sampel dan cara penggunaannya di Google Analytics.


Menangani Hasil Data Besar

Jika Anda memperkirakan kueri akan menampilkan kumpulan hasil yang besar, gunakan panduan di bawah untuk membantu mengoptimalkan kueri API, menghindari error, dan meminimalkan penggunaan kuota yang berlebih. Perhatikan bahwa kita menetapkan dasar pengukuran performa dengan mengizinkan maksimum 7 dimensi dan 10 metrik dalam satu permintaan API. Meskipun beberapa kueri yang menentukan jumlah metrik dan dimensi yang besar mungkin memerlukan waktu pemrosesan yang lebih lama dibandingkan yang lain, pembatasan 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 ini memungkinkan penetapan hingga 7 dimensi dalam satu permintaan. Sering kali, Google Analytics harus menghitung hasil kueri yang kompleks ini dengan cepat. Tindakan ini dapat sangat memakan waktu jika jumlah baris yang dihasilkan tinggi. Misalnya, membuat kueri untuk kata kunci, menurut kota menurut jam mungkin cocok dengan jutaan baris data. Anda dapat meningkatkan performa dengan mengurangi jumlah baris yang perlu diproses oleh Google Analytics dengan membatasi jumlah dimensi dalam kueri Anda.

Memisahkan Kueri berdasarkan Rentang Tanggal

Daripada mem-paging hasil berdasarkan tanggal dari satu rentang tanggal yang panjang, pertimbangkan untuk membuat kueri terpisah selama satu minggu — atau bahkan satu hari — dalam satu waktu. Tentu saja, untuk set data yang besar, bahkan permintaan untuk data satu hari mungkin menampilkan lebih dari max-results, sehingga paging tidak dapat dihindari. Namun, jika jumlah baris yang cocok untuk kueri Anda lebih tinggi dari max-results, memisahkan rentang tanggal dapat mengurangi total waktu untuk mengambil hasil tersebut. Pendekatan ini dapat meningkatkan performa pada kueri thread tunggal dan paralel.

Paging

Paging untuk hasil dapat menjadi cara yang berguna untuk membagi hasil yang besar menjadi beberapa bagian yang dapat dikelola. Kolom totalResults memberi tahu jumlah baris yang cocok, dan itemsPerPage memberikan jumlah baris maksimum yang dapat ditampilkan dalam hasil. Jika ada rasio totalResults yang tinggi terhadap itemsPerPage, setiap kueri mungkin memerlukan waktu lebih lama dari yang diperlukan. Jika hanya memerlukan baris dalam jumlah terbatas, seperti untuk tujuan tampilan, Anda dapat menetapkan batas eksplisit ukuran respons melalui parameter max-results. Namun, jika aplikasi Anda perlu memproses kumpulan hasil yang besar secara keseluruhan, permintaan untuk baris maksimum yang diizinkan mungkin lebih efisien.

Menggunakan gzip

Cara yang mudah dan nyaman untuk mengurangi bandwidth yang diperlukan untuk setiap permintaan adalah dengan mengaktifkan kompresi gzip. Meskipun diperlukan waktu CPU tambahan untuk membuka hasil, kompromi dengan biaya jaringan biasanya membuatnya sangat bermanfaat. Untuk menerima respons berenkode gzip, Anda harus melakukan dua hal: menetapkan header Accept-Encoding, dan mengubah agen pengguna agar berisi string gzip. Berikut contoh header HTTP yang dibuat dengan benar untuk mengaktifkan kompresi gzip:

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