Search Analytics: query

Wymaga autoryzacji

Wysyłaj zapytania dotyczące danych o ruchu z wyszukiwarki za pomocą zdefiniowanych przez siebie filtrów i parametrów. Metoda zwraca 0 lub więcej wierszy zgrupowanych według zdefiniowanych przez Ciebie kluczy wierszy (wymiarów). Musisz określić zakres dat obejmujący co najmniej 1 dzień.

Jeśli jednym z wymiarów jest data, z listy wyników są pomijane wszystkie dni, w przypadku których nie ma danych. Aby dowiedzieć się, w które dni są dostępne dane, wyślij zapytanie bez filtrów pogrupowane według daty dla interesującego Cię zakresu dat.

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

Aby dowiedzieć się, jak wywołać tę metodę, zapoznaj się z przykładowym kodem w Pythonie.

Interfejs API podlega wewnętrznym ograniczeniom Search Console i nie gwarantuje zwracania wszystkich wierszy danych, a jedynie te najważniejsze.

Zobacz ograniczenia dotyczące ilości dostępnych 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 adresu URL) lub sc-domain:example.com (w przypadku usługi domeny)

Autoryzacja

To żądanie wymaga autoryzacji z użyciem co najmniej jednego z tych 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

Dane w treści żądania muszą mieć poniższy format:

