Search Analytics: query

Wymaga autoryzacji

Wyszukiwanie danych dotyczących ruchu w sieci wyszukiwania za pomocą zdefiniowanych przez Ciebie filtrów i parametrów. Metoda zwraca co najmniej 1 wiersz zgrupowany 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.

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

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

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 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 [Wymagany] Data rozpoczęcia żądanego zakresu dat w formacie RRRR-MM-DD w czasie pacyficznym (UTC-7:00/8:00). Nie może być późniejsza niż data zakończenia. Ta wartość jest zawarta 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] 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 1 wiersz. Nie ma limitu liczby wymiarów, według których możesz grupować dane, ale nie możesz tworzyć grup 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 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ślnie] filtrowanie wyników do karty połączonej („Wszystkie”) w wyszukiwarce Google. Nie uwzględnia wyników na kartach Discover ani w Wiadomościach 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:
  • „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ść 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 to:
  • „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”: filtruj według określonego ciągu zapytania.
  • „searchAppearance”: filtrowanie według określonej 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 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 to:
  • „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ć zgodne.
  • „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 agregowania danych. Jeśli dane są agregowane według usługi, są agregowane wszystkie dane dotyczące tej samej usługi. Jeśli dane są agregowane według strony, są agregowane według kanonicznego 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 grupowanie lub filtrowanie odbywa się 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 zmieni 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. 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 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 zgrupujesz dane według kraju i urządzenia, wszystkie wyniki dla „usa, tablet” będą zgrupowane, wszystkie wyniki dla „usa, telefon” będą zgrupowane 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 wyniki 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.

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 to:
  • „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.