Wymaga autoryzacji
Możesz wysyłać zapytania o dane o ruchu z sieci wyszukiwania, używając zdefiniowanych przez siebie filtrów i parametrów. Metoda zwraca co najmniej 0 wierszy pogrupowanych według zdefiniowanych przez Ciebie kluczy wierszy (wymiarów). Musisz określić zakres dat obejmujący co najmniej 1 dzień.
Jeśli jednym z wymiarów jest data, dni bez danych są pomijane na liście wyników. Aby dowiedzieć się, które dni zawierają dane, wyślij zapytanie bez filtrów pogrupowane według daty dla interesującego Cię zakresu 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 dowolny sposób.
Aby dowiedzieć się, jak wywołać tę metodę, zapoznaj się z przykładem w języku Python.
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 mającej URL z przedrostkiem) 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
W treści żądania podaj dane o tej strukturze:
{
"startDate": string,
"endDate": string,
"dimensions": [
string
],
"type": string,
"dimensionFilterGroups": [
{
"groupType": string,
"filters": [
{
"dimension": string,
"operator": string,
"expression": string
}
],
"filterLists": [
{
"dimension": string,
"expressions": [
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 czasie PT (UTC – 7:00/8:00). Musi być wcześniejsza lub taka sama jak data zakończenia. Ta wartość jest uwzględniana 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 dacie rozpoczęcia lub od niej późniejsza. Ta wartość jest uwzględniana w zakresie. | |
dimensions[] |
list |
[Opcjonalnie] Co najmniej 1 wymiar, według którego 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 „data” i „godzina”. Wartości wymiarów grupowania są łączone, aby utworzyć unikalny 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żna grupować, ale nie można grupować według tego samego wymiaru 2 razy. Przykład: [country, device] | |
searchType |
string |
Wycofane, użyj type
|
|
type |
string |
[Opcjonalnie] Filtruj wyniki według tego typu:
|
|
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 jeden z nich. | |
dimensionFilterGroups[].groupType |
string |
Określa, czy wszystkie filtry w tej grupie muszą zwracać wartość „true” („and”), czy też co najmniej 1 filtr musi zwracać wartość „true” (jeszcze nieobsługiwane).
Akceptowane wartości:
|
|
dimensionFilterGroups[].filters[] |
list |
[Opcjonalnie] Co najmniej 1 filtr 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 ma zastosowanie 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] Sposób, w jaki podana wartość musi pasować (lub nie pasować) do wartości wymiaru w wierszu.
Akceptowane wartości:
|
|
dimensionFilterGroups[].filters[].expression |
string |
Wartość, którą filtr ma dopasować lub wykluczyć, w zależności od operatora. | |
dimensionFilterGroups[].filterLists[] |
list |
[Opcjonalnie] Co najmniej 1 filtr wymiaru wielowartościowego do przetestowania w wierszu.
W odróżnieniu od operatora filters[], który dopasowuje pojedynczą wartość na wpis, operator filterLists[] umożliwia dopasowanie wielu wartości dopasowania ścisłego dla pojedynczego wymiaru w jednym filtrze. Wiersz pasuje do listy filtrów, jeśli jego wartość dla określonego dimension jest równa dowolnej z podanych wartości expressions. Pamiętaj, że pojedyncze żądanie nie może filtrować według tego samego wymiaru jednocześnie w filters i filterLists. |
|
dimensionFilterGroups[].filterLists[].dimension |
string |
[Wymagane] Wymiar, do którego ma zastosowanie ta lista filtrów.
Akceptowane wartości:
|
|
dimensionFilterGroups[].filterLists[].expressions[] |
list |
[Wymagane] Lista wartości (string), według których ma być filtrowane. |
|
aggregationType |
string |
[Opcjonalnie] Sposób agregowania danych. 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 identyfikatora URI. Jeśli filtrujesz lub grupujesz według strony, wybierz opcję automatyczną. W przeciwnym razie możesz agregować według usługi lub strony, w zależności od tego, jak chcesz obliczać dane. Aby dowiedzieć się, jak dane są obliczane w przypadku witryny, a jak w przypadku strony, zapoznaj się z dokumentacją pomocy. Uwaga: jeśli grupujesz lub filtrujesz według strony, nie możesz agregować według usługi. Jeśli podasz wartość inną niż auto, typ agregacji w wyniku będzie zgodny z żądanym typem. 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:
|
|
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 |
[Opcjonalny; domyślnie 0] Indeks pierwszego wiersza w odpowiedzi (liczony od 0). Nie może być liczbą ujemną. Jeśli wartość startRow przekracza liczbę wyników zapytania, odpowiedź będzie pomyślna i będzie zawierać 0 wierszy. |
|
dataState |
string |
[Opcjonalnie] Jeśli „all” (wielkość liter nie jest rozróżniana), dane będą zawierać najnowsze dane. Jeśli podasz wartość „final” (wielkość liter nie jest rozróżniana) lub pominiesz ten parametr, zwrócone dane będą zawierać tylko sfinalizowane dane. Jeśli „hourly_all” (wielkość liter nie jest rozróżniana), dane będą zawierać podział godzinowy. Wskazuje ona, że dane godzinowe zawierają dane częściowe i powinna być używana podczas grupowania według wymiaru HOUR interfejsu 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 jednym wierszu. Jeśli na przykład grupujesz według wymiaru kraju, wszystkie wyniki dla „usa” zostaną zgrupowane razem, wszystkie wyniki dla „mdv” zostaną zgrupowane razem itd. Jeśli pogrupujesz dane według kraju i urządzenia, wszystkie wyniki dla „USA, tablet” zostaną zgrupowane, wszystkie wyniki dla „USA, komórka” zostaną zgrupowane itd. W dokumentacji raportu Analityka wyszukiwania znajdziesz szczegółowe informacje o tym, jak obliczane są kliknięcia, wyświetlenia itp. oraz co oznaczają.
Wyniki są sortowane według liczby kliknięć w porządku malejącym, chyba że grupujesz według daty – wtedy są sortowane według daty w porządku rosnącym (od najstarszych do najnowszych). Jeśli 2 wiersze są sobie równe, kolejność sortowania jest dowolna.
Aby dowiedzieć się, jaka jest maksymalna liczba wartości, które mogą zostać zwrócone, zapoznaj się z 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 klucza w kolejności podanej w zapytaniu. | |
rows[].keys[] |
list |
Lista wartości wymiarów dla tego wiersza, 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 danym 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 agregacji wyników. Aby dowiedzieć się, jak dane są obliczane w różny sposób w przypadku witryny i strony, zapoznaj się z dokumentacją pomocy.
Akceptowane wartości:
|
|
metadata |
object |
Obiekt, który może zostać zwrócony z wynikami zapytania, dostarczający kontekst dotyczący stanu danych. Gdy prosisz o najnowsze dane (używając Wszystkie daty i godziny podane w tym obiekcie są w strefie czasowej Konkretne pole zwracane w tym obiekcie zależy od tego, jak dane zostały pogrupowane w żądaniu:
|
Wypróbuj
Użyj poniższego narzędzia APIs Explorer, aby wywołać tę metodę na danych na żywo i zobaczyć odpowiedź.