{
  "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ć wcześniejsza lub równa dacie zakończenia. Ta wartość jest uwzględniona w zakresie.
endDate string [Wymagane] Data zakończenia żądanego zakresu dat w formacie RRRR-MM-DD, podana zgodnie ze strefą czasową PT (UTC-7:00/8:00). Musi być równa dacie rozpoczęcia lub od niej późniejsza. Ta wartość jest uwzględniona w zakresie.
dimensions[] list [Opcjonalnie] Co najmniej 1 wymiar, według którego mają być grupowane wyniki.Wyniki są grupowane w kolejności, w jakiej podasz te wymiary. W dimensionFilterGroups[].filters[].dimension możesz użyć dowolnej nazwy wymiaru, a także „date” i „hour”. Wartości wymiaru grupowania są łączone w celu utworzenia unikalnego klucza dla każdego wiersza wyników. Jeśli nie podasz żadnych wymiarów, wszystkie wartości zostaną połączone w jeden wiersz. Nie ma limitu liczby wymiarów, według których możesz grupować dane, ale nie możesz grupować według tego samego wymiaru 2 razy. Przykład: [kraj, urządzenie]
searchType string Wycofana, zamiast niej używaj type
type string [Opcjonalnie] Filtruj wyniki według tego typu:
  • „discover”: wyniki z Discover.
  • „googleNews”: wyniki z news.google.com oraz z aplikacji Wiadomości Google na Androida i iOS. Nie obejmuje wyników z karty „Wiadomości” w wyszukiwarce Google.
  • „news”: wyniki wyszukiwania z karty „Wiadomości” w wyszukiwarce Google.
  • „image”: wyniki wyszukiwania z karty „Grafika” w wyszukiwarce Google.
  • „video”: wyniki wyszukiwania filmów
  • „web”: [Domyślny] Filtruj wyniki na karcie łączonej („Wszystko”) w wyszukiwarce Google. Nie obejmuje wyników z Discover ani Wiadomości Google.
dimensionFilterGroups[] list [Opcjonalnie] Zero lub więcej grup filtrów do zastosowania do wartości grupowania wymiarów. Aby wiersz został zwrócony w odpowiedzi, wszystkie grupy filtrów muszą być zgodne. W ramach jednej grupy filtrów możesz określić, czy wszystkie filtry muszą pasować, czy wystarczy, że pasuje co najmniej jeden.
dimensionFilterGroups[].groupType string Czy wszystkie filtry w tej grupie muszą zwracać wartość „prawda” („and”), czy co najmniej 1 filtr musi zwracać wartość „prawda” (ta opcja nie jest jeszcze obsługiwana).

Akceptowane wartości:
  • „and”: aby grupa filtrów była prawdziwa, wszystkie filtry w grupie muszą zwracać wartość „prawda”.
dimensionFilterGroups[].filters[] list [Opcjonalnie] Co najmniej 1 filtr do przetestowania 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, do którego odnosi się ten filtr. Możesz filtrować dane według dowolnego z wymienionych tu wymiarów, nawet jeśli nie grupujesz według niego danych.

Akceptowane wartości:
  • „country”: filtruj według określonego kraju, zgodnie z 3-literowym kodem kraju (ISO 3166-1 alfa-3).
  • „device”: filtrowanie wyników według określonego typu urządzenia. Obsługiwane wartości:
    • DESKTOP
    • URZĄDZENIA MOBILNE
    • TABLET
  • „page”: filtruj według podanego ciągu znaków URI.
  • „query”: filtruj według określonego ciągu zapytania.
  • „searchAppearance”: filtrowanie według konkretnej funkcji wyników wyszukiwania. Aby wyświetlić listę dostępnych wartości, uruchom zapytanie pogrupowane według parametru „searchAppearance”. Pełna lista wartości i ich opisów jest też dostępna w dokumentacji pomocy.
dimensionFilterGroups[].filters[].operator string [Opcjonalnie] Określa, czy podana wartość musi być zgodna z wartością wymiaru w wierszu.

Akceptowane wartości:
  • „contains”: wartość wiersza musi zawierać lub być równa wyrażeniu (bez uwzględniania wielkości liter).
  • „equals”: [Domyślne] Wyrażenie musi być dokładnie równe wartości wiersza (w przypadku wymiarów strony i zapytania rozróżniana jest wielkość liter).
  • „notContains”: wartość wiersza nie może zawierać wyrażenia jako podciągu ani jako pełnego dopasowania (bez uwzględniania wielkości liter).
  • „notEquals”: wyrażenie nie może być dokładnie równe wartości wiersza (w przypadku wymiarów strony i zapytania rozróżniana jest wielkość liter).
  • „includingRegex”: wyrażenie regularne w składni RE2, które musi zostać dopasowane.
  • „excludingRegex”: wyrażenie regularne w składni RE2, które nie może być dopasowane.
dimensionFilterGroups[].filters[].expression string Wartość filtra, która ma być dopasowana lub wykluczona w zależności od operatora.
aggregationType string

[Opcjonalnie] Sposób agregowania danych. Jeśli dane są agregowane według usługi, wszystkie dane dotyczące tej samej usługi są agregowane. Jeśli dane są agregowane według strony, wszystkie dane są agregowane według kanonicznego URI. Jeśli filtrujesz lub grupujesz według strony, wybierz opcję automatyczną. W przeciwnym razie możesz agregować dane według usługi lub strony w zależności od tego, jak chcesz je obliczać. Aby dowiedzieć się, jak dane są obliczane w przypadku witryny i strony, zapoznaj się z dokumentacją pomocy.

Uwaga: jeśli grupujesz lub filtrujesz według strony, nie możesz agregować według usługi.

Jeśli podasz inną wartość niż auto, typ agregacji w wyniku będzie zgodny z żądanym typem. Jeśli zażądasz nieprawidłowego typu, otrzymasz błąd. Interfejs API nigdy nie zmieni typu agregacji, jeśli żądany typ jest nieprawidłowy.

Akceptowane wartości:
  • „auto”: [Domyślny] Pozwól usłudze zdecydować o odpowiednim typie agregacji.
  • „byNewsShowcasePanel”: agreguj wartości według panelu Showcase w Wiadomościach. Musisz go używać w połączeniu z filtrem NEWS_SHOWCASE searchAppearance i właściwością type=discover lub type=googleNews. Jeśli grupujesz według strony, filtrujesz według strony lub filtrujesz według innego searchAppearance, nie możesz agregować według byNewsShowcasePanel.
  • „byPage”: agreguj wartości według identyfikatora URI.
  • „byProperty”: agreguj wartości według usługi. Nieobsługiwane w przypadku type=discover i type=googleNews
rowLimit integer [Opcjonalnie; prawidłowy zakres to 1–25 000; wartość domyślna to 1000] Maksymalna liczba wierszy do zwrócenia. Aby przeglądać wyniki, użyj przesunięcia startRow.
startRow integer [Opcjonalnie; domyślnie 0] Indeks pierwszego wiersza w odpowiedzi liczony od zera. Musi to być liczba nieujemna. Jeśli wartość startRow przekracza liczbę wyników zapytania, odpowiedź będzie pomyślna i nie będzie zawierać wierszy.
dataState string [Opcjonalnie] Jeśli wartość to „all” (bez rozróżniania wielkości liter), dane będą zawierać najnowsze dane. Jeśli wartość to „final” (bez rozróżniania wielkości liter) lub jeśli ten parametr zostanie pominięty, zwrócone dane będą zawierać tylko dane ostateczne. Jeśli wartość to „hourly_all” (wielkość liter nie jest rozróżniana), dane będą zawierać zestawienie godzinowe. Wskazuje ona, że dane godzinowe obejmują dane częściowe i należy jej używać podczas grupowania według wymiaru interfejsu API HOUR.

Odpowiedź

Wyniki są grupowane 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 wyniki według wymiaru „Kraj”, wszystkie wyniki dla „usa” zostaną zgrupowane razem, wszystkie wyniki dla „mdv” zostaną zgrupowane razem itd. Jeśli zgrupujesz dane według kraju i urządzenia, wszystkie wyniki dla „usa, tablet” zostaną zgrupowane, wszystkie wyniki dla „usa, telefon” zostaną zgrupowane itd. Więcej informacji o tym, jak obliczane są kliknięcia, wyświetlenia itp. oraz co oznaczają, znajdziesz w dokumentacji raportu Analityka wyszukiwania.

Wyniki są sortowane według liczby kliknięć w kolejności malejącej, chyba że grupujesz je według daty. W takim przypadku wyniki są sortowane według daty w kolejności rosnącej (od najstarszych do najnowszych). Jeśli 2 wiersze są sobie równorzędne, kolejność sortowania jest dowolna.

Maksymalną liczbę wartości, które można zwrócić, znajdziesz we właściwości rowLimit w żądaniu.

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
Nazwa usługi Wartość Opis Uwagi
rows[] list Lista wierszy pogrupowanych według wartości kluczy w kolejności podanej w zapytaniu.
rows[].keys[] list Lista wartości wymiarów w tym wierszu, zgrupowanych według wymiarów w żądaniu, w kolejności określonej w żądaniu.
rows[].clicks double Liczba kliknięć w wierszu.
rows[].impressions double Liczba wyświetleń w wierszu.
rows[].ctr double Współczynnik klikalności (CTR) w wierszu. Wartości mieszczą się w zakresie od 0 do 1, 0 włącznie.
rows[].position double Średnia pozycja w wynikach wyszukiwania.
responseAggregationType string Sposób agregacji wyników. Więcej informacji o tym, jak dane są obliczane w przypadku witryny i strony, znajdziesz w dokumentacji pomocy.

Akceptowane wartości:
  • „auto”
  • „byPage”: wyniki zostały zagregowane według strony.
  • „byProperty”: wyniki zostały zagregowane według usługi.
metadata object

Obiekt, który może być zwracany z wynikami zapytania i zawierać kontekst dotyczący stanu danych.

Gdy poprosisz o najnowsze dane (używając all lub hourly_all w przypadku dataState), niektóre zwrócone wiersze mogą zawierać niepełne dane, co oznacza, że dane są nadal zbierane i przetwarzane. Ten obiekt metadanych pomaga dokładnie określić, kiedy się zaczyna i kończy.

Wszystkie daty i godziny podane w tym obiekcie są w strefie czasowej America/Los_Angeles.

Konkretne pole zwrócone w tym obiekcie zależy od sposobu grupowania danych w żądaniu:

  • first_incomplete_date (string): pierwsza data, dla której dane są nadal zbierane i przetwarzane, podana w formacie YYYY-MM-DD (rozszerzony format daty lokalnej ISO 8601).

    To pole jest wypełniane tylko wtedy, gdy wartość dataState w żądaniu to all i dane są pogrupowane według date, a żądany zakres dat zawiera niepełne punkty danych.

    Wszystkie wartości po first_incomplete_date mogą się jeszcze znacznie zmienić.

  • first_incomplete_hour (string): pierwsza godzina, w której dane są nadal zbierane i przetwarzane, podana w formacie YYYY-MM-DDThh:mm:ss[+|-]hh:mm (rozszerzony format daty i godziny z przesunięciem ISO 8601).

    To pole jest wypełniane tylko wtedy, gdy wartość parametru dataState w żądaniu to hourly_all, dane są pogrupowane według parametru hour, a żądany zakres dat zawiera niepełne punkty danych.

    Wszystkie wartości po first_incomplete_hour mogą się jeszcze znacznie zmienić.

Wypróbuj

Użyj narzędzia APIs Explorer poniżej, aby wywołać tę metodę na danych na żywo i zobaczyć odpowiedź.