Search Analytics: query

Yetkilendirme gerektiriyor

Tanımladığınız filtreler ve parametrelerle arama trafiği verilerinizi sorgulayın. Yöntem, tanımladığınız satır anahtarlarına (boyutlar) göre gruplandırılmış sıfır veya daha fazla satır döndürür. Bir veya daha fazla günlük bir tarih aralığı tanımlamanız gerekir.

Boyutlardan biri tarih olduğunda, veri içermeyen günler sonuç listesinden çıkarılır. Hangi günlerde veri olduğunu öğrenmek istiyorsanız ilgili tarih aralığına göre tarihe göre gruplandırılmış filtreler olmadan bir sorgu oluşturun.

Sonuçlar tıklama sayısına göre azalan düzende sıralanır. İki satırda tıklama sayısı aynıysa bu satırlar rastgele bir şekilde sıralanır.

Bu yöntemi çağırmak için python örneğine bakın.

API, Search Console'un dahili sınırlamalarıyla sınırlıdır ve tüm veri satırlarının değil, en üsttekilerin döndürüleceğini garanti etmez.

Kullanılabilir veri miktarına ilişkin sınırları inceleyin.

JSON POST Örneği: 
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"]
}
Şimdi deneyin.

İstek

HTTP isteği

POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query

Parametreler

Parametre adı Değer Açıklama
Yol parametreleri
siteUrl string Search Console'da tanımlandığı şekliyle mülkün URL'si. Örnekler: http://www.example.com/ (URL ön ek mülkü için) veya sc-domain:example.com (alan mülkü için)

Yetkilendirme

Bu istek, aşağıdaki kapsamlardan en az biriyle yetkilendirme gerektirir (kimlik doğrulama ve yetkilendirme hakkında daha fazla bilgi edinin).

Kapsam
https://www.googleapis.com/auth/webmasters.readonly
https://www.googleapis.com/auth/webmasters

İstek içeriği

İstek gövdesinde, verileri aşağıdaki yapıyla sağlayın:

{
  "startDate": string,
  "endDate": string,
  "dimensions": [
    string
  ],
  "type": string,
  "dimensionFilterGroups": [
    {
      "groupType": string,
      "filters": [
        {
          "dimension": string,
          "operator": string,
          "expression": string
        }
      ]
    }
  ],
  "aggregationType": string,
  "rowLimit": integer,
  "startRow": integer
}
Mülk adı Değer Açıklama Notlar
startDate string [Zorunlu] İstenen tarih aralığının PT saati (UTC - 7:00/8:00) biçiminde, YYYY-AA-GG biçiminde başlangıç tarihi. Bitiş tarihinden sonra veya bitiş tarihine eşit olmalıdır. Bu değer, aralığa dahil edilir.
endDate string [Zorunlu] İstenen tarih aralığının YYYY-AA-GG biçiminde, PT saatiyle (UTC - 7:00/8:00) bitiş tarihi. Başlangıç tarihinden sonra veya bu tarihe eşit olmalıdır. Bu değer, aralığa dahil edilir.
dimensions[] list [İsteğe bağlı] Sonuçların gruplandırılacağı sıfır veya daha fazla boyut.Sonuçlar, bu boyutları sağladığınız sırayla gruplandırılır.dimensionFilterGroups[].filters[].dimension içinde ve "tarih"te herhangi bir boyut adı kullanabilirsiniz.Gruplandırma boyut değerleri, her sonuç satırı için benzersiz bir anahtar oluşturmak amacıyla birleştirilir. Boyut belirtilmezse tüm değerler tek bir satırda birleştirilir. Gruplandırabileceğiniz boyut sayısında sınırlama yoktur, ancak aynı boyuta göre iki kez gruplandırma yapamazsınız. Örnek: [ülke, cihaz]
searchType string Kullanımdan kaldırıldı, onun yerine type kullanın
type string [İsteğe bağlı] Sonuçları aşağıdaki türe göre filtreleyin:
  • "discover": Sonuçları keşfedin
  • "googleNews": news.google.com adresinden ve Google Haberler uygulamasından sonuçlar: Android ve iOS. "Haberler"e ait sonuçları içermez sekmesinden erişebilirsiniz.
  • "news": "Haberler"den arama sonuçları sekmesinden erişebilirsiniz.
  • "image": "Resim"den arama sonuçları sekmesinden erişebilirsiniz.
  • "video": Video arama sonuçları
  • "web": [Varsayılan] Sonuçları şuradaki birleştirilmiş ("Tümü") sekmesine göre filtreleyin: Google Arama Keşfet veya Google Haberler sonuçlarını içermez.
