Search Analytics: query

Yetkilendirme gerektirir

Arama trafiği verilerinizi, tanımladığınız filtre ve parametrelerle sorgulayabilirsiniz. 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ünden oluşan bir tarih aralığı tanımlamalısınız.

Tarih boyutlardan biri olduğunda, veri içermeyen günler sonuç listesinden çıkarılır. Hangi günlerde veri bulunduğunu öğrenmek üzere, ilgili tarih aralığı için tarihe göre gruplandırılmış filtreler olmadan bir sorgu gönderin.

Sonuçlar, tıklama sayısına göre büyükten küçüğe sıralanır. İki satır aynı tıklama sayısına sahipse bunlar 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ı değil, en üstteki satırları döndüreceğini garanti eder.

Kullanılabilir veri miktarına ilişkin sınırlara 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 eki mülkü için) veya sc-domain:example.com (alan mülkü için)

Yetkilendirme

Bu istek için aşağıdaki kapsamlardan en az biriyle yetkilendirme gereklidir (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 YYYY-AA-GG biçimindeki başlangıç tarihi (PT saati (UTC - 7:00/8:00)). Bitiş tarihinden önce veya bitiş tarihine eşit olmalıdır. Bu değer, aralığa dahildir.
endDate string [Zorunlu] İstenen tarih aralığının YYYY-AA-GG biçiminde, PT zaman (UTC - 7:00/8:00) bitiş tarihi. Başlangıç tarihinden sonra veya başlangıç tarihine eşit olmalıdır. Bu değer, aralığa dahildir.
dimensions[] list [İsteğe bağlı] Sonuçları gruplandırmak için sıfır veya daha fazla boyut.Sonuçlar, bu boyutları sağladığınız sıraya göre gruplandırılır.dimensionFilterGroups[].filters[].dimension özelliğinde ve "tarih"te istediğiniz boyut adını kullanabilirsiniz.Gruplandırma boyut 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ırma ölçütü olarak kullanabileceğiniz boyut sayısı için bir sınır yoktur, ancak aynı boyuta göre iki kez gruplandırma yapamazsınız. Örnek: [ülke, cihaz]
searchType string Kullanımdan kaldırıldı, bunun 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 ile birlikte Android ve iOS cihazlarda Google Haberler uygulamasından alınan sonuçlar. Google Arama'daki "Haberler" sekmesindeki sonuçları içermez.
  • "news": Google Arama'daki "Haberler" sekmesinde yer alan arama sonuçları.
  • "image": Google Arama'daki "Görsel" sekmesinden 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 hiç filtre grubu yoktur veya daha fazla filtre grubu yoktur. 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şmesi veya en az birinin eşleşmesi gerektiğini belirtebilirsiniz.
dimensionFilterGroups[].groupType string Bu gruptaki tüm filtrelerin true ("and") döndürmesi gerekip gerekmediğini ya da bir veya daha fazlasının true (doğru) döndürmesinin gerekip gerekmediği (henüz desteklenmemektedir).

Kabul edilebilir değerler şunlardır:
  • "and": Filtre grubunun doğru olabilmesi için gruptaki tüm filtrelerin true değerini döndürmesi gerekir.
dimensionFilterGroups[].filters[] list [İsteğe bağlı] Satıra göre test edilecek sıfır veya daha fazla filtre. Her filtre bir boyut adı, operatör ve bir değerden oluşur. Maksimum uzunluk 4096 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 filtreleme yapabilirsiniz (söz konusu boyuta göre gruplama yapmıyor olsanız bile).

Kabul edilebilir değerler şunlardır:
  • "country": 3 harfli ülke koduyla (ISO 3166-1 alpha-3) 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 filtreleyin.
  • "query": Belirtilen sorgu dizesine göre filtreleyin.
  • "searchAppearance": Belirli bir arama sonucu özelliğine göre filtreleme yapın. Kullanılabilir değerlerin listesini görmek için "searchLookance" etiketine 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 edilebilir değerler şunlardır:
  • "contains": Satır değeri, ifadenizi içermelidir veya ifadenize eşit olmalıdır (büyük/küçük harfe duyarlı değildir).
  • "equals": [Varsayılan] İfadeniz, satır değeriyle 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 bir 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 bir RE2 söz dizimi normal ifadesidir.
  • "excludingRegex": Eşleştirilmemesi gereken bir RE2 söz dizimi normal ifadesi.
dimensionFilterGroups[].filters[].expression string Operatöre bağlı olarak eşleştirilecek veya hariç tutulacak filtre değeri.
aggregationType string

[İsteğe bağlı] Verilerin nasıl toplandığı. Mülke göre toplanırsa aynı mülkün tüm verileri toplanır; sayfaya göre toplanırsa tüm veriler standart URI tarafından toplanır. Sayfaya göre filtreleme veya gruplama 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 dokümanlarına bakın.

Not: Sayfaya göre gruplandırma veya filtreleme yaparsanız mülke 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 mesajı 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 verilir.
  • "byNewsShowcasePanel": Değerleri Haberler'de Öne Çıkan paneline göre toplar. Bu parametre, NEWS_SHOWCASE searchAppearance filtresi ve type=discover veya type=googleNews ile birlikte kullanılmalıdır. Sayfaya göre gruplama, sayfaya göre filtreleme veya başka bir searchAppearance için filtreleme yaparsanız byNewsShowcasePanel ile toplama yapamazsınız.
  • "byPage": Değerleri URI'ye göre toplar.
  • "byProperty": Değerleri mülke göre toplar. type=discover veya type=googleNews için desteklenmez
rowLimit integer [İsteğe bağlı; Geçerli aralık 1–25.000; Varsayılan değer 1.000'dir] Döndürülecek maksimum satır sayısı. Sonuçlar arasında geçiş yapmak için startRow ofsetini kullanın.
startRow integer [İsteğe bağlı; Varsayılan 0'dır] Yanıttaki ilk satırın sıfır tabanlı dizini. Negatif olmayan bir sayı olmalıdır. startRow sorgu için 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) yeni veriler içerir. "Nihai" (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ğerleri grubuna sahip tüm değerler tek bir satırda gruplandırılır. Örneğin, ülke boyutuna göre gruplandırırsanız "abd" için tüm sonuçlar birlikte gruplandırılır, "mdv" için tüm sonuçlar birlikte gruplandırılır ve bu şekilde devam eder. Ülkeye ve cihaza göre gruplandırırsanız, "abd, tablet" için tüm sonuçlar gruplanır, "usa, mobil" için olan tüm sonuçlar gruplandırılır vb. Tıklama sayısı ve gösterim gibi öğelerin nasıl hesaplandığına ve ne anlama geldiğine dair ayrıntıları öğrenmek için Arama Analizi raporu dokümanlarına bakın.

Tarihe göre gruplandırmadığınız sürece, sonuçlar tarihe göre artan düzende (en önce en eski, en yeni olan) şekilde, tıklama sayısına göre, azalan düzende sıralanır. İki satır arasında eşitlik varsa sıralama düzeni rastgeledir.

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 belirtilen sırada anahtar değerlerine göre gruplandırılmış satır listesi.
rows[].keys[] list Söz konusu satırla ilgili boyut değerlerinin listesi (istekteki boyutlara göre, istekte belirtilen sırada).
rows[].clicks double Satır için tıklama sayısı.
rows[].impressions double Satırın gösterim sayısı.
rows[].ctr double Satır için Tıklama Oranı (TO) Değerler 0 ile 1,0 arasında (0 ve 1,0 dahil) olabilir.
rows[].position double Arama sonuçlarındaki ortalama konum.
responseAggregationType string Sonuçların nasıl toplandığı.Verilerin site ve sayfaya göre nasıl farklı şekilde hesaplandığını öğrenmek için yardım dokümanlarına bakın.

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

Deneyin.

Aşağıdaki API Gezgini'ni kullanarak canlı verilerde bu yöntemi çağırın ve yanıtı görün.