Memerlukan otorisasi
Buat kueri data traffic penelusuran Anda dengan filter dan parameter yang Anda tentukan. Metode ini menampilkan nol atau beberapa baris yang dikelompokkan menurut row key (dimensi) yang Anda tentukan. Anda harus menentukan rentang tanggal satu hari atau lebih.
Jika tanggal adalah salah satu dimensi, hari tanpa data akan dihilangkan dari daftar hasil. Untuk mengetahui hari mana yang memiliki data, buat kueri tanpa filter yang dikelompokkan menurut tanggal, untuk rentang tanggal yang diinginkan.
Hasil diurutkan berdasarkan jumlah klik menurun. Jika dua baris memiliki jumlah klik yang sama, baris tersebut akan diurutkan secara arbitrer.
Lihat contoh python untuk memanggil metode ini.
API ini dibatasi oleh batasan internal Search Console dan tidak menjamin akan menampilkan semua baris data, melainkan hanya baris data teratas.
Lihat batasan jumlah data yang tersedia.
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY}
{
"startDate": "2015-04-01",
"endDate": "2015-05-01",
"dimensions": ["country","device"]
}Permintaan
Permintaan HTTP
POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query
Parameter
| Nama parameter | Nilai | Deskripsi |
|---|---|---|
| Parameter jalur | ||
siteUrl |
string |
URL properti seperti yang ditetapkan di Search Console. Contoh:
http://www.example.com/ (untuk properti awalan URL) atau
sc-domain:example.com (untuk Properti domain)
|
Otorisasi
Permintaan ini memerlukan otorisasi dengan setidaknya salah satu cakupan berikut (baca selengkapnya tentang autentikasi dan otorisasi).
| Cakupan |
|---|
https://www.googleapis.com/auth/webmasters.readonly |
https://www.googleapis.com/auth/webmasters |
Isi permintaan
Dalam isi permintaan, berikan data dengan struktur berikut:
{
"startDate": string,
"endDate": string,
"dimensions": [
string
],
"type": string,
"dimensionFilterGroups": [
{
"groupType": string,
"filters": [
{
"dimension": string,
"operator": string,
"expression": string
}
],
"filterLists": [
{
"dimension": string,
"expressions": [
string
]
}
]
}
],
"aggregationType": string,
"rowLimit": integer,
"startRow": integer
}| Nama properti | Nilai | Deskripsi | Catatan |
|---|---|---|---|
startDate |
string |
[Wajib] Tanggal mulai rentang tanggal yang diminta, dalam format YYYY-MM-DD, dalam waktu PT (UTC - 7.00/8.00). Harus kurang dari atau sama dengan tanggal akhir. Nilai ini disertakan dalam rentang. | |
endDate |
string |
[Wajib] Tanggal akhir rentang tanggal yang diminta, dalam format YYYY-MM-DD, dalam waktu PT (UTC - 7.00/8.00). Harus lebih besar dari atau sama dengan tanggal mulai. Nilai ini disertakan dalam rentang. | |
dimensions[] |
list |
[Opsional] Nol atau beberapa dimensi untuk mengelompokkan hasil. Hasil dikelompokkan dalam urutan dimensi yang Anda berikan. Anda dapat menggunakan nama dimensi apa pun di dimensionFilterGroups[].filters[].dimension serta "date" dan "hour". Nilai dimensi pengelompokan digabungkan untuk membuat kunci unik untuk setiap baris hasil. Jika tidak ada dimensi yang ditentukan, semua nilai akan digabungkan menjadi satu baris. Tidak ada batasan jumlah dimensi yang dapat Anda gunakan untuk mengelompokkan, tetapi Anda tidak dapat mengelompokkan menurut dimensi yang sama dua kali. Contoh: [country, device] | |
searchType |
string |
Tidak digunakan lagi, gunakan type sebagai gantinya
|
|
type |
string |
[Opsional] Filter hasil ke jenis berikut:
|
|
dimensionFilterGroups[] |
list |
[Opsional] Nol atau beberapa grup filter yang akan diterapkan ke nilai pengelompokan dimensi. Semua grup filter harus cocok agar baris ditampilkan dalam respons. Dalam satu grup filter, Anda dapat menentukan apakah semua filter harus cocok, atau setidaknya satu filter harus cocok. | |
dimensionFilterGroups[].groupType |
string |
Apakah semua filter dalam grup ini harus menampilkan nilai benar ("and"), atau satu atau beberapa filter harus menampilkan nilai benar (belum didukung).
Nilai yang dapat diterima adalah:
|
|
dimensionFilterGroups[].filters[] |
list |
[Opsional] Nol atau beberapa filter untuk diuji terhadap baris. Setiap filter terdiri dari nama dimensi, operator, dan nilai. Panjang maksimal 4.096 karakter. Contoh:
country equals FRA query contains mobile use device notContains tablet |
|
dimensionFilterGroups[].filters[].dimension |
string |
Dimensi yang menerapkan filter ini. Anda dapat memfilter menurut dimensi apa pun yang tercantum di sini, meskipun Anda tidak mengelompokkan menurut dimensi tersebut.
Nilai yang dapat diterima adalah:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Opsional] Cara nilai yang Anda tentukan harus cocok (atau tidak cocok) dengan nilai dimensi untuk baris.
Nilai yang dapat diterima adalah:
|
|
dimensionFilterGroups[].filters[].expression |
string |
Nilai yang akan dicocokkan atau dikecualikan oleh filter, bergantung pada operator. | |
dimensionFilterGroups[].filterLists[] |
list |
[Opsional] Nol atau beberapa filter dimensi multi-nilai untuk diuji terhadap baris.
Tidak seperti filters[], yang mencocokkan satu nilai per entri,
filterLists[] memungkinkan pencocokan dengan beberapa nilai pencocokan persis untuk
satu dimensi dalam satu filter. Baris cocok dengan daftar filter jika nilainya untuk dimension yang ditentukan sama dengan salah satu expressions yang diberikan. Perhatikan bahwa satu permintaan tidak dapat memfilter dimensi yang sama di filters dan filterLists secara bersamaan. |
|
dimensionFilterGroups[].filterLists[].dimension |
string |
[Wajib] Dimensi yang menerapkan daftar filter ini.
Nilai yang dapat diterima adalah:
|
|
dimensionFilterGroups[].filterLists[].expressions[] |
list |
[Wajib] Daftar nilai (string) yang akan difilter. |
|
aggregationType |
string |
[Opsional] Cara data digabungkan. Jika digabungkan menurut properti, semua data untuk properti yang sama akan digabungkan; jika digabungkan menurut halaman, semua data akan digabungkan menurut URI kanonis. Jika Anda memfilter atau mengelompokkan menurut halaman, pilih otomatis; jika tidak, Anda dapat menggabungkan menurut properti atau menurut halaman, bergantung pada cara Anda ingin data dihitung; lihat dokumentasi bantuan untuk mempelajari perbedaan penghitungan data menurut situs versus menurut halaman. Catatan: Jika mengelompokkan atau memfilter menurut halaman, Anda tidak dapat menggabungkan menurut properti. Jika Anda menentukan nilai selain auto, jenis agregasi dalam hasil akan cocok dengan jenis yang diminta, atau jika Anda meminta jenis yang tidak valid, Anda akan mendapatkan error. API tidak akan pernah mengubah jenis agregasi Anda jika jenis yang diminta tidak valid. Nilai yang dapat diterima adalah:
|
|
rowLimit |
integer |
[Opsional; Rentang yang valid adalah 1–25.000; Default-nya adalah 1.000] Jumlah maksimum baris yang akan ditampilkan. Untuk menelusuri hasil, gunakan offset startRow. |
|
startRow |
integer |
[Opsional; Defaultnya adalah 0] Indeks berbasis nol dari baris pertama dalam respons. Harus berupa bilangan non-negatif. Jika startRow melebihi jumlah hasil untuk kueri, responsnya akan berupa respons yang berhasil dengan nol baris. |
|
dataState |
string |
[Opsional] Jika "all" (tidak peka huruf besar/kecil), data akan menyertakan data terbaru. Jika "final" (tidak peka huruf besar/kecil) atau jika parameter ini dihilangkan, data yang ditampilkan hanya akan menyertakan data yang telah difinalisasi. Jika "hourly_all" (tidak peka huruf besar/kecil), data akan menyertakan perincian per jam. Hal ini akan menunjukkan bahwa data per jam menyertakan data parsial dan harus digunakan saat mengelompokkan menurut dimensi HOUR API. |
Respons
Hasil dikelompokkan sesuai dengan dimensi yang ditentukan dalam permintaan. Semua nilai dengan kumpulan nilai dimensi yang sama akan dikelompokkan ke dalam satu baris. Misalnya, jika Anda mengelompokkan menurut dimensi negara, semua hasil untuk "usa" akan dikelompokkan bersama, semua hasil untuk "mdv" akan dikelompokkan bersama, dan seterusnya. Jika Anda mengelompokkan menurut negara dan perangkat, semua hasil untuk "usa, tablet" akan dikelompokkan, semua hasil untuk "usa, seluler" akan dikelompokkan, dan seterusnya. Lihat dokumentasi laporan Analisis Penelusuran untuk mempelajari secara spesifik cara penghitungan klik, tayangan, dan sebagainya, serta artinya.
Hasil diurutkan berdasarkan jumlah klik, dalam urutan menurun, kecuali jika Anda mengelompokkan menurut tanggal, yang dalam hal ini hasil diurutkan berdasarkan tanggal, dalam urutan menaik (terlama terlebih dahulu, terbaru terakhir). Jika ada dua baris yang sama, tata urutannya bersifat arbitrer.
Lihat properti rowLimit dalam permintaan untuk mempelajari jumlah nilai maksimum yang dapat ditampilkan.
{
"rows": [
{
"keys": [
string
],
"clicks": double,
"impressions": double,
"ctr": double,
"position": double
}
],
"responseAggregationType": string
}| Nama properti | Nilai | Deskripsi | Catatan |
|---|---|---|---|
rows[] |
list |
Daftar baris yang dikelompokkan menurut nilai kunci dalam urutan yang diberikan dalam kueri. | |
rows[].keys[] |
list |
Daftar nilai dimensi untuk baris tersebut, yang dikelompokkan menurut dimensi dalam permintaan, dalam urutan yang ditentukan dalam permintaan. | |
rows[].clicks |
double |
Jumlah klik untuk baris. | |
rows[].impressions |
double |
Jumlah tayangan iklan untuk baris. | |
rows[].ctr |
double |
Rasio Klik-Tayang (CTR) untuk baris. Nilai berkisar dari 0 hingga 1,0, inklusif. | |
rows[].position |
double |
Posisi rata-rata di hasil penelusuran. | |
responseAggregationType |
string |
Cara hasil digabungkan. Lihat dokumentasi bantuan untuk mempelajari perbedaan penghitungan data menurut situs dan menurut halaman.
Nilai yang dapat diterima adalah:
|
|
metadata |
object |
Objek yang dapat ditampilkan dengan hasil kueri Anda, yang memberikan konteks tentang status data. Saat Anda meminta data terbaru (menggunakan Semua tanggal dan waktu yang diberikan dalam objek ini menggunakan zona waktu Kolom spesifik yang ditampilkan dalam objek ini bergantung pada cara Anda mengelompokkan data dalam permintaan:
|
Cobalah!
Gunakan APIs Explorer di bawah untuk memanggil metode ini pada data langsung dan melihat responsnya.