Search Analytics: query

Wymaga autoryzacji

tworzyć zapytania dotyczące danych o ruchu w sieci wyszukiwania przy użyciu zdefiniowanych filtrów i parametrów; Metoda zwraca zero lub więcej wierszy pogrupowanych według zdefiniowanych przez Ciebie kluczy (wymiarów). Musisz określić zakres dat obejmujący co najmniej 1 dzień.

Gdy data jest jednym z wymiarów, wszystkie dni bez danych są pomijane na liście wyników. Aby dowiedzieć się, z których dni pochodzą dane, wyślij zapytanie bez filtrów pogrupowanych według daty dla danego zakresu dat.

Wyniki są posortowane malejąco według liczby kliknięć. Jeśli dwa wiersze mają taką samą liczbę kliknięć, są sortowane w dowolny sposób.

Zobacz przykład Pythona dla tej metody.

Interfejs API jest ograniczony przez wewnętrzne ograniczenia Search Console i nie gwarantuje, że zwróci wszystkie wiersze danych, ale tylko najważniejsze.

Zobacz, jakie są limity danych.

Przykład żądania POST w formacie 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"]
}

Wypróbuj teraz

Żądanie

Żądanie HTTP

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

Parametry

Nazwa parametru	Wartość	Opis
Parametry ścieżki
siteUrl	string	Adres URL usługi, zgodnie z definicją w Search Console. Przykłady: http://www.example.com/ (w przypadku usługi z prefiksem URL) lub sc-domain:example.com (w przypadku usługi domeny)

Upoważnienie

To żądanie wymaga autoryzacji z co najmniej jednym z poniższych zakresów (więcej informacji o uwierzytelnianiu i autoryzacji).

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

Treść żądania

W treści żądania podaj dane o tej strukturze:

{
  "startDate": string,
  "endDate": string,
  "dimensions": [
    string
  ],
  "type": string,
  "dimensionFilterGroups": [
    {
      "groupType": string,
      "filters": [
        {
          "dimension": string,
          "operator": string,
          "expression": string
        }
      ]
    }
  ],
  "aggregationType": string,
  "rowLimit": integer,
  "startRow": integer
}

