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"] }
Żą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:
|
|
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:
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:
|
|
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 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:
|
|
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:
|
Wypróbuj
Użyj poniższego eksploratora interfejsów API, aby wywołać tę metodę na bieżących danych i wyświetlić odpowiedź.