Search Analytics: query

Wymaga autoryzacji

Twórz zapytania dotyczące danych o ruchu w sieci wyszukiwania przy użyciu zdefiniowanych przez siebie filtrów i parametrów. Ta metoda zwraca zero lub więcej wierszy pogrupowanych według zdefiniowanych przez Ciebie kluczy wiersza (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ę, w które dni są dostępne dane, wyślij 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ą sortowane w dowolny sposób.

Informacje o wywołaniu 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, tylko tych z góry.

Sprawdzanie limitów ilości dostępnych danych

Przykład JSON POST: 
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 użyciem co najmniej jednego 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 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 [Wymagane] Data rozpoczęcia żądanego zakresu dat w formacie RRRR-MM-DD, w czasie PT (UTC–7:00/8:00). Nie może być wcześniejsza niż data zakończenia. Ta wartość należy do zakresu.
endDate string [Wymagane] Data zakończenia żądanego zakresu dat w formacie RRRR-MM-DD, w czasie PT (UTC–7:00/8:00). Nie może być mniejsza niż data rozpoczęcia. Ta wartość należy do zakresu.
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 podasz te wymiary.Możesz użyć dowolnej nazwy wymiaru zarówno w polu dimensionFilterGroups[].filters[].dimension, jak i w polu „data”.Wartości wymiarów grupowania są łączone, tworząc unikalny klucz dla każdego wiersza wyników. Jeśli nie określisz żadnych wymiarów, wszystkie wartości zostaną połączone w 1 wiersz. Możesz grupować dane z dowolną liczbą wymiarów, ale nie możesz dwa razy 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 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": [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] Brak lub więcej grup filtrów, które można zastosować do wartości grupowania wymiarów. Aby wiersz został zwrócony w odpowiedzi, muszą być dopasowane wszystkie grupy filtrów. W ramach pojedynczej grupy filtrów możesz określić, czy muszą pasować wszystkie filtry, czy przynajmniej jeden.
dimensionFilterGroups[].groupType string Określa, czy wszystkie filtry w tej grupie muszą zwracać wartość „prawda” („and”), czy co najmniej 1 z nich musi zwracać wartość „prawda” (nie jest jeszcze obsługiwana).

Akceptowane wartości:
  • „and”: wszystkie filtry w grupie muszą zwracać wartość prawda w przypadku grupy filtrów to prawda.
dimensionFilterGroups[].filters[] list [Opcjonalny] Brak lub więcej filtrów do testowania 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 z wymienionych tutaj wymiarów, nawet jeśli nie grupujesz według tego wymiaru.

Akceptowane wartości:
  • „country”: filtruj według kraju określonego za pomocą 3-literowego kodu kraju (ISO 3166-1 alfa-3).
  • „device”: umożliwia filtrowanie wyników według określonego typu urządzenia. Obsługiwane wartości:
    • KOMPUTER
    • URZĄDZENIA MOBILNE
    • TABLET
  • „page”: filtruje według określonego ciągu URI.
  • „query”: filtrowanie według określonego ciągu zapytania.
  • „searchAppearance”: filtruje według określonej funkcji wyników wyszukiwania. Aby wyświetlić listę dostępnych wartości, uruchom zapytanie pogrupowane według elementu „searchVisual”.
dimensionFilterGroups[].filters[].operator string [Opcjonalnie] Sposób, w jaki określona wartość musi pasować (lub nie) do wartości wymiaru w wierszu.

Akceptowane wartości:
  • „contains”: wartość wiersza musi zawierać wyrażenie lub być mu równa (wielkość liter nie jest rozróżniana).
  • „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 jako podłańcucha ani pełnego dopasowania (wielkość liter nie jest rozróżniana).
  • „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 zostać 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. W przypadku agregacji 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 tryb automatyczny. 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 wartość inną niż automatyczna, 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] pozwól usłudze wybrać odpowiedni typ agregacji.
  • „byNewsShowcasePanel”: zagregowane 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 dane według strony, filtrujesz według strony lub filtrujesz według innego elementu searchAppearance, nie możesz korzystać z agregacji według wymiaru 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. Do podziału wyników między wynikami użyj przesunięcia startRow.
startRow integer [Opcjonalny; wartość domyślna to 0] liczony od zera indeks pierwszego wiersza w odpowiedzi. Musi być liczbą nieujemną. Jeśli startRow przekroczy liczbę wyników dla zapytania, odpowiedź będzie pomyślnym wynikiem z zerową liczbą wierszy.
dataState string [Opcjonalnie] Jeśli wybierzesz ustawienie „Wszystkie” (wielkość liter nie jest rozróżniana), dane będą zawierać aktualne dane. Jeśli parametr ma wartość „final” (wielkość liter nie jest rozróżniana) lub ten parametr jest pominięty, zwracane dane będą zawierały 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 na przykład pogrupujesz wyniki według wymiaru kraju, wszystkie wyniki dla hasła „usa” zostaną zgrupowane, wszystkie wyniki dla hasła „mdv” zostaną zgrupowane itd. Jeśli pogrupujesz wyniki według kraju i urządzenia, wszystkie wyniki dla hasła „usa, tablet” 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. W takim przypadku wyniki są sortowane według daty w kolejności rosnącej (od najstarszych, od najnowszych). Jeśli 2 wiersze mają takie same wartości, 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 Notatki
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 zgodnie z wymiarami w żądaniu, w kolejności określonej w żądaniu.
rows[].clicks double Liczba kliknięć w wierszu.
rows[].impressions double liczbę 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.Informacje o różnicach w obliczaniu danych w poszczególnych witrynach i poszczególnych stronach znajdziesz w dokumentacji pomocy

Akceptowane wartości:
  • "auto"
  • „byPage”: wyniki zostały zagregowane według strony.
  • „byProperty”: wyniki zostały zagregowane 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ź.