Memerlukan otorisasi
Mengkueri data traffic penelusuran dengan filter dan parameter yang Anda tetapkan. Metode ini menampilkan nol atau beberapa baris yang dikelompokkan menurut kunci baris (dimensi) yang Anda tentukan. Anda harus menentukan rentang tanggal untuk satu atau beberapa hari.
Jika tanggal adalah salah satu dimensi, hari tanpa data akan dihapus dari daftar hasil. Untuk mempelajari hari apa yang memiliki data, buat kueri tanpa filter yang dikelompokkan menurut tanggal, untuk rentang tanggal yang diinginkan.
Hasil diurutkan menurut jumlah klik secara menurun. Jika dua baris memiliki jumlah klik yang sama, baris tersebut akan diurutkan dengan cara acak.
Lihat contoh python untuk memanggil metode ini.
API ini dibatasi oleh batasan internal Search Console dan tidak menjamin untuk menampilkan semua baris data, melainkan baris teratas.
Lihat batas 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 ditentukan 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 lebih lanjut 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 } ] } ], "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 Pasifik (UTC - 7.00/8.00). Harus lebih kecil 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 sesuai urutan penyediaan dimensi ini.Anda dapat menggunakan nama dimensi apa pun di dimensionFilterGroups[].filters[].dimension serta "tanggal".Pengelompokan nilai dimensi 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 kelompokkan, tetapi Anda tidak dapat mengelompokkan menurut dimensi yang sama dua kali. Contoh: [negara, perangkat] | |
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 pada 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 salah satunya harus cocok. | |
dimensionFilterGroups[].groupType |
string |
Apakah semua filter dalam grup ini harus menampilkan true (benar) ("and"), atau satu atau beberapa filter harus menampilkan true (belum didukung).
Nilai yang dapat diterima:
|
|
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 tempat filter ini diterapkan. Anda dapat memfilter menurut dimensi yang tercantum di sini, meskipun Anda tidak mengelompokkan menurut dimensi tersebut.
Nilai yang dapat diterima:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Opsional] Cara nilai yang ditentukan harus cocok (atau tidak cocok) dengan nilai dimensi untuk baris.
Nilai yang dapat diterima:
|
|
dimensionFilterGroups[].filters[].expression |
string |
Nilai untuk filter yang akan dicocokkan atau dikecualikan, bergantung pada operator. | |
aggregationType |
string |
[Opsional] Cara data diagregasi. Jika digabungkan berdasarkan properti, semua data untuk properti yang sama digabungkan; jika digabungkan berdasarkan halaman, semua data akan digabungkan berdasarkan halaman kanonis URI. Jika Anda memfilter atau mengelompokkan menurut halaman, pilih otomatis; jika tidak, Anda dapat menggabungkan dengan properti atau halaman, bergantung pada cara Anda menghitung data yang diinginkan; lihat dokumentasi bantuan untuk mempelajari bagaimana data dihitung secara berbeda berdasarkan situs versus berdasarkan halaman. Catatan: Jika Anda mengelompokkan atau memfilter berdasarkan halaman, Anda tidak dapat menggabungkan berdasarkan properti. Jika Anda menentukan selain otomatis, 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:
|
|
rowLimit |
integer |
[Opsional; Rentang yang valid adalah 1–25.000; Jumlah defaultnya adalah 1.000] Jumlah maksimum baris yang akan ditampilkan. Untuk melihat-lihat hasil, gunakan offset startRow . |
|
startRow |
integer |
[Opsional; Defaultnya adalah 0] Indeks berbasis nol dari baris pertama dalam respons. Harus berupa angka yang tidak negatif. Jika startRow melebihi jumlah hasil untuk kueri, responsnya akan menjadi respons yang berhasil dengan baris nol. |
|
dataState |
string |
[Opsional] Jika "semua" (tidak peka huruf besar/kecil), data akan mencakup data baru. Jika "final" (tidak peka huruf besar/kecil) atau jika parameter ini dihilangkan, data yang ditampilkan hanya akan menyertakan data akhir. |
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 berdasarkan negara dan perangkat, maka semua hasil untuk "usa, tablet" akan dikelompokkan, semua hasil untuk "usa, mobile" 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 Anda mengelompokkan berdasarkan tanggal, dengan hasil diurutkan berdasarkan tanggal, dalam urutan menaik (terlama dulu, terbaru terakhir). Jika ada yang sama di antara dua baris, tata urutannya bersifat arbitrer.
Lihat properti rowLimit dalam permintaan untuk mengetahui jumlah maksimum nilai 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 berdasarkan nilai kunci dalam urutan yang diberikan dalam kueri. | |
rows[].keys[] |
list |
Daftar nilai dimensi untuk baris tersebut, yang dikelompokkan sesuai dengan 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. Nilainya 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 cara penghitungan data secara berbeda per situs versus per halaman.
Nilai yang dapat diterima:
|
Cobalah!
Gunakan APIs Explorer di bawah untuk memanggil metode ini pada data langsung dan melihat responsnya.