Search Analytics: query

Wymaga autoryzacji

Wyszukiwanie danych dotyczących ruchu w sieci wyszukiwania za pomocą zdefiniowanych przez Ciebie filtrów i parametrów. Zwraca ona 0 lub więcej wierszy zgrupowanych według zdefiniowanych przez Ciebie kluczy wierszy (wymiarów). Musisz zdefiniować zakres dat obejmujący co najmniej jeden dzień.

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

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

Zapoznaj się z przykładem języka Python na temat wywoływania tej metody.

Interfejs API jest ograniczony wewnętrznymi ograniczeniami Search Console i nie gwarantuje, że zwróci on wszystkie wiersze danych, a nie tylko te z góry.

Zobacz limity ilości dostępnych danych

Przykład żądania POST 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

Prośba

Żą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 określony w Search Console. Przykłady: http://www.example.com/ (usługa z prefiksem URL) lub sc-domain:example.com (usługa domeny).

Upoważnienie

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

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

Treść żądania

Dane w treści żądania podaj w następującej 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	Notatki
startDate	string	[Wymagany] Data rozpoczęcia wybranego zakresu dat w formacie RRRR-MM-DD w czasie PT (UTC – 7:00/8:00). Nie może być późniejsza niż data zakończenia. Ta wartość jest uwzględniona w zakresie.
endDate	string	[Wymagane] Data zakończenia żądanego zakresu dat podana w formacie RRRR-MM-DD w czasie PT (UTC – 7:00/8:00). Musi być późniejsza niż data rozpoczęcia lub jej równa. Ta wartość jest uwzględniona w zakresie.
dimensions[]	list	[Opcjonalnie] Brak lub więcej wymiarów, według których można grupować wyniki.Wyniki są grupowane w kolejności, w jakiej zostały podane te wymiary.W polu dimensionFilterGroups[].filters[].dimension możesz użyć dowolnej nazwy wymiaru oraz daty.Po połączeniu wartości wymiarów grupowania tworzy to unikalny klucz dla każdego wiersza wyników. Jeśli nie podasz żadnych wymiarów, wszystkie wartości zostaną połączone w 1 wiersz. Możesz grupować według nieograniczonej liczby wymiarów, ale nie możesz grupować według tego samego wymiaru dwukrotnie. Przykład: [kraj, urządzenie]
searchType	string	Wycofano, zamiast niego użyj: type
type	string	[Opcjonalnie] Przefiltruj wyniki do tego typu: „discover”: wyniki na kartach Discover „googleNews”: wyniki z news.google.com i aplikacji Wiadomości Google na Androida i iOS. Nie uwzględnia wyników z karty „Wiadomości” w wyszukiwarce Google. „news”: wyniki wyszukiwania na karcie „Wiadomości” w wyszukiwarce Google. „image”: wyniki wyszukiwania na karcie „Obraz” w wyszukiwarce Google. „video”: wyniki wyszukiwania filmów „web”: [wartość domyślna] filtruj wyniki w wyszukiwarce Google, aby wyświetlać je na połączonej karcie („Wszystkie”). Nie uwzględnia wyników na kartach Discover ani w Wiadomościach Google.
dimensionFilterGroups[]	list	[Opcjonalnie] Brak lub więcej grup filtrów, które można zastosować 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 spełnione muszą być wszystkie filtry, czy przynajmniej jeden.
dimensionFilterGroups[].groupType	string	Określa, czy wszystkie filtry w tej grupie muszą zwracać wartość „prawda” („i”) czy też co najmniej 1 z nich musi zwracać wartość „prawda” (jeszcze nieobsługiwana). Akceptowane wartości to: „and”: wszystkie filtry w grupie muszą zwracać wartość „prawda” dla grupy filtrów, to wartość „prawda”.
dimensionFilterGroups[].filters[]	list	[Opcjonalnie] 0 lub więcej filtrów do sprawdzenia względem wiersza. Każdy filtr składa się z nazwy wymiaru, operatora i wartości. Maksymalna długość 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 z wymienionych tutaj wymiarów, nawet jeśli nie grupujesz według tego wymiaru. Akceptowane wartości to: „country”: filtruj według określonego kraju określonego za pomocą 3-literowego kodu kraju (ISO 3166-1 alfa-3). „device”: filtruj wyniki według określonego typu urządzenia. Obsługiwane wartości: KOMPUTER URZĄDZENIE MOBILNE TABLET „page”: filtruj według określonego ciągu URI. „query”: filtruj według określonego ciągu zapytania. „searchAppearance”: umożliwia filtrowanie według określonej funkcji wyniku wyszukiwania. Aby wyświetlić listę dostępnych wartości, uruchom zapytanie pogrupowane według parametru „searchAppearance”.
dimensionFilterGroups[].filters[].operator	string	[Opcjonalnie] Sposób, w jaki określona wartość musi odpowiadać wartości wymiaru w wierszu (lub od niego różnić się). Akceptowane wartości to: „contains”: wartość wiersza musi zawierać wyrażenie lub być równe (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ść wiersza nie może zawierać wyrażenia ani jako podłańcucha, ani jako pełnego dopasowania (wielkość liter nie jest rozróżniana). „notEquals”: wyrażenie nie może dokładnie odpowiadać wartości wiersza (wielkość liter ma znaczenie w przypadku wymiarów strony i zapytania). „includingRegex”: wyrażenie regularne w składni RE2, które musi być dopasowane. „excludingRegex”: wyrażenie regularne w składni RE2, którego nie można dopasować.
dimensionFilterGroups[].filters[].expression	string	Wartość filtra do dopasowania lub wykluczenia w zależności od operatora.
aggregationType	string	[Opcjonalnie] Sposób agregacji danych. Jeśli są agregowane według usługi, wszystkie dane z tej samej usługi są agregowane według strony. Jeśli są agregowane według strony, są agregowane według kanonicznego identyfikatora URI. Jeśli filtrujesz lub grupujesz dane według strony, wybierz „Automatycznie”. W przeciwnym razie możesz agregować dane według usługi lub strony (w zależności od tego, jak chcesz obliczać dane). Z dokumentacji pomocy dowiesz się, jak różni się obliczanie danych w przypadku poszczególnych witryn i stron. Uwaga: jeśli grupujesz lub filtrujesz według strony, nie możesz agregować danych według usługi. Jeśli podasz wartość inną niż automatyczna, typ agregacji w wyniku będzie zgodny z żądanym typem. Jeśli wyślesz żądanie nieprawidłowego typu, wystąpi błąd. Interfejs API nigdy nie zmienia typu agregacji, jeśli żądany typ jest nieprawidłowy. Akceptowane wartości: „auto”: [wartość domyślna], pozwól usłudze wybrać odpowiedni typ 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 type=discover lub type=googleNews. Jeśli grupujesz według strony, filtrujesz według strony lub filtrujesz według innego elementu searchAppearance, nie możesz agregować danych według parametru byNewsShowcasePanel. „byPage”: agreguj wartości według identyfikatora URI. „byProperty”: agreguj wartości według usługi. Nieobsługiwane w przypadku wersji 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 przeglądać wyniki, użyj przesunięcia startRow.
startRow	integer	[Opcjonalnie; wartość domyślna to 0] Indeks liczony od zera pierwszego wiersza odpowiedzi. Musi być liczbą nieujemną. Jeśli startRow przekroczy liczbę wyników dla zapytania, odpowiedź to pomyślna odpowiedź bez wierszy.
dataState	string	[Opcjonalnie] Jeśli wybierzesz opcję „Wszystkie” (wielkość liter nie jest rozróżniana), dane będą uwzględniać aktualne dane. Jeśli parametr ma wartość „final” (wielkość liter nie jest rozróżniana) lub ten parametr zostanie pominięty, zwrócone dane będą zawierać tylko dane ostateczne.

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 np. pogrupujesz według wymiaru kraju, wszystkie wyniki dla hasła „usa” zostaną zgrupowane, wszystkie wyniki dla „mdv” zostaną zgrupowane razem itd. Jeśli pogrupujesz według kraju i urządzenia, wszystkie wyniki dla hasła „USA, tablety” zostaną zgrupowane, wszystkie wyniki dla hasła „USA, urządzenia mobilne” itd. Zapoznaj się z dokumentacją raportu Analityka wyszukiwania, aby dowiedzieć się więcej o sposobie obliczania liczby kliknięć, wyświetleń itp. oraz o tym, co one oznaczają.

Wyniki są sortowane według liczby kliknięć w kolejności malejącej, chyba że pogrupujesz dane według daty, w kolejności rosnącej (od najstarszej do najnowszego). Jeśli 2 wiersze są sobie równorzędne, kolejność sortowania jest dowolna.

Informacje o maksymalnej liczbie 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	Notatki
rows[]	list	Lista wierszy pogrupowanych według par klucz-wartość w kolejności określonej w zapytaniu.
rows[].keys[]	list	Lista wartości wymiarów w danym wierszu pogrupowanych według wymiarów w żądaniu i 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 danym wierszu. Wartości pochodzą z zakresu od 0 do 1, 0 włącznie.
rows[].position	double	Średnia pozycja w wynikach wyszukiwania
responseAggregationType	string	Sposób zagregowania wyników.Zapoznaj się z dokumentacją pomocy, aby dowiedzieć się, jak obliczamy dane w zależności od witryny i strony. Akceptowane wartości to: "auto" „byPage”: wyniki zostały zagregowane według strony. „byProperty”: wyniki zostały zagregowane według usługi.

Wypróbuj

Użyj poniższego eksploratora interfejsów API, aby wywołać tę metodę na bieżących danych i wyświetlić odpowiedź.