dimensionFilterGroups[] list [İsteğe bağlı] Boyut gruplandırma değerlerine uygulanacak sıfır veya daha fazla filtre grubu. Yanıtta bir satırın döndürülmesi için tüm filtre gruplarının eşleşmesi gerekir. Tek bir filtre grubunda, tüm filtrelerin eşleşmesinin mi yoksa en az birinin eşleşmesinin mi gerektiğini belirtebilirsiniz.
dimensionFilterGroups[].groupType string Bu gruptaki tüm filtrelerin true ("ve") döndürmesi gerekip gerekmediğini veya bir veya daha fazlasının true (doğru) değerini döndürmesinin gerekip gerekmediği (henüz desteklenmiyor).

Kabul edilen değerler şunlardır:
  • "and": O o doğru filtre grubu için, gruptaki tüm filtreler doğru değerini döndürmelidir.
dimensionFilterGroups[].filters[] list [İsteğe bağlı] Satırda test edilecek sıfır veya daha fazla filtre. Her filtre şunlardan oluşur: boyut adı, operatör ve değer. Maks. uzunluk 4.096 karakter. Örnekler: 
country equals FRA
query contains mobile use
device notContains tablet
.
dimensionFilterGroups[].filters[].dimension string Bu filtrenin geçerli olduğu boyut. Burada listelenen herhangi bir boyuta göre gruplama yapmıyor olsanız bile, söz konusu boyuta göre filtreleme yapabilirsiniz.

Kabul edilen değerler şunlardır:
  • "country": 3 harfli ülke kodu (ISO 3166-1 alpha-3) ile belirtilen ülkeye göre filtreleyin.
  • "device": Sonuçları belirtilen cihaz türüne göre filtreleyin. Desteklenen değerler:
    • MASAÜSTÜ
    • MOBİL
    • TABLET
  • "page": Belirtilen URI dizesine göre filtreleme yapın.
  • "query": Belirtilen sorgu dizesine göre filtreleyin.
  • "searchAppearance": Belirli bir arama sonucu özelliğine göre filtreleyin. Kullanılabilir değerlerin listesini görmek için "searchViewance" ölçütüne göre gruplandırılmış bir sorgu çalıştırın.
dimensionFilterGroups[].filters[].operator string [İsteğe bağlı] Belirttiğiniz değerin, satırın boyut değeriyle nasıl eşleşmesi (veya eşleşmemesi) gerektiği.

Kabul edilen değerler şunlardır:
  • "contains": Satır değeri, ifadenizi içermeli veya ona eşit olmalıdır (büyük/küçük harfe duyarlı değildir).
  • "equals": [Varsayılan] İfadeniz, satır değerine tam olarak eşit olmalıdır (sayfa ve sorgu boyutları için büyük/küçük harfe duyarlı).
  • "notContains": Satır değeri, ifadenizi alt dize veya (büyük/küçük harfe duyarlı olmayan) tam eşleşme olarak içermemelidir.
  • "notEquals": İfadeniz, satır değeriyle tam olarak eşit olmamalıdır (sayfa ve sorgu boyutları için büyük/küçük harfe duyarlı).
  • "includingRegex": Eşlenmesi gereken RE2 söz dizimi normal ifadesi.
  • "excludingRegex": Eşleşmemesi gereken RE2 söz dizimi normal ifadesi.
dimensionFilterGroups[].filters[].expression string Operatöre bağlı olarak filtrenin eşleştirileceği veya hariç tutulacağı değer.
aggregationType string

[İsteğe bağlı] Verilerin toplanma şekli. Mülke göre toplanırsa, şu sayfaya ait tüm veriler: aynı mülk toplanır; sayfa bazında toplandığında tüm veriler standart URI. Filtre veya sayfaya göre gruplandırıyorsanız otomatik'i seçin. aksi takdirde, verilerin nasıl hesaplanmasını istediğinize bağlı olarak mülke veya sayfaya göre bkz. yardım belgelerini (verilerin siteye ve sayfaya göre nasıl farklı hesaplandığını öğrenin).

Not: Sayfaya göre gruplandırır veya filtrelerseniz mülke göre toplama yapamazsınız.

