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
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"] }
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/ (usługa z prefiksem URL) lub sc-domain:example.com (usługa domeny).
|
Upoważnienie
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 | Notatki |
---|---|---|---|
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 zostały podane te wymiary.W polu dimensionFilterGroups[].filters[].dimension możesz użyć dowolnej nazwy wymiaru oraz daty.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. 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] Przefiltruj wyniki do tego typu:
|
|
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:
|
|
dimensionFilterGroups[].filters[] |
list |
[Opcjonalnie] 0 lub więcej filtrów do sprawdzenia względem 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 z wymienionych tutaj wymiarów, nawet jeśli nie grupujesz według tego wymiaru.
Akceptowane wartości to:
|
|
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:
|
|
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 z tej samej usługi są agregowane według strony. Jeśli są agregowane według strony, są agregowane 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 (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 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. 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:
|
|
rowLimit |
integer |
[Opcjonalny; 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] Indeks liczony od zera 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 opcję „Wszystkie” (wielkość liter nie jest rozróżniana), dane będą uwzględniać aktualne dane. Jeśli parametr ma wartość „final” (wielkość liter nie jest rozróżniana) lub 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 hasła „usa” zostaną zgrupowane, wszystkie wyniki dla „mdv” zostaną zgrupowane razem itd. Jeśli pogrupujesz według kraju i urządzenia, wszystkie wyniki dla hasła „USA, tablety” zostaną zgrupowane, wszystkie wyniki dla hasła „USA, urządzenia mobilne” 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 dane 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 | Notatki |
---|---|---|---|
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:
|
Wypróbuj
Użyj poniższego eksploratora interfejsów API, aby wywołać tę metodę na bieżących danych i wyświetlić odpowiedź.