Search Analytics: query

Wymaga autoryzacji

Wyszukiwanie danych dotyczących ruchu w sieci wyszukiwania za pomocą zdefiniowanych przez Ciebie filtrów i parametrów. Zwraca ona 0 lub więcej wierszy zgrupowanych według zdefiniowanych przez Ciebie kluczy wierszy (wymiarów). Musisz zdefiniować zakres dat obejmujący co najmniej jeden 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, wyślij zapytanie bez filtrów pogrupowanych według daty i dla wybranego zakresu dat.

Wyniki są sortowane malejąco według liczby kliknięć. 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 wewnętrznymi ograniczeniami Search Console i nie gwarantuje, że zwróci on wszystkie wiersze danych, a nie tylko te z góry.

Zobacz limity ilości dostępnych danych

Przykład żądania POST 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 określony w Search Console. Przykłady: http://www.example.com/ (w przypadku usługi z prefiksem URL) lub sc-domain:example.com (usługa domeny)

Autoryzacja

To żądanie wymaga autoryzacji z co najmniej jednym z tych zakresów (więcej informacji o uwierzytelnianiu i autoryzowaniu).

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 Uwagi
startDate string [Wymagany] Data rozpoczęcia wybranego zakresu dat w formacie RRRR-MM-DD w czasie PT (UTC – 7:00/8:00). Nie może być późniejsza niż data zakończenia. Ta wartość jest uwzględniona 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] Brak lub więcej wymiarów, według których można grupować wyniki.Wyniki są grupowane w kolejności, w jakiej podasz te wymiary.W polu dimensionFilterGroups[].filters[].dimension możesz użyć dowolnej nazwy wymiaru oraz wartości „data”.Po połączeniu wartości wymiarów grupowania utworzą one unikalny klucz dla każdego wiersza wyników. Jeśli nie podasz żadnych wymiarów, wszystkie wartości zostaną połączone w 1 wiersz. Możesz grupować według nieograniczonej liczby wymiarów, ale nie możesz grupować według tego samego wymiaru dwukrotnie. Przykład: [kraj, urządzenie]
searchType string Wycofano, zamiast niego 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 na Androidzie i iOS. Nie obejmuje wyników z kategorii „Wiadomości” w wyszukiwarce Google.
  • „news”: wyniki wyszukiwania z kategorii „Wiadomości” w wyszukiwarce Google.
  • „image”: wyniki wyszukiwania z kategorii „Obraz” w wyszukiwarce Google.
  • „video”: wyniki wyszukiwania filmów
  • „web”: [wartość domyślna] filtruj wyniki do połączonej karty („Wszystkie”) w Wyszukiwarka Google. Nie uwzględnia wyników na kartach Discover ani w Wiadomościach Google.
dimensionFilterGroups[] list [Opcjonalnie] Brak lub więcej grup filtrów, które można zastosować do wartości grupowania wymiarów. Aby w odpowiedzi został zwrócony wiersz, wszystkie grupy filtrów muszą być zgodne. W ramach jednej grupy filtrów możesz określić, czy spełnione muszą być wszystkie filtry, czy przynajmniej jeden.
dimensionFilterGroups[].groupType string Określa, czy wszystkie filtry w tej grupie muszą zwracać wartość „prawda” („i”) czy też co najmniej 1 z nich musi zwracać wartość „prawda” (jeszcze nieobsługiwana).

Akceptowane wartości to:
  • „and”: wszystkie filtry w grupie muszą zwracać wartość „prawda” dla grupy filtrów, to wartość „prawda”.
dimensionFilterGroups[].filters[] list [Opcjonalnie] 0 lub więcej filtrów do sprawdzenia względem wiersza. Każdy filtr składa się z: nazwę wymiaru, operator i wartość. 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 z wymienionych tutaj wymiarów, nawet jeśli nie grupujesz według tego wymiaru.

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