Nazwa usługi	Wartość	Opis	Uwagi
startDate	string	[Wymagany] Data rozpoczęcia żądanego zakresu dat w formacie RRRR-MM-DD, w czasie PT (UTC–7:00/8:00). Musi być późniejsza lub równa dacie zakończenia. Ta wartość jest zawarta w zakresie.
endDate	string	[Wymagany] Data zakończenia żądanego zakresu dat w formacie RRRR-MM-DD, w czasie PT (UTC-7:00/8:00). Musi być późniejsza lub równa dacie rozpoczęcia. Ta wartość jest zawarta w zakresie.
dimensions[]	list	[Opcjonalnie] Brak wymiarów lub więcej, według których można pogrupować wyniki.Wyniki są pogrupowane według kolejności ich dodawania.W polu dimensionFilterGroups[].filters[].dimension możesz użyć dowolnej nazwy wymiaru oraz daty.Pogrupowane wartości wymiarów grupowania tworzą unikalny klucz dla każdego wiersza wyników. Jeśli nie określisz wymiarów, wszystkie wartości zostaną połączone w jednym wierszu. Nie ma ograniczeń co do liczby wymiarów, według których można grupować, ale nie można grupować dwukrotnie tego samego wymiaru. Przykład: [country, device]
searchType	string	Wycofane – zamiast tego użyj type
type	string	[Opcjonalnie] Filtruj wyniki według tych typów: „discover”: znajdź wyniki „googleNews”: wyniki z news.google.com i aplikacji Wiadomości Google na Androida i iOS. Nie obejmuje wyników z karty „Wiadomości” w wyszukiwarce Google. „news”: wyniki wyszukiwania na karcie „Wiadomości” w wyszukiwarce Google. „image”: wyniki wyszukiwania na karcie „Grafika” w wyszukiwarce Google. „video”: wyniki wyszukiwania filmów „web”: [domyślnie] filtruje wyniki na połączonej karcie „Wszystkie” w wyszukiwarce Google. Nie obejmuje wyników z Discover ani Wiadomości Google.
dimensionFilterGroups[]	list	[Opcjonalnie] 0 lub więcej grup filtrów, które można zastosować do wartości grupowania wymiarów. Aby wiersz został zwrócony w odpowiedzi, wszystkie grupy filtrów muszą być dopasowane. W ramach jednej grupy filtrów możesz określić, czy wszystkie filtry muszą być dopasowane, czy co najmniej jeden,
dimensionFilterGroups[].groupType	string	Określa, czy wszystkie filtry w tej grupie muszą zwracać wartość „prawda” (i), czy co najmniej 1 musi zwracać wartość „prawda” (jeszcze nieobsługiwany). Akceptowane wartości: „and”: wszystkie filtry w grupie muszą zwracać wartość „prawda”.
dimensionFilterGroups[].filters[]	list	[Opcjonalnie] Zero lub więcej filtrów, które możesz przetestować w wierszu. Każdy filtr składa się z nazwy wymiaru, operatora i wartości. Maksymalna długość to 4096 znaków. Przykłady: country equals FRA query contains mobile use device notContains tablet
dimensionFilterGroups[].filters[].dimension	string	Wymiar, którego dotyczy ten filtr. Możesz filtrować według dowolnego z wymienionych tutaj wymiarów, nawet wtedy, gdy nie grupujesz według tego wymiaru. Akceptowane wartości: „country”: filtruj według określonego kraju zgodnie z 3-literowym kodem kraju (ISO 3166-1 alfa-3). „device”: filtruj wyniki według określonego typu urządzenia. Obsługiwane wartości: NA KOMPUTERZE TELEFONIE TABLET „page”: filtruj według określonego ciągu identyfikatora URI. „query”: filtruj według określonego ciągu zapytania. „searchAppearance”: filtruj według konkretnej funkcji wyników wyszukiwania. Aby wyświetlić listę dostępnych wartości, uruchom zapytanie pogrupowane według parametru „searchlook”.
dimensionFilterGroups[].filters[].operator	string	[Opcjonalny] Jak podana wartość musi pasować (lub nie) do wartości wymiaru w wierszu. Akceptowane wartości: „contains”: wartość w wierszu musi zawierać lub równości wyrażenia (wielkość liter nie jest rozróżniana). „equals”: [wartość domyślna] wyrażenie musi dokładnie odpowiadać wartości wiersza (wielkość liter ma znaczenie w przypadku wymiarów strony i zapytania). „notContains”: wartość w wierszu nie może zawierać wyrażenia w postaci podłańcucha lub dopasowania przybliżonego (bez rozróżniania wielkości liter). „notEquals”: wyrażenie nie może dokładnie odpowiadać wartości w wierszu (wielkość liter ma znaczenie w przypadku wymiarów strony i zapytania). „includingRegex”: wyrażenie regularne składni RE2, które musi być dopasowane. „excludingRegex”: wyrażenie regularne składni RE2, którego nie można dopasować.
dimensionFilterGroups[].filters[].expression	string	Wartość filtra, którą chcesz dopasować lub wykluczyć, w zależności od operatora.
aggregationType	string	[Opcjonalnie] sposób agregacji danych. Jeśli dane są agregowane według usługi, są one agregowane. Jeśli dane są agregowane według strony, są one agregowane według kanonicznego identyfikatora URI. Jeśli filtrujesz lub grupujesz według strony, wybierz opcję „automatyczne”. W przeciwnym razie możesz łączyć dane według usługi lub strony w zależności od tego, jak chcesz obliczać dane. Zapoznaj się z dokumentacją pomocy, aby dowiedzieć się, jak obliczamy dane w poszczególnych witrynach. Uwaga: jeśli grupujesz lub filtrujesz według strony, nie możesz łączyć danych według usługi. Jeśli podasz wartość inną niż automatyczna, typ agregacji w wyniku będzie zgodny z żądanym typem, a jeśli poprosisz o nieprawidłowy typ, wystąpi błąd. Interfejs API nigdy nie zmienia typu agregacji, jeśli żądany typ jest nieprawidłowy. Akceptowane wartości to: „auto”: [wartość domyślna] usługa wybiera odpowiedni typ agregacji. „byPage”: zagregowane wartości według identyfikatora URI. „byProperty”: zagregowane wartości według usługi. Nieobsługiwane w przypadku type=discover i type=googleNews
rowLimit	integer	[Opcjonalny; prawidłowy zakres to 1–25 000; wartość domyślna to 1000] Maksymalna liczba wierszy do zwrócenia. Aby wyświetlić wyniki, użyj przesunięcia startRow.
startRow	integer	[Opcjonalny; wartość domyślna to 0] Indeks zerowy pierwszego wiersza w odpowiedzi. Musi być liczbą nieujemną. Jeśli startRow przekroczy liczbę wyników dla zapytania, odpowiedź będzie pomyślna i nie będzie żadnych wierszy.
dataState	string	[Opcjonalnie] Jeśli wybierzesz opcję „Wszystkie” (wielkość liter nie jest rozróżniana), dane będą zawierać świeże dane. Jeśli parametr jest typu „final” (wielkość liter nie jest rozróżniana) lub jeśli ten parametr zostanie pominięty, zwracane dane będą zawierały tylko dane ostateczne.

