Search Analytics: query

Wymaga autoryzacji

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

Jeśli data jest jednym z wymiarów, wszystkie dni bez danych są pomijane na liście wyników. Aby dowiedzieć się, w których dniach są dostępne dane, wyślij zapytanie bez filtrów pogrupowane według daty w interesującym Cię zakresie dat.

Wyniki są sortowane według liczby kliknięć w kolejności malejącej. Jeśli 2 wiersze mają taką samą liczbę kliknięć, są sortowane w dowolnej kolejności.

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

Interfejs API jest ograniczony przez wewnętrzne ograniczenia Search Console i nie gwarantuje zwrócenia wszystkich wierszy danych, ale tylko te najważniejsze.

Zapoznaj się z limitami 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 go 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)

Autoryzacja

To żądanie wymaga autoryzacji z co najmniej jednym 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 [Wymagane] Data rozpoczęcia żądanego zakresu dat w formacie RRRR-MM-DD w strefie czasowej PT (UTC – 7:00/8:00). Musi być mniejsza lub równa dacie zakończenia. Ta wartość jest uwzględniana w zakresie.
endDate string [Wymagane] Data zakończenia żądanego zakresu dat w formacie RRRR-MM-DD w strefie czasowej PT (UTC – 7:00/8:00). Musi być większa lub równa dacie rozpoczęcia. Ta wartość jest uwzględniana w zakresie.
dimensions[] list [Opcjonalnie] Zero lub więcej wymiarów, według których mają być grupowane wyniki. Wyniki są grupowane w kolejności, w jakiej podajesz te wymiary.Możesz użyć dowolnej nazwy wymiaru w dimensionFilterGroups[].filters[].dimension, 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 ograniczeń co do 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: [country, device]
searchType string Wycofane, zamiast niego używaj parametru type
type string [Opcjonalnie] Filtruj wyniki według tego typu:
  • "discover": wyniki na kartach Discover.
  • googleNews: wyniki z news.google.com oraz z aplikacji Google News 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ślnie] filtruj wyniki do połączonej karty („Wszystko”) w wyszukiwarce Google. Nie obejmuje wyników z Discover ani Google News.
dimensionFilterGroups[] list [Opcjonalnie] Zero lub więcej grup filtrów, które mają być stosowane do wartości grupowania wymiarów. Aby w odpowiedzi został zwrócony wiersz, wszystkie grupy filtrów muszą być zgodne. W ramach jednej grupy filtrów możesz określić, czy wszystkie filtry muszą być zgodne, czy tylko co najmniej 1.
dimensionFilterGroups[].groupType string Czy wszystkie filtry w tej grupie muszą zwracać wartość true („and”), czy co najmniej 1 musi zwracać wartość true (nie jest jeszcze obsługiwane).

Akceptowane wartości:
  • "and": Aby grupa filtrów była zgodna, wszystkie filtry w grupie muszą zwracać wartość true.
dimensionFilterGroups[].filters[] list [Opcjonalnie] Zero lub więcej filtrów, które mają być testowane 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 ma zastosowanie ten filtr. Możesz filtrować według dowolnego wymiaru wymienionego tutaj, nawet jeśli 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 alpha-3).
  • "device": filtruj wyniki według określonego typu urządzenia. Obsługiwane wartości:
    • DESKTOP
    • MOBILE
    • TABLET
  • "page": filtruj według określonego ciągu 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 „searchAppearance”. Pełna lista wartości i opisów jest też dostępna w dokumentacji pomocy.
dimensionFilterGroups[].filters[].operator string [Opcjonalnie] Jak określona wartość musi pasować (lub nie pasować) do wartości wymiaru w wierszu.

Akceptowane wartości:
dimensionFilterGroups[].filters[].expression string Wartość, która ma być dopasowana lub wykluczona przez filtr, w zależności od operatora.
aggregationType string

[Opcjonalnie] Jak dane są agregowane. 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 adresu URI . Jeśli filtrujesz lub grupujesz według strony, wybierz opcję auto. W przeciwnym razie możesz agregować według usługi lub według strony, w zależności od tego, jak chcesz obliczać dane. Więcej informacji o tym, jak dane są obliczane inaczej według witryny niż według strony, znajdziesz w dokumentacji 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 poprosisz o nieprawidłowy typ, otrzymasz błąd. Interfejs API nigdy nie zmieni typu agregacji, jeśli żądany typ jest nieprawidłowy.

Akceptowane wartości:
  • "auto": [Domyślnie] usługa decyduje o odpowiednim typie agregacji.
  • "byNewsShowcasePanel": agreguj wartości według panelu Showcase w Wiadomościach. Tej opcji należy używać w połączeniu z filtrem NEWS_SHOWCASE searchAppearance oraz z 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 adresu URI.
  • "byProperty": agreguj wartości według usługi. Nieobsługiwane w przypadku type=discover ani type=googleNews
rowLimit integer [Opcjonalnie; prawidłowy zakres to 1–25 000; domyślna wartość to 1000] Maksymalna liczba wierszy do zwrócenia. Aby podzielić wyniki na strony, użyj przesunięcia startRow.
startRow integer [Opcjonalnie; domyślna wartość to 0] Indeks pierwszego wiersza w odpowiedzi (liczony od zera). Nie może być liczbą ujemną. Jeśli startRow przekracza liczbę wyników zapytania, odpowiedź będzie zawierać 0 wierszy.
dataState string [Opcjonalnie] Jeśli podasz "all" (bez uwzględniania wielkości liter), dane będą zawierać najnowsze dane. Jeśli podasz „final” (bez uwzględniania wielkości liter) lub pominiesz ten parametr, zwrócone dane będą zawierać tylko dane ostateczne. Jeśli podasz „hourly_all” (bez uwzględniania wielkości liter), dane będą zawierać zestawienie godzinowe. Wskazuje to, że dane godzinowe zawierają dane częściowe i należy ich używać podczas grupowania według wymiaru GODZINA w interfejsie API.

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

Wyniki są sortowane według liczby kliknięć w kolejności malejącej, chyba że grupujesz 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 mają taką samą wartość, 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 dla tego wiersza, pogrupowanych 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 pochodzą z zakresu od 0 do 1, 0.
rows[].position double Średnia pozycja w wynikach wyszukiwania.
responseAggregationType string Jak wyniki zostały zagregowane.Więcej informacji o tym, jak dane są obliczane inaczej według witryny niż według 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 zostać zwrócony z wynikami zapytania i zawierać informacje o stanie danych.

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

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

Konkretne pole zwrócone w tym obiekcie zależy od tego, jak dane zostały pogrupowane w żądaniu:

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

    To pole jest wypełniane tylko wtedy, gdy dataState w żądaniu ma wartość 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, dla której dane są nadal zbierane i przetwarzane, 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 dataState w żądaniu ma wartość hourly_all, dane są pogrupowane według hour, a żądany zakres dat zawiera niepełne punkty danych.

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

Wypróbuj

Aby wywołać tę metodę na podstawie danych na żywo i zobaczyć odpowiedź, użyj Eksploratora interfejsów API poniżej.