Search Analytics: query

Wymaga autoryzacji

Możesz wysyłać zapytania o dane o ruchu z sieci wyszukiwania, używając zdefiniowanych przez siebie filtrów i parametrów. Metoda zwraca co najmniej 0 wierszy pogrupowanych 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, dni bez danych są pomijane na liście wyników. Aby dowiedzieć się, które dni zawierają dane, wyślij zapytanie bez filtrów pogrupowane według daty dla interesującego Cię zakresu 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 dowolny sposób.

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

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

Zobacz limity ilości dostępnych danych

Przykładowe żądanie 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 mającej URL z przedrostkiem) 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

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
        }
      ],
      "filterLists": [
        {
          "dimension": string,
          "expressions": [
            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 czasie PT (UTC – 7:00/8:00). Musi być wcześniejsza lub taka sama jak data zakończenia. Ta wartość jest uwzględniana w zakresie.
endDate string [Wymagane] Data zakończenia żądanego zakresu dat w formacie RRRR-MM-DD, w czasie PT (UTC – 7:00/8:00). Musi być równa dacie rozpoczęcia lub od niej późniejsza. Ta wartość jest uwzględniana 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 podajesz te wymiary. Możesz użyć dowolnej nazwy wymiaru w dimensionFilterGroups[].filters[].dimension, a także „data” i „godzina”. Wartości wymiarów grupowania są łączone, aby utworzyć unikalny klucz 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żna grupować, ale nie można grupować według tego samego wymiaru 2 razy. Przykład: [country, device]
searchType string Wycofane, użyj type
type string [Opcjonalnie] Filtruj wyniki według tego typu:
  • „discover”: wyniki na kartach Discover.
  • „googleNews”: wyniki z news.google.com i 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ślna] filtruje wyniki na karcie „Wszystko” w wyszukiwarce Google. Nie obejmuje wyników z kart Discover ani Wiadomości Google.
  • „webMultimodal”: wyniki wyszukiwania z Obiektywu Google, funkcji „Zaznacz, aby wyszukać” na Androidzie i obrazów przesłanych do wyszukiwarki 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 jeden z nich.
dimensionFilterGroups[].groupType string Określa, czy wszystkie filtry w tej grupie muszą zwracać wartość „true” („and”), czy też co najmniej 1 filtr musi zwracać wartość „true” (jeszcze nieobsługiwane).

Akceptowane wartości:
  • „and”: aby grupa filtrów miała wartość „prawda”, wszystkie filtry w grupie muszą mieć 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 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, podanego jako 3-literowy kod kraju (ISO 3166-1 alfa-3).
  • „device”: filtrowanie wyników według określonego typu urządzenia. Obsługiwane wartości:
    • KOMPUTERY
    • MOBILE
    • TABLET
  • „page”: filtrowanie według określonego ciągu identyfikatora URI.
  • „query”: filtruj według określonego ciągu zapytania.
  • „searchAppearance”: filtrowanie według konkretnej funkcji wyników wyszukiwania. Aby zobaczyć listę dostępnych wartości, uruchom zapytanie pogrupowane według „searchAppearance”. Pełną listę wartości i opisów znajdziesz też w dokumentacji pomocy.
  • „brandedClassification”: filtruj wyniki według określonej klasyfikacji zapytania dotyczącego marki (obsługiwany jest tylko operator „equals”). Filtrowania ani grupowania według „brandedClassification” nie można połączyć z filtrem „query” w tym samym żądaniu. Dane są dostępne od 21 lutego 2026 r. i tylko w przypadku usług najwyższego poziomu z wystarczającą liczbą zapytań i wyświetleń (patrz ogłoszenie o zapytaniach dotyczących marki). Obsługiwane wartości:
    • BRANDED
    • NON_BRANDED
dimensionFilterGroups[].filters[].operator string [Opcjonalnie] Sposób, w jaki podana wartość musi pasować (lub nie pasować) do wartości wymiaru w wierszu.

Akceptowane wartości:
  • „contains”: wartość wiersza musi zawierać wyrażenie lub być mu równa (wielkość liter nie ma znaczenia).
  • „equals”: [Domyślne] Wyrażenie musi być dokładnie równe wartości wiersza (w przypadku wymiarów strony i zapytania wielkość liter ma znaczenie).
  • „notContains”: wartość wiersza nie może zawierać wyrażenia jako podłańcucha ani 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 wielkość liter ma znaczenie).
  • „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 zostać dopasowane.
dimensionFilterGroups[].filters[].expression string Wartość, którą filtr ma dopasować lub wykluczyć, w zależności od operatora.
dimensionFilterGroups[].filterLists[] list [Opcjonalnie] Co najmniej 1 filtr wymiaru wielowartościowego do przetestowania w wierszu. W odróżnieniu od operatora filters[], który dopasowuje pojedynczą wartość na wpis, operator filterLists[] umożliwia dopasowanie wielu wartości dopasowania ścisłego dla pojedynczego wymiaru w jednym filtrze. Wiersz pasuje do listy filtrów, jeśli jego wartość dla określonego dimension jest równa dowolnej z podanych wartości expressions. Pamiętaj, że pojedyncze żądanie nie może filtrować według tego samego wymiaru jednocześnie w filters i filterLists.
dimensionFilterGroups[].filterLists[].dimension string [Wymagane] Wymiar, do którego ma zastosowanie ta lista filtrów.

Akceptowane wartości:
  • „country”: filtrowanie według określonych krajów przy użyciu 3-literowych kodów krajów (ISO 3166-1 alfa-3).
  • „device”: filtrowanie według określonych typów urządzeń (DESKTOP, MOBILE, TABLET).
dimensionFilterGroups[].filterLists[].expressions[] list [Wymagane] Lista wartości (string), według których ma być filtrowane.
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 identyfikatora URI. Jeśli filtrujesz lub grupujesz według strony, wybierz opcję automatyczną. W przeciwnym razie możesz agregować według usługi lub strony, w zależności od tego, jak chcesz obliczać dane. Aby dowiedzieć się, jak dane są obliczane w przypadku witryny, a jak w przypadku 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 wartość inną niż auto, typ agregacji w wyniku będzie zgodny z żądanym typem. 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ślny] Pozwól usłudze wybrać odpowiedni typ agregacji.
  • „byNewsShowcasePanel”: wartości zbiorcze według panelu Showcase w Wiadomościach. Tego parametru należy używać w połączeniu z filtrem NEWS_SHOWCASE searchAppearance oraz parametrem 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ć według elementu 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 [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 [Opcjonalny; domyślnie 0] Indeks pierwszego wiersza w odpowiedzi (liczony od 0). Nie może być liczbą ujemną. Jeśli wartość startRow przekracza liczbę wyników zapytania, odpowiedź będzie pomyślna i będzie zawierać 0 wierszy.
dataState string [Opcjonalnie] Jeśli „all” (wielkość liter nie jest rozróżniana), dane będą zawierać najnowsze dane. Jeśli podasz wartość „final” (wielkość liter nie jest rozróżniana) lub pominiesz ten parametr, zwrócone dane będą zawierać tylko sfinalizowane dane. Jeśli „hourly_all” (wielkość liter nie jest rozróżniana), dane będą zawierać podział godzinowy. Wskazuje ona, że dane godzinowe zawierają dane częściowe i powinna być używana podczas grupowania według wymiaru HOUR interfejsu 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 jednym wierszu. Jeśli na przykład grupujesz według wymiaru kraju, wszystkie wyniki dla „usa” zostaną zgrupowane razem, wszystkie wyniki dla „mdv” zostaną zgrupowane razem itd. Jeśli pogrupujesz dane według kraju i urządzenia, wszystkie wyniki dla „USA, tablet” zostaną zgrupowane, wszystkie wyniki dla „USA, komórka” zostaną zgrupowane itd. W dokumentacji raportu Analityka wyszukiwania znajdziesz szczegółowe informacje o tym, jak obliczane są kliknięcia, wyświetlenia itp. oraz co oznaczają.

Wyniki są sortowane według liczby kliknięć w porządku malejącym, chyba że grupujesz według daty – wtedy są sortowane według daty w porządku rosnącym (od najstarszych do najnowszych). Jeśli 2 wiersze są sobie równe, kolejność sortowania jest dowolna.

Aby dowiedzieć się, jaka jest maksymalna liczba wartości, które mogą zostać zwrócone, zapoznaj się z 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 klucza 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 danym 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 agregacji wyników. Aby dowiedzieć się, jak dane są obliczane w różny sposób w przypadku witryny i strony, zapoznaj się z dokumentacją 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, dostarczający kontekst dotyczący stanu danych.

Gdy prosisz o najnowsze dane (używając all lub hourly_all w przypadku dataState), niektóre zwrócone wiersze mogą zawierać niekompletne 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 zwracane 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, podana w formacie YYYY-MM-DD (rozszerzony format daty lokalnej ISO-8601).

    To pole jest wypełniane tylko wtedy, gdy parametr dataState żądania ma wartość all, dane są grupowane 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, podana w formacie YYYY-MM-DDThh:mm:ss[+|-]hh:mm (rozszerzony format daty i godziny ISO-8601).

    To pole jest wypełniane tylko wtedy, gdy parametr dataState żądania ma wartość hourly_all, a dane są grupowane 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

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