Dokumen ini memberikan referensi lengkap baik untuk kueri maupun respons untuk Multi-Channel Funnel Reporting API.
Pengantar
Multi-Channel Funnel Reporting API memungkinkan Anda meminta data laporan Funnel Multisaluran Google Analytics. Setiap laporan berisi statistik yang berasal dari data yang dikirim kembali oleh kode pelacakan ke Analytics, yang diatur sebagai dimensi dan metrik. Dengan memilih kombinasi dimensi dan metrik sendiri, Anda dapat menggunakan Reporting API untuk membuat laporan yang disesuaikan dengan spesifikasi Anda sendiri.
API tersebut berisi satu metode yang meminta data laporan: report.get. Dengan metode ini, Anda memberikan ID tabel yang sesuai dengan tampilan (profil) yang datanya ingin Anda ambil. Selain itu, Anda menentukan hal berikut:
- Kombinasi dimensi dan metrik.
- Rentang tanggal.
- Kumpulan parameter opsi yang mengontrol data yang ditampilkan
API membuat metode report.get tersedia di endpoint REST: https://www.googleapis.com/analytics/v3/data/mcf. Bagian berikut menampilkan contoh permintaan dan menjelaskan setiap parameter.
Permintaan
API ini menyediakan satu metode untuk meminta data:
analytics.data.mcf.get()
API juga dapat dikueri sebagai endpoint REST:
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/mcf ?ids=ga:12345 &metrics=mcf:totalConversions,mcf:totalConversionValue &start-date=2011-10-01 &end-date=2011-10-31
Setiap parameter kueri URL menentukan parameter kueri API yang harus dienkode ke URL.
Semua Permintaan ke Multi-Channel Funnel Reporting API harus diberi otorisasi, sebaiknya melalui OAuth 2.0.
Ringkasan Parameter Kueri
Tabel berikut meringkas semua parameter kueri yang diterima oleh Multi-Channel Funnel 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
mcf:totalConversions,mcf:totalConversionValue .
Kueri yang valid harus mencantumkan setidaknya satu metrik. |
dimensions |
string |
no | Daftar dimensi yang dipisahkan koma untuk laporan Funnel Multisaluran,
seperti mcf:source,mcf:keyword . |
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. |
samplingLevel |
string |
no | Tingkat sampling yang diinginkan. Nilai yang Diizinkan:
|
start-index |
integer |
no | Baris pertama data yang akan diambil, mulai dari 1.
Gunakan parameter ini sebagai mekanisme penomoran halaman beserta
parameter max-results . |
max-results |
integer |
no | Jumlah baris maksimum yang akan disertakan dalam respons. |
Detail Parameter Kueri
ids
ids=ga:12345
ga:
namespace dengan
ID tampilan (profil) laporan. Anda dapat mengambil ID tampilan (profil) untuk
laporan
menggunakan metode analytics.management.profiles.list
,
yang menyediakan id
pada resource Tampilan (Profil) di
Google Analytics Management API.
tanggal-mulai
start-date=2011-10-01
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 2011-01-01
.
Tidak ada batasan atas untuk start-date
.Contoh rentang tanggal selama 7 hari terakhir (mulai kemarin) menggunakan tanggal relatif:
&start-date=7daysAgo &end-date=yesterday
tanggal-akhir
end-date=2011-10-31
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=mcf:source,mcf:keyword
Parameter dimensi menentukan kunci data utama untuk
laporan Funnel Multisaluran, seperti mcf:source
atau mcf:medium
.
Gunakan dimensi untuk menyegmentasikan metrik konversi Anda. Misalnya, meskipun Anda
dapat meminta jumlah total konversi ke situs, mungkin akan
lebih menarik untuk meminta jumlah konversi yang dikelompokkan menurut media.
Dalam hal ini, Anda akan melihat jumlah konversi dari organik, rujukan,
email, 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.
Nilai Tidak Tersedia
Jika nilai dimensi tidak dapat ditentukan, Analytics akan menggunakan string khusus (not set).
metrics
metrics=mcf:totalConversions,mcf:totalConversionValue
Statistik gabungan untuk aktivitas pengguna ke situs Anda, seperti jumlah
konversi total atau nilai konversi total.
Jika kueri tidak memiliki parameter dimensions
, metrik yang ditampilkan akan memberikan nilai gabungan untuk rentang tanggal yang diminta, seperti total nilai konversi secara keseluruhan. Namun, saat dimensi diminta, nilai akan disegmentasikan menurut nilai dimensi.
Misalnya, mcf:totalConversions
yang diminta dengan
mcf:source
akan menampilkan total konversi per sumber.
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.
sort
sort=mcf:source,mcf:medium
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 sumber konversi teratas saya dan melalui media apa?"
Anda dapat membuat kueri dengan parameter berikut. Pengurutan ini diurutkan
pertama menurut mcf:source
, lalu menurut mcf:medium
,
keduanya dalam urutan menaik:
sort=mcf:source,mcf:medium
Untuk menjawab pertanyaan terkait "Apa media konversi teratas saya,
dan dari sumber mana?", Anda dapat membuat kueri dengan
parameter berikut. Pengurutan ini diurutkan pertama kali berdasarkan mcf:medium
, lalu mcf:source
, keduanya dalam urutan menaik:
sort=mcf:medium,mcf:source
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=mcf: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 mcf:totalConversions
dan mcf:source
untuk
tampilan (profil) 12134
, dengan dimensi
mcf:medium
adalah string referral
:
https://www.googleapis.com/analytics/v3/data/mcf ?ids=mcf:12134 &dimensions=mcf:source &metrics=mcf:totalConversions &filters=mcf:medium%3D%3Dreferral &start-date=2011-10-01 &end-date=2011-10-31
Baca Referensi Core Reporting API untuk mengetahui detailnya.
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.max-results
max-results=100
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 dari yang pertama.
Jika max-results
tidak diberikan, kueri akan menampilkan jumlah maksimum default 1.000 baris.
Multi-ChannelFunnel Reporting API menampilkan maksimum 10.000 baris
per permintaan, berapa pun jumlah yang Anda minta. Contoh ini juga dapat menampilkan
baris yang lebih sedikit dari yang diminta, jika tidak ada segmen dimensi
sebanyak yang Anda harapkan. Misalnya, ada kurang dari 300
nilai yang memungkinkan untuk mcf:medium
. Jadi, saat melakukan segmentasi hanya
menurut media, Anda tidak bisa mendapatkan lebih dari 300 baris, meskipun
menetapkan max-results
ke nilai yang lebih tinggi.
Respons
Jika berhasil, permintaan ini akan menampilkan isi respons dengan struktur JSON 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.
Format Respons
{
"kind": "analytics#mcfData",
"id": string,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"sort": [
string
],
"filters": string,
"samplingLevel": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"selfLink": string,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"containsSampledData": boolean,
"sampleSize": string,
"sampleSpace": string,
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"totalsForAllResults": [
{
metricName: string,
...
}
]
"rows": [
[
McfData.Rows
]
],
}
Kolom Respons
Properti struktur isi respons didefinisikan sebagai berikut:
Nama Properti | Nilai | Deskripsi |
---|---|---|
kind |
string |
Jenis resource. Nilainya adalah "analytics#mcfData". |
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.sort[] |
list |
Daftar metrik atau dimensi yang digunakan untuk mengurutkan data. |
query.filters |
string |
Daftar filter metrik atau dimensi yang dipisahkan koma. |
query.samplingLevel |
string |
Requested sampling level. |
query.start-index |
integer |
Indeks awal baris. Nilai defaultnya adalah 1. |
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.
|
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" atau "MCF_SEQUENCE" sebagai jenis data.
Header kolom metrik memiliki jenis data untuk nilai metrik seperti "INTEGER" , "DOUBLE" , "CURRENCY" , dll. |
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 laporan, dengan setiap baris berisi daftar
objek Objek
{ "primitiveValue": "2183" }
{ "conversionPathValue": [ { "interactionType" : "CLICK", "nodeValue" : "google" }, { "interactionType" : "CLICK", "nodeValue" : "google" } ] } |
Kode Error
Multi-ChannelFunnel 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!
Gunakan APIs Explorer di bawah untuk memanggil metode ini pada data live dan melihat responsnya.
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 MCF 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)