Wymaga autoryzacji
Wysyłaj zapytania o dane o ruchu z wyszukiwarki za pomocą zdefiniowanych przez siebie filtrów i parametrów. Ta metoda zwraca zero lub więcej wierszy pogrupowanych według kluczy wierszy (wymiarów) zdefiniowanych przez Ciebie. Musisz określić zakres dat obejmujący co najmniej 1 dzień.
Jeśli data jest jednym z wymiarów, wszystkie dni bez danych są pomijane na liście wyników. Aby dowiedzieć się, w których dniach są dostępne dane, wyślij zapytanie bez filtrów pogrupowane według daty w interesującym Cię zakresie dat.
Wyniki są sortowane według liczby kliknięć w kolejności malejącej. Jeśli 2 wiersze mają taką samą liczbę kliknięć, są sortowane w dowolnej kolejności.
Aby dowiedzieć się, jak wywołać tę metodę, zapoznaj się z przykładem w Pythonie.
Interfejs API jest ograniczony przez wewnętrzne ograniczenia Search Console i nie gwarantuje zwrócenia wszystkich wierszy danych, ale tylko te najważniejsze.
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 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 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 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 |
[Wymagane] Data rozpoczęcia żądanego zakresu dat w formacie RRRR-MM-DD w strefie czasowej PT (UTC – 7:00/8:00). Musi być wcześniejsza lub równa dacie zakończenia. Ta wartość jest uwzględniana w zakresie. | |
endDate |
string |
[Wymagane] Data zakończenia żądanego zakresu dat w formacie RRRR-MM-DD w strefie czasowej PT (UTC – 7:00/8:00). Musi być późniejsza lub równa dacie rozpoczęcia. Ta wartość jest uwzględniana w zakresie. | |
dimensions[] |
list |
[Opcjonalnie] Zero lub więcej wymiarów, według których mają być grupowane wyniki. Wyniki są grupowane w kolejności, w jakiej podajesz te wymiary.Możesz użyć dowolnej nazwy wymiaru w dimensionFilterGroups[].filters[].dimension, a także „date” i „hour”. Wartości wymiaru grupowania są łączone w celu utworzenia unikalnego klucza dla każdego wiersza wyników. Jeśli nie podasz żadnych wymiarów, wszystkie wartości zostaną połączone w jeden wiersz. Nie ma ograniczeń co do liczby wymiarów, według których można grupować dane, ale nie można grupować według tego samego wymiaru 2 razy. Przykład: [country, device] | |
searchType |
string |
Wycofane, zamiast tego użyj parametru type
|
|
type |
string |
[Opcjonalnie] Filtruj wyniki według tego typu:
|
|
dimensionFilterGroups[] |
list |
[Opcjonalnie] Zero lub więcej grup filtrów do zastosowania 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 wszystkie filtry muszą być zgodne, czy tylko co najmniej 1. | |
dimensionFilterGroups[].groupType |
string |
Czy wszystkie filtry w tej grupie muszą zwracać wartość true („and”), czy co najmniej 1 musi zwracać wartość true (nie jest jeszcze obsługiwane).
Akceptowane wartości:
|
|
dimensionFilterGroups[].filters[] |
list |
[Opcjonalnie] Zero lub więcej filtrów do przetestowania 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, do którego odnosi się ten filtr. Możesz filtrować według dowolnego wymiaru wymienionego tutaj, nawet jeśli nie grupujesz według tego wymiaru.
Akceptowane wartości:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Opcjonalnie] Jak określona wartość musi pasować (lub nie pasować) do wartości wymiaru w wierszu.
Akceptowane wartości:
|
|
dimensionFilterGroups[].filters[].expression |
string |
Wartość, która ma być dopasowana lub wykluczona przez filtr, w zależności od operatora. | |
aggregationType |
string |
[Opcjonalnie] Jak dane są agregowane. Jeśli dane są agregowane według usługi, wszystkie dane dotyczące tej samej usługi są agregowane . Jeśli dane są agregowane według strony, wszystkie dane są agregowane według kanonicznego adresu URI . Jeśli filtrujesz lub grupujesz według strony, wybierz opcję auto. W przeciwnym razie możesz agregować według usługi lub strony, w zależności od tego, jak chcesz obliczać dane. Więcej informacji o tym, jak dane są obliczane inaczej według witryny niż według strony, znajdziesz w dokumentacji pomocy . Uwaga: Jeśli grupujesz lub filtrujesz według strony, nie możesz agregować według usługi. Jeśli podasz inną wartość niż auto, typ agregacji w wyniku będzie zgodny z żądanym typem. Jeśli poprosisz o nieprawidłowy typ, otrzymasz błąd. Interfejs API nigdy nie zmieni typu agregacji, jeśli żądany typ jest nieprawidłowy. Akceptowane wartości:
|
|
rowLimit |
integer |
[Opcjonalnie; prawidłowy zakres to 1–25 000; domyślna wartość to 1000] Maksymalna liczba wierszy do zwrócenia. Aby podzielić wyniki na strony, użyj przesunięcia startRow. |
|
startRow |
integer |
[Opcjonalnie; domyślna wartość to 0] Indeks pierwszego wiersza w odpowiedzi (liczony od zera). Nie może być liczbą ujemną. Jeśli startRow przekracza liczbę wyników zapytania, odpowiedź będzie zawierać 0 wierszy. |
|
dataState |
string |
[Opcjonalnie] Jeśli podasz "all" (bez uwzględniania wielkości liter), dane będą zawierać najnowsze dane. Jeśli podasz „final” (bez uwzględniania wielkości liter) lub pominiesz ten parametr, zwrócone dane będą zawierać tylko dane ostateczne. Jeśli podasz „hourly_all” (bez uwzględniania wielkości liter), dane będą zawierać podział na godziny. Wskazuje to, że dane godzinowe zawierają dane częściowe i należy ich używać podczas grupowania według wymiaru GODZINA w interfejsie 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 na przykład grupujesz według wymiaru kraj, wszystkie wyniki dla „usa” zostaną zgrupowane, wszystkie wyniki dla „mdv” zostaną zgrupowane itd. Jeśli grupujesz według kraju i urządzenia, wszystkie wyniki dla „usa, tablet” zostaną zgrupowane, wszystkie wyniki dla „usa, mobile” zostaną zgrupowane itd. Więcej informacji o tym, jak obliczane są kliknięcia, wyświetlenia itp. oraz co one oznaczają, znajdziesz w dokumentacji raportu Statystyki wyszukiwania.
Wyniki są sortowane według liczby kliknięć w kolejności malejącej, chyba że grupujesz według daty. W takim przypadku wyniki są sortowane według daty w kolejności rosnącej (najstarsze najpierw, najnowsze na końcu). Jeśli 2 wiersze mają taką samą wartość, kolejność sortowania jest dowolna.
Maksymalną liczbę 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 | Uwagi |
|---|---|---|---|
rows[] |
list |
Lista wierszy pogrupowanych według wartości kluczy 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 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 wierszu. Wartości pochodzą z zakresu od 0 do 1, 0. | |
rows[].position |
double |
Średnia pozycja w wynikach wyszukiwania. | |
responseAggregationType |
string |
Jak wyniki zostały zagregowane.Więcej informacji o tym, jak dane są obliczane inaczej według witryny niż według strony, znajdziesz w dokumentacji pomocy.
Akceptowane wartości:
|
|
metadata |
object |
Obiekt, który może zostać zwrócony z wynikami zapytania i który zawiera informacje o stanie danych. Gdy poprosisz o najnowsze dane (używając Wszystkie daty i godziny podane w tym obiekcie są w Konkretne pole zwrócone w tym obiekcie zależy od tego, jak dane zostały pogrupowane w żądaniu:
|
Wypróbuj
Aby wywołać tę metodę na podstawie danych na żywo i zobaczyć odpowiedź, użyj Eksploratora interfejsów API poniżej.