Herhangi bir değeri otomatik dışında bir değerse sonuçtaki toplama türü, istenen türle eşleşir veya Geçersiz bir tür isteğinde bulunursanız hata alırsınız. İstenen tür geçersizse API, toplama türünüzü hiçbir zaman değiştirmez.

Kabul edilebilir değerler şunlardır:
  • "auto": [Varsayılan] Uygun toplama türüne hizmetin karar vermesine izin verin.
  • "byNewsShowcasePanel": Değerleri toplama ölçütü Haberler'de Öne Çıkan paneli. Bu, NEWS_SHOWCASE searchAppearance ile birlikte kullanılmalıdır filtreleyip type=discover veya type=googleNews'yi seçin. Sayfaya göre gruplandırır, sayfaya göre filtreler ya da başka bir searchAppearance için filtreleme yaparsanız byNewsShowcasePanel tarihine kadar toplayamazsınız.
  • "byPage": Değerleri URI'ye göre toplayın.
  • "byProperty": Değerleri mülke göre toplayın. type=discover veya type=googleNews için desteklenmez
rowLimit integer [İsteğe bağlı; Geçerli aralık 1–25.000'dir; Varsayılan değer 1.000'dir.] Döndürülecek maksimum satır sayısı. Sonuçların sayfaları arasında gezinmek için startRow ofsetini kullanın.
startRow integer [İsteğe bağlı; Varsayılan değer 0'dır] Yanıttaki ilk satırın sıfır tabanlı dizini. Negatif olmayan bir sayı olmalıdır. startRow, sorgunun sonuç sayısını aşarsa yanıt sıfır satırlı başarılı bir yanıt olur.
dataState string [İsteğe bağlı] "Tümü" ise (büyük/küçük harfe duyarlı değil), veriler güncel veriler. "Nihai" ise (büyük/küçük harfe duyarlı değil) veya bu parametre atlanırsa döndürülen veriler yalnızca kesinleşmiş verileri içerir.

Yanıt

Sonuçlar, istekte belirtilen boyutlara göre gruplandırılır. Aynı boyut değerine sahip tüm değerler tek bir satırda gruplandırılır. Örneğin, ülke boyutuna göre gruplandırma yaparsanız "abd" için tüm sonuçlar olarak gruplandırılır, "mdv" için tüm sonuçlar bir arada gruplandırılır vb. Ülke ve cihaza göre gruplandırırsanız "abd, tablet" için tüm sonuçlar gruplanacak, "abd, mobil" için tüm sonuçlar gruplandırılır ve bu şekilde devam eder. Tıklama sayısı, gösterim sayısı ve benzeri verilerin nasıl hesaplandığı ve bunların ne anlama geldiği hakkında ayrıntılı bilgi edinmek için Arama Analizi raporu dokümanlarına göz atın.

Tarihe göre gruplandırma yapmadığınız sürece, sonuçlar tıklama sayısına göre azalan düzende sıralanır. Tarihe göre sonuçlar, artan düzende (en eskiden yeniye, sondan başlayarak) sıralanır. İki satır arasında eşitlik varsa sıralama ölçütü rastgele belirlenir.

Döndürülebilecek maksimum değer sayısını öğrenmek için istekteki rowLimit özelliğine bakın.

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
Mülk adı Değer Açıklama Notlar
rows[] list Sorguda verilen sırada anahtar değerlerine göre gruplandırılmış satırların listesi.
rows[].keys[] list İstekteki boyutlara göre gruplandırılmış ve istekte belirtilen sırayla, ilgili satır için boyut değerlerinin listesi.
rows[].clicks double Satırın tıklama sayısı.
rows[].impressions double Satıra ilişkin gösterim sayısı.
rows[].ctr double Satırın tıklama oranı (TO). Değerler, 0 ile 1,0 dahil olmak üzere bu değerler arasında değişir.
rows[].position double Arama sonuçlarındaki ortalama konum.
responseAggregationType string Sonuçların toplanma şekli.Verilerin siteye ve sayfaya göre nasıl farklı şekilde hesaplandığını öğrenmek için yardım dokümanlarına bakın.

Kabul edilen değerler şunlardır:
  • "auto"
  • "byPage": Sonuçlar sayfaya göre toplanmıştır.
  • "byProperty": Sonuçlar mülke göre toplanmıştır.

Deneyin!

Canlı verilerde bu yöntemi çağırmak ve yanıtı görmek için aşağıdaki API Gezgini'ni kullanın.