Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Search Analytics: query

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 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, ajukan kueri tanpa filter yang dikelompokkan menurut tanggal, untuk rentang tanggal yang diinginkan.

Hasil diurutkan berdasarkan jumlah klik dalam urutan menurun. Jika dua baris memiliki jumlah klik yang sama, baris tersebut akan diurutkan secara 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 data teratas.

Lihat batasan 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 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
`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 ke dalam satu baris. Tidak ada batasan jumlah dimensi yang dapat Anda kelompokkan, tetapi Anda tidak dapat mengelompokkan berdasarkan 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: "`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] Filter hasil ke tab gabungan ("Semua") di Google Penelusuran. Tidak menyertakan hasil Discover atau Google Berita.
`dimensionFilterGroups[]`	`list`	[Opsional] Nol atau beberapa grup filter untuk diterapkan ke nilai pengelompokan dimensi. Semua grup filter harus cocok agar baris dapat ditampilkan dalam respons. Dalam satu grup filter, Anda dapat menentukan apakah semua filter harus cocok, atau setidaknya satu harus cocok.
`dimensionFilterGroups[].groupType`	`string`	Apakah semua filter dalam grup ini harus menampilkan nilai benar ("and"), atau satu atau beberapa harus menampilkan nilai benar (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 oleh filter ini. Anda dapat memfilter berdasarkan dimensi apa pun yang tercantum di sini, meskipun Anda tidak mengelompokkan berdasarkan dimensi tersebut. Nilai yang dapat diterima adalah: "`country`": Filter terhadap negara yang ditentukan, seperti yang ditentukan oleh kode negara 3 huruf (ISO 3166-1 alpha-3). "`device`": Filter hasil terhadap jenis perangkat yang ditentukan. Nilai yang didukung: DESKTOP MOBILE TABLET "`page`": Filter terhadap string URI yang ditentukan. "`query`": Filter terhadap string kueri yang ditentukan. "`searchAppearance`": Filter terhadap fitur hasil penelusuran tertentu. Untuk melihat daftar nilai yang tersedia, jalankan kueri yang dikelompokkan menurut "searchAppearance". Daftar lengkap nilai dan deskripsi juga tersedia dalam dokumentasi bantuan.
`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: "`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 kecocokan 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 cocok. "`excludingRegex`": Ekspresi reguler sintaksis RE2 yang tidak boleh cocok.
`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 berdasarkan halaman, pilih otomatis; jika tidak, Anda dapat menggabungkan berdasarkan properti atau berdasarkan halaman, bergantung pada cara Anda ingin data dihitung; lihat dokumentasi bantuan untuk mempelajari cara data dihitung secara berbeda menurut situs dan menurut halaman. Catatan: Jika Anda mengelompokkan atau memfilter berdasarkan halaman, Anda tidak dapat menggabungkan berdasarkan 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 adalah: "`auto`": [Default] Biarkan layanan menentukan jenis agregasi yang sesuai. "`byNewsShowcasePanel`": Gabungkan nilai berdasarkan panel News Showcase. Hal 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`, Anda tidak dapat menggabungkan berdasarkan `byNewsShowcasePanel`. "`byPage`": Gabungkan nilai berdasarkan URI. "`byProperty`": Gabungkan nilai berdasarkan properti. Tidak didukung untuk `type=discover` atau `type=googleNews`
`rowLimit`	`integer`	[Opsional; Rentang yang valid adalah 1–25.000; Default adalah 1.000] Jumlah maksimum baris yang akan ditampilkan. Untuk menelusuri hasil, gunakan offset `startRow`.
`startRow`	`integer`	[Opsional; Default adalah 0] Indeks berbasis nol dari baris pertama dalam respons. Harus berupa bilangan bulat bukan negatif. Jika `startRow` melebihi jumlah hasil untuk kueri, respons 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 diselesaikan. 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 berdasarkan dimensi HOUR API.

Respons

Hasil dikelompokkan menurut dimensi yang ditentukan dalam permintaan. Semua nilai dengan kumpulan nilai dimensi yang sama akan dikelompokkan ke dalam satu baris. Misalnya, jika Anda mengelompokkan berdasarkan 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, seluler" akan dikelompokkan, dan seterusnya. Lihat dokumentasi laporan Analisis Penelusuran untuk mempelajari spesifikasi cara klik, tayangan, dan sebagainya dihitung, serta artinya.

Hasil diurutkan berdasarkan jumlah klik, dalam urutan menurun, kecuali jika Anda mengelompokkan berdasarkan tanggal, yang dalam hal ini hasil diurutkan berdasarkan tanggal, dalam urutan menaik (terlama terlebih dahulu, terbaru terakhir). Jika ada dua baris yang memiliki jumlah klik yang sama, urutan pengurutan bersifat acak.

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
`rows[]`	`list`	Daftar baris yang dikelompokkan menurut nilai kunci dalam urutan yang diberikan dalam kueri.
`rows[].keys[]`	`list`	Daftar nilai dimensi untuk baris tersebut, dikelompokkan menurut dimensi dalam permintaan, dalam urutan yang ditentukan dalam permintaan.
`rows[].clicks`	`double`	Jumlah klik untuk baris.
`rows[].impressions`	`double`	Jumlah tayangan 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 dalam hasil penelusuran.
`responseAggregationType`	`string`	Cara hasil digabungkan.Lihatdokumentasi bantuan untuk mempelajari cara data dihitung secara berbeda menurut situs dan menurut halaman. Nilai yang dapat diterima adalah: "`auto`" "`byPage`": Hasil digabungkan berdasarkan halaman. "`byProperty`": Hasil digabungkan berdasarkan properti.
`metadata`	`object`	Objek yang dapat ditampilkan dengan hasil kueri Anda, yang memberikan konteks tentang status data. Saat Anda meminta data terbaru (menggunakan `all` atau `hourly_all` untuk `dataState`), beberapa baris yang ditampilkan mungkin mewakili data yang tidak lengkap, yang berarti data masih dikumpulkan dan diproses. Objek metadata ini membantu Anda mengidentifikasi dengan tepat kapan data ini dimulai dan berakhir. Semua tanggal dan waktu yang diberikan dalam objek ini berada di zona waktu `America/Los_Angeles`. Kolom tertentu yang ditampilkan dalam objek ini bergantung pada cara Anda mengelompokkan data dalam permintaan: `first_incomplete_date` (`string`): Tanggal pertama data masih dikumpulkan dan diproses, yang ditampilkan dalam format `YYYY-MM-DD` (format tanggal lokal diperpanjang ISO-8601). Kolom ini hanya diisi jika `dataState` permintaan adalah `all` dan data dikelompokkan menurut `date`, serta rentang tanggal yang diminta berisi titik data yang tidak lengkap. Semua nilai setelah `first_incomplete_date` mungkin masih berubah secara signifikan. `first_incomplete_hour` (`string`): Jam pertama data masih dikumpulkan dan diproses, yang ditampilkan dalam format `YYYY-MM-DDThh:mm:ss[+\|-]hh:mm` (format tanggal-waktu offset diperpanjang ISO-8601). Kolom ini hanya diisi jika `dataState` permintaan adalah `hourly_all`, dan data dikelompokkan menurut `hour` serta rentang tanggal yang diminta berisi titik data yang tidak lengkap. Semua nilai setelah `first_incomplete_hour` mungkin masih berubah secara signifikan.

Cobalah!

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