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ün içeren 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ırın tıklama sayısı aynıysa satırların sıralaması rastgele yapılır.

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

API, Search Console'un dahili sınırlamalarına tabidir ve tüm veri satırlarını değil, en üsttekileri döndürmeyi garanti etmez.

Kullanılabilir veri miktarıyla ilgili sınırlamalara bakın.

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 Mülkün Search Console'da tanımlanan 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 birinde 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 aşağıdaki yapıya sahip veriler 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ş tarihiyle aynı olmalıdır. Bu değer, aralığa dahil edilir.
endDate string [Zorunlu] İstenen tarih aralığının bitiş tarihi, YYYY-AA-GG biçiminde, PT saatinde (UTC - 7:00/8:00). Başlangıç tarihinden büyük veya başlangıç tarihiyle aynı 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 "date" (tarih) ile birlikte dilediğiniz boyut adını kullanabilirsiniz. Gruplandırma boyutu değerleri, her sonuç satırı için benzersiz bir anahtar oluşturmak üzere birleştirilir. Boyut belirtilmezse tüm değerler tek bir satırda birleştirilir. Gruplandırabileceğiniz boyut sayısıyla ilgili bir sınır yoktur ancak aynı boyutu iki kez gruplandıramazsınız. Örnek: [country, device]
searchType string Desteği sonlandırıldı, bunun yerine type kullanın
type string [İsteğe bağlı] Sonuçları aşağıdaki türe göre filtreleyin:
  • "discover": Keşfet sonuçları
  • "googleNews": news.google.com ile Android ve iOS'teki Google Haberler uygulamasından elde edilen sonuçlar. Google Arama'daki "Haberler" sekmesindeki sonuçları içermez.
  • "news": Google Arama'daki "Haberler" sekmesindeki arama sonuçları.
  • "image": Google Arama'daki "Görsel" sekmesindeki arama sonuçları.
  • "video": Video arama sonuçları
  • "web": [Varsayılan] Sonuçları Google Arama'daki birleşik ("Tümü") sekmesine göre filtreleyin. 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. Bir satırın yanıtta döndürülebilmesi 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 doğru ("ve") döndürmesi mi yoksa bir veya daha fazlasının doğru döndürmesi mi gerektiği (henüz desteklenmemektedir).

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ırla test edilecek sıfır veya daha fazla filtre. Her filtre bir boyut adı, bir operatör ve bir değerden oluşur. Maksimum uzunluk 4096 karakterdir. Ö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:
    • DESKTOP
    • 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 filtreleme. Kullanılabilir değerlerin listesini görmek için "search visibleance" grubuna göre gruplandırılmış bir sorgu çalıştırın. Değerlerin ve açıklamaların tam listesini yardım dokümanlarından da
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 ifadenize eşit olmalıdır (büyük/küçük harf 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ıdır).
  • "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şleştirilmesi gereken bir RE2 söz dizimi normal ifadesi.
  • "excludingRegex": Eşleşmemesi gereken bir RE2 söz dizimi normal ifadesi.
dimensionFilterGroups[].filters[].expression string Operatöre bağlı olarak filtrenin eşleştireceği veya hariç tutacağı değer.
aggregationType string

[İsteğe bağlı] Verilerin toplanma şekli. Mülke göre toplanırsa aynı mülkle ilgili tüm veriler toplanır; sayfaya göre toplanırsa tüm veriler standart URI'ye göre toplanır. Sayfaya göre filtreleme veya gruplandırma yapıyorsanız "otomatik"i seçin. Aksi takdirde, verilerinizin nasıl hesaplanmasını istediğinize bağlı olarak mülke veya sayfaya göre toplama yapabilirsiniz. Verilerin siteye ve sayfaya göre nasıl farklı şekilde hesaplandığını öğrenmek için yardım belgelerini inceleyin.

Not: Sayfaya göre gruplandırdığınızda veya filtrelediğinizde tesise göre toplama yapamazsınız.

Otomatik dışında bir değer belirtirseniz sonuçtaki toplama türü istenen türle eşleşir. Geçersiz bir tür isterseniz hata alırsınız. İstenen tür geçersizse API, toplama türünüzü hiçbir zaman değiştirmez.

Kabul edilen değerler şunlardır:
  • "auto": [Varsayılan] Uygun toplama türüne hizmetin karar vermesine izin verin.
  • "byNewsShowcasePanel": Değerleri Haberler'de Öne Çıkan paneline göre toplar. Bu, NEWS_SHOWCASE searchAppearance filtresiyle ve type=discover veya type=googleNews ile birlikte kullanılmalıdır. Sayfaya göre gruplandırır, sayfaya göre filtre uygular veya başka bir searchAppearance'ye göre filtre uygularsanız byNewsShowcasePanel'ye göre toplama yapamazsı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 desteklenmiyor
rowLimit integer [İsteğe bağlı; Geçerli aralık 1-25.000; Varsayılan değer 1.000] Döndürülecek maksimum satır sayısı. Sonuçlar arasında sayfalamak için startRow ofsetini kullanın.
startRow integer [İsteğe bağlı; Varsayılan değer 0] 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 harf duyarlı değildir) veriler taze verileri içerir. "final" (büyük/küçük harf duyarlı değildir) ise veya bu parametre atlanırsa döndürülen veriler yalnızca nihai verileri içerir.

Yanıt

Sonuçlar, istekte belirtilen boyutlara göre gruplandırılır. Aynı boyut değeri grubuna sahip tüm değerler tek bir satırda gruplandırılır. Örneğin, ülke boyutuna göre gruplandırma yaparsanız "usa" ile ilgili tüm sonuçlar birlikte gruplandırılır, "mdv" ile ilgili tüm sonuçlar birlikte gruplandırılır ve bu şekilde devam eder. Ülkeye ve cihaza göre gruplandırdıysanız "usa, tablet" için tüm sonuçlar, "usa, mobil" için tüm sonuçlar vb. gruplandırılır. Tıklamaların, gösterimlerin vb. nasıl hesaplanıp ne anlama geldiğiyle ilgili ayrıntılı bilgi için Arama Analizi raporu dokümanlarını inceleyin.

Sonuçlar, tarihe göre gruplandırma yapmadığınız sürece tıklama sayısına göre azalan düzende sıralanır. Aksi takdirde sonuçlar tarihe göre artan düzende (en eski önce, en yeni son) sıralanır. İki satır arasında eşitlik varsa sıralama düzeni keyfidir.

Döndürülebilecek maksimum değer sayısını öğrenmek için istekteki rowLimit mülküne 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 belirtilen 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 sayısını tıklayın.
rows[].impressions double Satırın 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 nasıl toplandığı. Verilerin siteye ve sayfaya göre nasıl farklı şekilde hesaplandığını öğrenmek için yardım dokümanlarına göz atı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.