Search Analytics: query

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 satu atau beberapa hari.

Jika tanggal adalah salah satu dimensi, hari tanpa data akan dihilangkan dari daftar hasil. Untuk mempelajari 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 untuk menampilkan semua baris data, melainkan baris teratas.

Lihat batas jumlah data yang tersedia.

Contoh POST JSON: 
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"]
}
Coba sekarang.

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
        }
      ]
    }
  ],
  "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". Nilai dimensi pengelompokan digabungkan untuk membuat kunci unik bagi setiap baris hasil. Jika tidak ada dimensi yang ditentukan, semua nilai akan digabungkan ke dalam satu baris. Tidak ada batasan jumlah dimensi yang dapat Anda gunakan untuk mengelompokkan, tetapi Anda tidak dapat mengelompokkan berdasarkan dimensi yang sama dua kali. Contoh: [country, device]
searchType string Tidak digunakan lagi, gunakan type
type string [Opsional] Filter hasil ke jenis berikut:
  • "discover": Hasil Discover
  • "googleNews": Hasil dari news.google.com dan aplikasi Google Berita di Android dan iOS. Tidak menyertakan hasil dari tab "Berita" di Google Penelusuran.
  • "news": Hasil penelusuran dari tab "Berita" di Google Penelusuran.
  • "image": Hasil penelusuran dari tab "Gambar" di Google Penelusuran.
  • "video": Hasil penelusuran video
  • "web": [Default] Memfilter hasil ke tab gabungan ("Semua") di Google Penelusuran. Tidak mencakup hasil Discover atau Google Berita.
dimensionFilterGroups[] list [Opsional] Satu 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 true (benar) ("and"), atau satu atau beberapa filter harus menampilkan true (belum didukung).

Nilai yang dapat diterima adalah:
  • "and": Semua filter dalam grup harus menampilkan nilai benar agar grup filter bernilai benar.
dimensionFilterGroups[].filters[] list [Opsional] Nol atau beberapa filter untuk diuji terhadap baris. Setiap filter terdiri dari nama dimensi, operator, dan nilai. Panjang maksimum 4.096 karakter. Contoh: 
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string Dimensi yang diterapkan 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:
  • "country": Memfilter berdasarkan negara yang ditentukan, seperti yang ditentukan oleh kode negara 3 huruf (ISO 3166-1 alpha-3).
  • "device": Memfilter hasil berdasarkan jenis perangkat yang ditentukan. Nilai yang didukung:
    • DESKTOP
    • SELULAR
    • TABLET
  • "page": Memfilter berdasarkan string URI yang ditentukan.
  • "query": Memfilter berdasarkan string kueri yang ditentukan.
  • "searchAppearance": Memfilter berdasarkan fitur hasil penelusuran tertentu. Untuk melihat daftar nilai yang tersedia, jalankan kueri yang dikelompokkan menurut "searchAppearance". Daftar lengkap nilai dan deskripsi juga tersedia di dokumentasi bantuan.
dimensionFilterGroups[].filters[].operator string [Opsional] Cara nilai yang ditentukan harus cocok (atau tidak cocok) dengan nilai dimensi untuk baris.

Nilai yang dapat diterima:
  • "contains": Nilai baris harus berisi atau sama dengan ekspresi Anda (tidak peka huruf besar/kecil).
  • "equals": [Default] Ekspresi Anda harus sama persis dengan nilai baris (peka huruf besar/kecil untuk dimensi halaman dan kueri).
  • "notContains": Nilai baris tidak boleh berisi ekspresi Anda sebagai substring atau pencocokan lengkap (tidak peka huruf besar/kecil).
  • "notEquals": Ekspresi Anda tidak boleh sama persis dengan nilai baris (peka huruf besar/kecil untuk dimensi halaman dan kueri).
  • "includingRegex": Ekspresi reguler sintaksis RE2 yang harus dicocokkan.
  • "excludingRegex": Ekspresi reguler sintaksis RE2 yang tidak boleh dicocokkan.
dimensionFilterGroups[].filters[].expression string Nilai untuk filter yang akan dicocokkan atau dikecualikan, bergantung pada operator.
aggregationType string

[Opsional] Cara data digabungkan. Jika digabungkan berdasarkan properti, semua data untuk properti yang sama akan digabungkan; jika digabungkan berdasarkan halaman, semua data akan digabungkan berdasarkan URI kanonis. Jika Anda memfilter atau mengelompokkan menurut halaman, pilih otomatis; jika tidak, Anda dapat menggabungkan menurut properti atau halaman, bergantung pada cara Anda ingin data dihitung; lihat dokumentasi bantuan untuk mempelajari cara data dihitung secara berbeda menurut situs versus halaman.

Catatan: Jika mengelompokkan atau memfilter menurut halaman, Anda tidak dapat menggabungkan menurut properti.

Jika Anda menentukan nilai 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:
  • "auto": [Default] Izinkan layanan menentukan jenis agregasi yang sesuai.
  • "byNewsShowcasePanel": Nilai gabungan menurut panel Berita Pilihan dari Google Berita. Ini harus digunakan bersama dengan filter NEWS_SHOWCASE searchAppearance dan type=discover atau type=googleNews. Jika Anda mengelompokkan berdasarkan halaman, memfilter berdasarkan halaman, atau memfilter ke searchAppearance lain, Anda tidak dapat menggabungkan menurut byNewsShowcasePanel.
  • "byPage": Menggabungkan nilai menurut URI.
  • "byProperty": Menggabungkan nilai berdasarkan properti. Tidak didukung untuk type=discover atau type=googleNews
rowLimit integer [Opsional; Rentang valid adalah 1–25.000; Defaultnya 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 baru. Jika "final" (tidak peka huruf besar/kecil) atau jika parameter ini dihilangkan, data yang ditampilkan hanya akan menyertakan data yang telah diselesaikan.

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, semua hasil untuk "usa, tablet" akan dikelompokkan, semua hasil untuk "usa, mobile" akan dikelompokkan, dan seterusnya. Lihat dokumentasi laporan Analisis Penelusuran untuk mempelajari cara penghitungan klik, tayangan, dan sebagainya, serta artinya.

Hasil diurutkan berdasarkan jumlah klik, dalam urutan menurun, kecuali jika Anda mengelompokkan menurut tanggal. Jika demikian, hasil akan diurutkan menurut tanggal, dalam urutan menaik (terlama terlebih dahulu, terbaru terakhir). Jika ada yang sama di antara dua baris, tata urutannya bersifat arbitrer.

Lihat properti rowLimit dalam permintaan untuk mempelajari 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 Klik jumlah untuk baris.
rows[].impressions double Jumlah tayangan 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 perbedaan penghitungan data menurut situs dan menurut halaman.

Nilai yang dapat diterima adalah:
  • "auto"
  • "byPage": Hasil digabungkan berdasarkan halaman.
  • "byProperty": Hasil digabungkan berdasarkan properti.

Cobalah!

Gunakan API Explorer di bawah untuk memanggil metode ini pada data langsung dan melihat responsnya.