Требуется авторизация.
Запрашивайте данные о поисковом трафике, используя заданные вами фильтры и параметры. Метод возвращает строки, сгруппированные по заданным вами ключам строк (параметрам). Необходимо указать диапазон дат, включающий один или несколько дней.
Если в качестве одного из параметров выбрана дата, то дни, за которые нет данных, будут исключены из списка результатов. Чтобы узнать, за какие дни есть данные, выполните запрос без фильтров, сгруппированный по дате, за интересующий вас диапазон дат.
Результаты сортируются по количеству кликов в порядке убывания. Если у двух строк одинаковое количество кликов, они сортируются произвольным образом.
Пример вызова этого метода на Python можно найти здесь.
API ограничен внутренними лимитами Search Console и не гарантирует возврат всех строк данных, а только верхних.
Подробнее об ограничениях на объем доступных данных…
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"]
}Запрос
HTTP-запрос
POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query
Параметры
| Название параметра | Значение | Описание |
|---|---|---|
| Параметры пути | ||
siteUrl |
string |
URL ресурса, указанный в Search Console. Примеры:
http://www.example.com/ (для ресурса с префиксом в URL) или
sc-domain:example.com (для доменного ресурса).
|
Авторизация
Для выполнения этого запроса требуется авторизация как минимум в одной из следующих областей доступа. Подробнее…
| Область доступа |
|---|
https://www.googleapis.com/auth/webmasters.readonly |
https://www.googleapis.com/auth/webmasters |
Тело запроса
В теле запроса требуется предоставить следующую структуру данных:
{
"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
}| Название свойства | Значение | Описание | Примечания |
|---|---|---|---|
startDate |
string |
[Обязательный] Дата начала запрашиваемого диапазона дат в формате ГГГГ-ММ-ДД по тихоокеанскому времени (UTC - 7:00/8:00). Значение должно быть меньше или равно дате окончания. Это значение входит в диапазон. | |
endDate |
string |
[Обязательно] Дата окончания запрашиваемого диапазона дат в формате ГГГГ-ММ-ДД по тихоокеанскому времени (UTC - 7:00/8:00). Значение должно быть больше или равно дате начала. Это значение входит в диапазон. | |
dimensions[] |
list |
[Необязательно] Один или несколько параметров, по которым нужно сгруппировать результаты.Результаты группируются в том порядке, в котором вы указываете эти параметры. В dimensionFilterGroups[].filters[].dimension можно использовать любое название параметра, а также "date" и "hour". Значения параметров группировки объединяются, чтобы создать уникальный ключ для каждой строки результатов. Если параметры не указаны, все значения будут объединены в одну строку. Ограничений на количество оснований группировки нет, но группировать данные по одному и тому же параметру дважды нельзя. Пример: [country, device] | |
searchType |
string |
Устарело, используйте type
|
|
type |
string |
[Необязательно] Отфильтруйте результаты по следующим типам:
|
|
dimensionFilterGroups[] |
list |
[Необязательно] Ноль или более групп фильтров, которые нужно применить к значениям группировки измерений. Чтобы строка была возвращена в ответе, она должна соответствовать всем группам фильтров. В рамках одной группы фильтров можно указать, должны ли соответствовать все фильтры или хотя бы один. | |
dimensionFilterGroups[].groupType |
string |
Должны ли все фильтры в этой группе возвращать значение true ("и") или только один или несколько (пока не поддерживается).
Допустимые значения:
|
|
dimensionFilterGroups[].filters[] |
list |
[Необязательно] Фильтры, которые будут применяться к строке. Каждый фильтр состоит из названия параметра, оператора и значения. Максимальная длина – 4096 символов. Примеры:
country equals FRA query contains mobile use device notContains tablet |
|
dimensionFilterGroups[].filters[].dimension |
string |
Параметр, к которому применяется этот фильтр. Вы можете фильтровать данные по любому из перечисленных здесь параметров, даже если вы не используете этот параметр в качестве основания группировки.
Допустимые значения:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Необязательно] Как указанное вами значение должно соответствовать (или не соответствовать) значению параметра для строки.
Допустимые значения:
|
|
dimensionFilterGroups[].filters[].expression |
string |
Значение, которое фильтр должен включать или исключать в зависимости от оператора. | |
dimensionFilterGroups[].filterLists[] |
list |
Необязательный параметр. Ноль или более фильтров параметров с несколькими значениями, которые нужно применить к строке.
В отличие от оператора filters[], который сопоставляет одно значение на запись, оператор filterLists[] позволяет сопоставлять несколько значений точного соответствия для одного параметра в одном фильтре. Строка соответствует списку фильтров, если ее значение для указанного dimension равно любому из предоставленных expressions. Обратите внимание, что в одном запросе нельзя одновременно фильтровать один и тот же параметр в filters и filterLists. |
|
dimensionFilterGroups[].filterLists[].dimension |
string |
[Обязательный параметр] Параметр, к которому применяется этот список фильтров.
Допустимые значения:
|
|
dimensionFilterGroups[].filterLists[].expressions[] |
list |
[Обязательный параметр] Список значений (string), по которым выполняется фильтрация. |
|
aggregationType |
string |
[Необязательно] Как агрегируются данные. Если данные агрегируются по ресурсу, то объединяются все данные для одного ресурса. Если данные агрегируются по странице, то объединяются все данные для одного канонического URI. Если вы фильтруете или группируете данные по страницам, выберите auto. В противном случае вы можете агрегировать данные по ресурсу или по странице в зависимости от того, как вы хотите их рассчитывать. Подробнее о том, как рассчитываются данные по сайту и по странице… Примечание. Если вы группируете или фильтруете данные по страницам, то не сможете агрегировать их по ресурсам. Если вы укажете любое другое значение, кроме auto, тип агрегирования в результате будет соответствовать запрошенному типу. Если вы запросите недопустимый тип, то получите сообщение об ошибке. API никогда не изменит тип агрегирования, если запрошенный тип недействителен. Возможные значения:
|
|
rowLimit |
integer |
[Необязательный параметр. Допустимый диапазон: 1–25 000. Значение по умолчанию: 1000.] Максимальное количество строк, которые нужно вернуть. Для постраничного просмотра результатов используйте смещение startRow. |
|
startRow |
integer |
[Необязательный параметр. Значение по умолчанию – 0.] Индекс первой строки в ответе (начиная с нуля). Значение должно быть неотрицательным числом. Если значение startRow превышает количество результатов запроса, будет возвращен успешный ответ с нулевым количеством строк. |
|
dataState |
string |
Необязательный параметр. Если указано значение all (без учета регистра), то в данные будут включены недавние данные. Если указано значение final (без учета регистра) или параметр опущен, возвращаются только окончательные данные. Если указано значение hourly_all (без учета регистра), данные будут включать разбивку по часам. Это значение указывает на то, что почасовая статистика может быть неполной. Его следует использовать при группировке по параметру HOUR API. |
Ответ
Результаты группируются по параметрам, указанным в запросе. Все значения с одинаковым набором значений параметров будут сгруппированы в одну строку. Например, если вы группируете данные по параметру "Страна", то все результаты для США будут сгруппированы вместе, все результаты для Мальдивских островов – тоже и т. д. Если вы сгруппировали данные по стране и устройству, то все результаты для США и планшетов будут объединены в одну группу, для США и мобильных устройств – в другую и т. д. В документации по отчету "Анализ поисковых запросов" рассказывается, как рассчитываются клики, показы и другие показатели и что они означают.
Результаты сортируются по количеству кликов в порядке убывания. Если вы используете основание группировки по дате, то они сортируются по дате в порядке возрастания (сначала самые старые, затем самые новые). Если две строки имеют одинаковое значение, порядок сортировки будет произвольным.
Чтобы узнать максимальное количество значений, которые могут быть возвращены, посмотрите свойство rowLimit в запросе.
{
"rows": [
{
"keys": [
string
],
"clicks": double,
"impressions": double,
"ctr": double,
"position": double
}
],
"responseAggregationType": string
}| Название свойства | Значение | Описание | Примечания |
|---|---|---|---|
rows[] |
list |
Список строк, сгруппированных по значениям ключей в порядке, указанном в запросе. | |
rows[].keys[] |
list |
Список значений параметров для этой строки, сгруппированных по параметрам в запросе и в указанном в нем порядке. | |
rows[].clicks |
double |
Количество кликов для строки. | |
rows[].impressions |
double |
Количество показов для строки. | |
rows[].ctr |
double |
Показатель CTR для строки. Значения в диапазоне от 0 до 1, 0 включительно. | |
rows[].position |
double |
Средняя позиция в результатах поиска. | |
responseAggregationType |
string |
Как были агрегированы результаты. Подробнее о том, как рассчитываются данные по сайтам и по страницам…
Допустимые значения:
|
|
metadata |
object |
Объект, который может быть возвращен вместе с результатами запроса и содержит контекстную информацию о состоянии данных. Если вы запрашиваете недавние данные (используя Все даты и время в этом объекте указаны в часовом поясе Поле, возвращаемое в этом объекте, зависит от того, как вы сгруппировали данные в запросе:
|
Попробовать
Воспользуйтесь инструментом API Explorer ниже, чтобы применить этот метод к реальным данным и посмотреть, как он работает.