Search Analytics: query

Wymaga autoryzacji

Wysyłaj zapytania do danych o ruchu w wyszukiwarce za pomocą zdefiniowanych przez siebie filtrów i parametrów. Metoda zwraca co najmniej 1 wiersz zgrupowany według zdefiniowanych przez Ciebie kluczy wierszy (wymiarów). Musisz zdefiniować zakres dat obejmujący co najmniej 1 dzień.

Jeśli data jest jednym z wymiarów, z listy wyników pomijane są dni bez danych. Aby dowiedzieć się, w których dniach są dane, prześlij zapytanie bez filtrów pogrupowane według daty w wybranym zakresie 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 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). Musi być równa lub mniejsza od daty zakończenia. Ta wartość jest zawarta 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 lub większa od daty rozpoczęcia. 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 elemencie dimensionFilterGroups[].filters[].dimension możesz użyć dowolnej nazwy wymiaru, a także nazw „data” i „godzina”. Wartości wymiaru grupowania są łączone, aby utworzyć niepowtarzalny 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ć dane, ale nie możesz tworzyć grup według tego samego wymiaru dwukrotnie. Przykład: [kraj, urządzenie]
searchType string Wycofany, użyj type
type string [Opcjonalnie] Filtruj wyniki według 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 połączonej karty („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ść „prawda” („i”), czy co najmniej 1 filtr musi zwracać wartość „prawda” (nie jest to jeszcze obsługiwane).

Akceptowane wartości:
  • „and”: aby grupa filtrów zwróciła wartość „prawda”, wszystkie filtry w grupie 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ć dane 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”. Pełną listę wartości i ich opisów znajdziesz też 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 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 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 różnicach w obliczaniu danych według witryny i strony 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 dowolną 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”: [wartość domyślna] usługa sama zdecyduje o odpowiednim typie 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 type=discover i type=googleNews
rowLimit integer [Opcjonalnie; dopuszczalny zakres to 1–25 tys.; domyślnie 1000] Maksymalna liczba wierszy do zwrócenia. Aby przeglądać wyniki strona po stronie, 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 względu na wielkość liter), dane będą zawierać najnowsze dane. Jeśli parametr ma wartość „final” (niezależnie od wielkości liter), lub jeśli nie podasz tego parametru, zwrócone dane będą zawierać tylko sfinalizowane dane. Jeśli „hourly_all” (wielkość liter nie ma znaczenia), dane będą zawierać zestawienie godzinowe. Wskazuje to, że dane godzinne obejmują dane częściowe i powinny być używane podczas grupowania według wymiaru HOUR 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 jeden wiersz. 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, podobnie jak wszystkie wyniki dla „usa, komórka” 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, zobacz 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 zgrupowane według strony.
  • „byProperty”: wyniki zostały zagregowane według usługi.