Odpowiedź

Wyniki są pogrupowane według wymiarów określonych w żądaniu. Wszystkie wartości z tym samym zestawem wartości wymiarów zostaną zgrupowane w jednym wierszu. Jeśli na przykład pogrupujesz według wymiaru kraj wszystkie wyniki dotyczące „USA” zostaną zgrupowane, a wyniki „mdv” – zgrupowane itd. Jeśli pogrupujesz wyniki według kraju i urządzenia, zgrupowane zostaną wszystkie wyniki dotyczące hasła „usa, tablet” i „usa, telefon komórkowy” itd. Więcej informacji o sposobie obliczania kliknięć, wyświetleń itd. i ich znaczenie znajdziesz w dokumentacji raportów Analityka wyszukiwania.

Wyniki są sortowane według liczby kliknięć w kolejności malejącej, chyba że pogrupujesz je według daty – w kolejności od najnowszych do malejącej (malejąco). Jeśli 2 wiersze są powiązane, kolejność sortowania jest dowolna.

W żądaniu znajdziesz właściwość rowLimit, która pozwala poznać maksymalną liczbę wartości, jakie można zwrócić.

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}

Nazwa usługi	Wartość	Opis	Uwagi
rows[]	list	Lista wierszy pogrupowana według par klucz-wartość w kolejności podanej w zapytaniu.
rows[].keys[]	list	Lista wartości wymiarów w tym wierszu, pogrupowanych według wymiarów w żądaniu, w kolejności określonej w żądaniu.
rows[].clicks	double	Kliknij liczbę wierszy.
rows[].impressions	double	Liczba wyświetleń wiersza.
rows[].ctr	double	Kliknij współczynnik klikalności (CTR) dla wiersza. Wartości należą do zakresu od 0 do 1, 0.
rows[].position	double	Średnia pozycja w wynikach wyszukiwania.
responseAggregationType	string	Sposób agregacji wyników.Zapoznaj się z dokumentacją pomocy, aby dowiedzieć się, jak różnią się dane w zależności od witryny i strony. Akceptowane wartości: „auto” „byPage”: wyniki zostały zagregowane według strony. „byProperty”: wyniki zostały agregowane według usługi.

Wypróbuj

Skorzystaj z eksploratora interfejsów API poniżej, aby wywołać tę metodę w aktywnych danych i zobaczyć odpowiedź.