Search Analytics: query

Wymaga autoryzacji

Wysyłanie zapytań dotyczących danych o ruchu z wyszukiwarki za pomocą zdefiniowanych przez siebie filtrów i parametrów. Ta metoda zwraca zero lub więcej wierszy zgrupowanych według zdefiniowanych przez Ciebie kluczy wierszy (wymiarów). Musisz zdefiniować zakres dat obejmujący co najmniej 1 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, wykonaj zapytanie bez filtrów pogrupowanych według daty, 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.

Informacje o wywoływaniu tej metody znajdziesz w przykładzie w języku Python.

Interfejs API jest objęty wewnętrznymi ograniczeniami Search Console i nie gwarantuje zwracania wszystkich wierszy danych, a jedynie wierszy najwyższego poziomu.

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

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/ (w przypadku usługi z prefiksem URL) lub sc-domain:example.com (w przypadku usługi domeny)

Upoważnienie

To żądanie wymaga autoryzacji z co najmniej jednym z poniższych 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ć taką strukturę:

{
  "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, według czasu PT (UTC-7:00/8:00). Nie może być późniejsza niż data zakończenia. Ta wartość znajduje się w zakresie.
endDate string [Wymagany] Data zakończenia wybranego zakresu dat w formacie RRRR-MM-DD, w czasie PT (UTC-7:00/8:00). Nie może być wcześniejsza niż data rozpoczęcia. Ta wartość znajduje się w zakresie.
dimensions[] list [Opcjonalnie] Zero lub więcej wymiarów, według których można grupować wyniki.Wyniki są grupowane w kolejności, w jakiej zostały wprowadzone te wymiary.W polu dimensionFilterGroups[].filters[].dimension możesz użyć dowolnej nazwy wymiaru lub daty.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żesz grupować, ale nie możesz dwukrotnie grupować według tego samego wymiaru. Przykład: [kraj, urządzenie]
searchType string Wycofano, zamiast tego użyj zasady type
type string [Opcjonalnie] Przefiltruj wyniki według 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 na karcie „Grafika” w wyszukiwarce Google.
  • „video”: wyniki wyszukiwania filmów
  • "web": [wartość domyślna]: filtrowanie wyników na połączonej karcie („Wszystkie”) w wyszukiwarce Google. Nie uwzględnia wyników z Discover ani Wiadomości Google.
dimensionFilterGroups[] list [Opcjonalnie] 0 lub więcej grup filtrów do zastosowania do wartości grupowania wymiarów. Aby w odpowiedzi został zwrócony wiersz, wszystkie grupy filtrów muszą być dopasowane. W ramach jednej grupy filtrów możesz określić, czy muszą pasować wszystkie filtry czy co najmniej 1.
dimensionFilterGroups[].groupType string Określa, czy wszystkie filtry w tej grupie muszą zwracać wartość „prawda” („and”), czy co najmniej jeden z nich musi zwracać wartość „prawda” (jeszcze nieobsługiwana).

Akceptowane wartości:
  • "and": Wszystkie filtry w grupie muszą zwracać wartość prawda w grupie filtrów to be true.
dimensionFilterGroups[].filters[] list [Opcjonalnie] 0 lub więcej filtrów 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, którego dotyczy ten filtr. Możesz filtrować według dowolnego wymienionego tutaj wymiaru, nawet jeśli nie grupujesz według tego wymiaru.

Akceptowane wartości:
  • „country”: użyj filtra, aby wyświetlić dane według kraju podanego w 3-literowym kodzie kraju (ISO 3166-1 alfa-3).
  • „device”: filtruj wyniki według określonego typu urządzenia. Obsługiwane wartości:
    • KOMPUTER
    • URZĄDZENIA MOBILNE
    • TABLET
  • „page”: filtruj według określonego ciągu identyfikatora URI.
  • „query”: filtruj według określonego ciągu zapytania.
  • „searchAppearance”: filtruj według określonej funkcji wyników wyszukiwania. Aby wyświetlić listę dostępnych wartości, uruchom zapytanie pogrupowane według elementu „searchface”.
dimensionFilterGroups[].filters[].operator string [Opcjonalnie] Sposób, w jaki określona wartość musi odpowiadać (lub nie pasować) 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”: [wartość domyślna] wyrażenie musi być dokładnie takie same jak wartość wiersza (wielkość liter ma znaczenie w przypadku wymiarów strony i zapytania).
  • „notContains”: wartość wiersza nie może zawierać wyrażenia w postaci podłańcucha ani jako pełnego dopasowania (bez rozróżniania wielkości liter).
  • „notEquals”: wyrażenie nie może być identyczne z 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ć dopasowywane.
  • „excludingRegex”: wyrażenie regularne 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 dane są agregowane według usługi, wszystkie dane z tej samej usługi są agregowane, a agregowane według strony – 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 – zależnie od tego, jak chcesz obliczać dane. W dokumentacji pomocy znajdziesz informacje o różnicach w obliczaniu danych według witryny i strony.

Uwaga: jeśli grupujesz lub filtrujesz dane według strony, nie możesz agregować danych według usługi.

Jeśli podasz dowolną wartość inną niż auto, typ agregacji w wyniku będzie zgodny z żądanym typem, a jeśli poprosisz o nieprawidłowy typ, pojawi się błąd. Jeśli żądany typ jest nieprawidłowy, interfejs API nigdy nie zmieni typu agregacji.

Akceptowane wartości:
  • „auto”: [wartość domyślna] pozwala 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 searchAppearance NEWS_SHOWCASE i właściwością 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 kryterium byNewsShowcasePanel.
  • „byPage”: agreguj wartości według identyfikatora URI.
  • „byProperty”: agreguj wartości według usługi. Nieobsługiwane w przypadku usług 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 między wynikami strony wyświetlić stronę, użyj przesunięcia startRow.
startRow integer [Opcjonalny; wartość domyślna to 0] liczony od zera indeks pierwszego wiersza odpowiedzi. Wartość musi być liczbą nieujemną. Jeśli startRow przekroczy liczbę wyników dla zapytania, odpowiedź będzie pomyślną odpowiedzią z 0 wierszami.
dataState string [Opcjonalnie] Jeśli ustawisz wartość „wszystkie” (wielkość liter nie jest rozróżniana), dane będą zawierać aktualne dane. Jeśli ustawisz wartość „final” (wielkość liter nie jest rozróżniana) lub ten parametr zostanie pominięty, zwracane dane będą zawierały tylko dane sfinalizowane.

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. Na przykład jeśli pogrupujesz według wymiaru kraju, wszystkie wyniki dla hasła „usa” zostaną zgrupowane, wszystkie wyniki dla „mdv” zostaną zgrupowane itd. Jeśli pogrupujesz wyniki według kraju i urządzenia, wszystkie wyniki dla hasła „usa, tablety” zostaną zgrupowane, wszystkie wyniki dla hasła „usa, mobile” itd. W dokumentacji raportu Analityka wyszukiwania znajdziesz szczegółowe informacje o sposobie obliczania kliknięć, wyświetleń itp. oraz ich znaczenia.

Wyniki są sortowane według liczby kliknięć w kolejności malejącej, chyba że pogrupujesz wyniki według daty – wtedy wyniki są sortowane w kolejności rosnącej (od najstarszych, od najnowszych). 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 w opisie 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 par klucz-wartość w kolejności podanej w zapytaniu.
rows[].keys[] list Lista wartości wymiarów w danym wierszu, pogrupowanych według wymiarów z żądania, 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) danego wiersza. 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.Informacje o różnicach w obliczaniu danych w poszczególnych witrynach i stronach znajdziesz w dokumentacji pomocy.

Akceptowane wartości:
  • "auto"
  • „byPage”: wyniki agregowano według strony.
  • „byProperty”: wyniki agregowano według usługi.

Wypróbuj

Użyj Eksploratora interfejsów API poniżej, aby wywołać tę metodę na aktywnych danych i zobaczyć odpowiedź.