Search Analytics: query

Wymaga autoryzacji

Wysyłaj zapytania do danych o ruchu w wyszukiwarce za pomocą zdefiniowanych przez siebie filtrów i parametrów. Zwraca ona 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 data jest jednym z wymiarów, z listy wyników pomija się wszystkie dni bez danych. 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 według liczby kliknięć malejąco. Jeśli 2 wiersze mają taką samą liczbę kliknięć, są one sortowane w dowolny sposób.

Aby wywołać tę metodę, użyj przykładu w Pythonie.

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

Zobacz limity 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

Żą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 określony 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 [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 zawarta w zakresie.
dimensions[] list [Opcjonalnie] co najmniej 1 wymiar do grupowania wyników. Wyniki są grupowane w kolejności, w jakiej podajesz te wymiary. W wymiarze dimensionFilterGroups[].filters[].dimension możesz użyć dowolnej nazwy wymiaru, a także wymiaru „data”.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 jeden 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 Wycofane, użyj zamiast tego type
type string [Opcjonalnie] Filtrowanie wyników według 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 z karty „Wiadomości” w wyszukiwarce Google.
  • „image”: wyniki wyszukiwania z karty „Grafika” w wyszukiwarce Google.
  • „video”: wyniki wyszukiwania filmów
  • „web”: [Domyślnie] filtrowanie wyników do karty połączonej („Wszystkie”) w wyszukiwarce Google. Nie obejmuje wyników z Discover ani Wiadomości Google.
dimensionFilterGroups[] list [Opcjonalnie] Co najmniej 1 grupa 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 muszą pasować wszystkie filtry, czy co najmniej 1 filtr.
dimensionFilterGroups[].groupType string Określa, czy wszystkie filtry w tej grupie muszą zwracać wartość true („i”), czy co najmniej 1 filtr musi zwracać wartość true (nie jest to jeszcze obsługiwane).

Akceptowane wartości to:
  • „and”: aby grupa filtrów zwróciła wartość „prawda”, wszystkie filtry w niej muszą zwracać wartość „prawda”.
dimensionFilterGroups[].filters[] list [Opcjonalnie] co najmniej 1 filtr do przetestowania w odniesieniu do wiersza. 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 na tej liście, nawet jeśli nie grupowujesz według tego wymiaru.

Akceptowane wartości:
  • „country”: filtrowanie według wybranego 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ĄDZENIE MOBILNE
    • TABLET
  • „page”: filtrowanie według określonego ciągu znaków identyfikatora URI.
  • „query”: filtrowanie według określonego ciągu zapytania.
  • „searchAppearance”: filtrowanie według określonej funkcji wyników wyszukiwania. Aby zobaczyć listę dostępnych wartości, uruchom zapytanie pogrupowane według kolumny „searchAppearance” (Wygląd wyszukiwania). Pełna lista wartości i opisów jest również dostępna w dokumentacji pomocy.
dimensionFilterGroups[].filters[].operator string [Opcjonalnie] Sposób, w jaki określona wartość musi być zgodna (lub nie) z wartością wymiaru w wierszu.

Akceptowane wartości:
  • „contains”: wartość wiersza musi zawierać wyrażenie lub być równa temu wyrażeniu (bez uwzględniania wielkości liter).
  • „equals”: [wartość domyślna] wyrażenie musi dokładnie odpowiadać wartości wiersza (wielkość liter ma znaczenie w przypadku wymiarów „Strona” i „Zapytanie”).
  • „notContains”: wartość wiersza nie może zawierać wyrażenia jako podciągu ani dopasowania pełnego (bez uwzględniania wielkości liter).
  • „notEquals”: wyrażenie nie musi być identyczne z wartością wiersza (w przypadku wymiarów „Strona” i „Zapytanie” rozróżniana jest wielkość liter).
  • „includingRegex”: wyrażenie regularne w składni RE2, które musi być dopasowane.
  • „excludingRegex”: wyrażenie regularne w składni RE2, które nie musi być zgodne.
dimensionFilterGroups[].filters[].expression string Wartość, która ma być dopasowywana lub wykluczana przez filtr, 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 grupowanie według strony, wybierz automatyczne. W przeciwnym razie możesz agregować dane według usługi lub strony, w zależności od tego, jak mają być obliczone. Więcej informacji o rozbieżnościach w obliczaniu danych w przypadku witryn i stron znajdziesz w dokumentacji pomocy.

Uwaga: jeśli grupowanie lub filtrowanie odbywa się według strony, nie możesz agregować danych według usługi.

Jeśli podasz wartość inną niż automatyczne, typ agregacji w wyniku będzie odpowiadać żądanemu typowi. Jeśli podasz nieprawidłowy typ, pojawi się błąd. Interfejs API nigdy nie zmieni typu agregacji, jeśli żądany typ jest nieprawidłowy.

Akceptowane wartości:
  • „auto”: [domyślnie] usługa sama wybiera odpowiedni typ agregacji.
  • „byNewsShowcasePanel”: wartości zbiorcze według panelu Showcase w Wiadomościach. Należy go używać w połączeniu z filtrem NEWS_SHOWCASE searchAppearance i jedną z właściwości type=discover lub type=googleNews. Jeśli grupowanie według strony, filtrowanie według strony lub filtrowanie do innego searchAppearance, nie możesz agregować według byNewsShowcasePanel.
  • „byPage”: wartości zagregowane według identyfikatora URI.
  • „byProperty”: wartości zagregowane według usługi. Nieobsługiwane w przypadku wersji type=discover i type=googleNews
rowLimit integer [Opcjonalnie; dopuszczalny zakres to 1–25 tys.; domyślnie 1000] Maksymalna liczba wierszy do zwrócenia. Aby przewijać wyniki, użyj przesunięcia startRow.
startRow integer [Opcjonalnie; domyślnie 0] Indeks pierwszej wiersza w odpowiedzi liczony od 0. Musi być liczbą nieujemną. Jeśli startRow przekracza liczbę wyników zapytania, odpowiedź będzie pomyślną odpowiedzią z zerową liczbą wierszy.
dataState string [Opcjonalnie] Jeśli wybierzesz „all” (bez rozróżniania wielkości liter), dane będą obejmować najnowsze dane. Jeśli parametr ma wartość „final” (niezależnie od wielkości liter) lub jeśli nie zostanie podany, zwrócone dane będą zawierać tylko sfinalizowane dane.

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. grupowanie odbywa się według wymiaru kraju, wszystkie wyniki dla „usa” będą zgrupowane razem, podobnie wszystkie wyniki dla „mdv” 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. Więcej informacji o sposobie obliczania i interpretacji liczby kliknięć, wyświetleń itp. znajdziesz w dokumentacji raportu Analityka wyszukiwania.

Wyniki są sortowane według liczby kliknięć w kolejności malejącej, chyba że grupowanie odbywa się według daty. W takim przypadku wyniki są sortowane według daty w kolejności rosnącej (najpierw najstarsze, a na końcu najnowsze). Jeśli 2 wiersze są sobie równorzędne, kolejność sortowania jest dowolna.

Aby dowiedzieć się, jaka jest maksymalna liczba wartości, które mogą zostać zwrócone, sprawdź właściwość rowLimit w pytaniu.

{
  "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 klucza w kolejności podanej w zapytaniu.
rows[].keys[] list Lista wartości wymiarów w danym wierszu, pogrupowanych według wymiarów w żądaniu w kolejności podanej w żądaniu.
rows[].clicks double Kliknij liczbę kliknięć w wierszu.
rows[].impressions double Liczba wyświetleń w wierszu.
rows[].ctr double Współczynnik klikalności (CTR) wiersza. Wartości mieszczą się w zakresie od 0 do 1, 0.
rows[].position double Średnia pozycja w wynikach wyszukiwania.
responseAggregationType string Sposób agregacji wyników. Aby dowiedzieć się, jak dane są obliczane w różny sposób w przypadku witryn i stron, otwórz dokumentację.

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

Wypróbuj

Aby wywołać tę metodę na podstawie danych na żywo i zobaczyć odpowiedź, użyj narzędzia APIs Explorer.