Akceptowane wartości to:
  • „contains”: wartość wiersza musi zawierać wyrażenie lub być równe (wielkość liter nie jest rozróżniana).
  • „equals”: [wartość domyślna]: wyrażenie musi dokładnie odpowiadać wartości wiersza (wielkość liter ma znaczenie w przypadku wymiarów strony i zapytania).
  • „notContains”: wartość wiersza nie może zawierać wyrażenia ani jako podłańcucha, ani jako pełnego dopasowania (wielkość liter nie jest rozróżniana).
  • „notEquals”: wyrażenie nie może dokładnie odpowiadać wartości wiersza (wielkość liter ma znaczenie w przypadku wymiarów strony i zapytania).
  • „includingRegex”: Składnia RE2 wyrażenie regularne, które musi być dopasowane.
  • „excludingRegex”: Składnia RE2 wyrażenie regularne, 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 są agregowane według usługi, wszystkie dane dotyczące usługi ta sama usługa jest agregowana; jeśli są agregowane według strony, wszystkie dane są agregowane według stron kanonicznych Identyfikator URI. Jeśli filtrujesz lub grupujesz dane według strony, wybierz „Automatycznie”. W przeciwnym razie możesz agregować wartości według usługi lub strony – w zależności od tego, jak chcesz obliczać dane; zobacz dokumentacji pomocy .

Uwaga: Jeśli grupujesz lub filtrujesz 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 lub jeśli wyślesz żądanie nieprawidłowego typu, wystąpi błąd. Interfejs API nigdy nie zmienia 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 Panel Showcase w Wiadomościach. Tego atrybutu należy używać w połączeniu z zasadą NEWS_SHOWCASE searchAppearance filtr i type=discover lub type=googleNews. Jeśli grupujesz według strony, filtrujesz według strony lub filtrujesz według innego elementu searchAppearance, nie można agregować według kolumny byNewsShowcasePanel.
  • „byPage”: agreguj wartości według identyfikatora URI.
  • „byProperty”: agreguj wartości według usługi. Nieobsługiwane w przypadku wersji type=discover i type=googleNews
rowLimit integer [Opcjonalnie; 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 [Opcjonalnie; Wartość domyślna to 0] liczony od zera indeks pierwszego wiersza odpowiedzi. Musi być liczbą nieujemną. Jeśli startRow przekroczy liczbę wyników dla zapytania, odpowiedź to pomyślna odpowiedź bez wierszy.
dataState string [Opcjonalnie] Jeśli wybierzesz „Wszystkie” (wielkość liter nie jest rozróżniana), dane będą obejmować aktualnych danych. Jeżeli ma stan „ostateczny”, (wielkość liter nie jest rozróżniana) lub jeśli ten parametr zostanie pominięty, zwrócone dane będą zawierać 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 np. pogrupujesz według wymiaru kraju, wszystkie wyniki dla „usa” zostaną zgrupowane, wszystkie wyniki dla „mdv” zostaną zgrupowane i tak dalej. Jeśli pogrupujesz według kraju i urządzenia, wszystkie wyniki dla hasła „USA, tablet” zostanie zgrupowany, wszystkie wyniki dla hasła „usa, mobile” zostaną zgrupowane i tak dalej. Zapoznaj się z dokumentacją raportu Analityka wyszukiwania, aby dowiedzieć się więcej o sposobie obliczania liczby kliknięć, wyświetleń itp. oraz o tym, co 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.

Informacje o maksymalnej liczbie wartości, które można zwrócić, znajdziesz we 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 określonej w zapytaniu.
rows[].keys[] list Lista wartości wymiarów w danym wierszu pogrupowanych według wymiarów w żądaniu i w kolejności określonej w żądaniu.
rows[].clicks double Liczba kliknięć w wierszu.
rows[].impressions double Liczba wyświetleń w 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 zagregowania wyników.Zapoznaj się z dokumentacją pomocy, aby dowiedzieć się, jak obliczamy dane w zależności od witryny i strony.

Akceptowane wartości to:
  • „auto”
  • „byPage”: wyniki zostały zagregowane według strony.
  • „byProperty”: wyniki zostały zagregowane według usługi.

Wypróbuj

Użyj poniższego eksploratora interfejsów API, aby wywołać tę metodę na bieżących danych i wyświetlić odpowiedź.