Search Analytics: query

Требуется авторизация.

Запрашивайте данные о поисковом трафике, используя заданные вами фильтры и параметры. Метод возвращает строки, сгруппированные по заданным вами ключам строк (параметрам). Необходимо указать диапазон дат, включающий один или несколько дней.

Если в качестве одного из параметров выбрана дата, то дни, за которые нет данных, будут исключены из списка результатов. Чтобы узнать, за какие дни есть данные, выполните запрос без фильтров, сгруппированный по дате, за интересующий вас диапазон дат.

Результаты сортируются по количеству кликов в порядке убывания. Если у двух строк одинаковое количество кликов, они сортируются произвольным образом.

Пример вызова этого метода на Python можно найти здесь.

API ограничен внутренними лимитами Search Console и не гарантирует возврат всех строк данных, а только верхних.

Подробнее об ограничениях на объем доступных данных…

Пример POST-запроса JSON:
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 [Необязательно] Отфильтруйте результаты по следующим типам:
  • discover. Раздел "Рекомендации".
  • googleNews – результаты с сайта news.google.com и из приложения "Google Новости" для Android и iOS. Не включает результаты с вкладки "Новости" в Google Поиске.
  • news – результаты поиска на вкладке "Новости" в Google Поиске.
  • image – результаты поиска на вкладке "Картинки" в Google Поиске.
  • "video": результаты поиска видео
  • web – [по умолчанию] фильтрация результатов на вкладке "Все" в Google Поиске. Не включает результаты из рекомендаций и Google Новостей.
  • webMultimodal – результаты поиска с помощью Google Объектива, функции "Обвести и найти" на Android и загрузки изображений в Google Поиск.
dimensionFilterGroups[] list [Необязательно] Ноль или более групп фильтров, которые нужно применить к значениям группировки измерений. Чтобы строка была возвращена в ответе, она должна соответствовать всем группам фильтров. В рамках одной группы фильтров можно указать, должны ли соответствовать все фильтры или хотя бы один.
dimensionFilterGroups[].groupType string Должны ли все фильтры в этой группе возвращать значение true ("и") или только один или несколько (пока не поддерживается).

Допустимые значения:
  • and – все фильтры в группе должны возвращать значение true, чтобы группа фильтров возвращала значение true.
dimensionFilterGroups[].filters[] list [Необязательно] Фильтры, которые будут применяться к строке. Каждый фильтр состоит из названия параметра, оператора и значения. Максимальная длина – 4096 символов. Примеры:
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string Параметр, к которому применяется этот фильтр. Вы можете фильтровать данные по любому из перечисленных здесь параметров, даже если вы не используете этот параметр в качестве основания группировки.

Допустимые значения:
  • country – фильтрация по стране, указанной с помощью трехбуквенного кода (ISO 3166-1 alpha-3).
  • "device": фильтрация результатов по указанному типу устройств. Допустимые значения:
    • КОМПЬЮТЕРЫ
    • МОБИЛЬНЫЕ УСТРОЙСТВА
    • ПЛАНШЕТЫ
  • page – фильтрация по указанной строке URI.
  • "query": фильтрация по указанной строке запроса.
  • "searchAppearance": фильтрация по определенной функции в результатах поиска. Чтобы посмотреть список доступных значений, выполните запрос с группировкой по параметру searchAppearance. Полный список значений и описаний также доступен в справочной документации.
  • brandedClassification – фильтрация результатов по указанной классификации брендированных запросов (поддерживается только оператор equals). Фильтрацию или группировку по параметру "brandedClassification" нельзя использовать в одном запросе с фильтром "query". Данные доступны с 21 февраля 2026 г. и только для ресурсов верхнего уровня с достаточным количеством запросов и показов (см. объявление о брендированных запросах). Допустимые значения:
    • БРЕНДИРОВАННЫЕ
    • NON_BRANDED
dimensionFilterGroups[].filters[].operator string [Необязательно] Как указанное вами значение должно соответствовать (или не соответствовать) значению параметра для строки.

Допустимые значения:
  • "contains": значение строки должно содержать ваше выражение или быть равно ему (без учета регистра).
  • equals: [по умолчанию] выражение должно точно соответствовать значению строки (с учетом регистра для параметров страницы и запроса).
  • "notContains": значение строки не должно содержать ваше выражение ни в качестве подстроки, ни в качестве полного совпадения (без учета регистра).
  • "notEquals": выражение не должно точно совпадать со значением строки (с учетом регистра для параметров страницы и запроса).
  • "includingRegex" – регулярное выражение с синтаксисом RE2, которому должно соответствовать значение.
  • "excludingRegex" – регулярное выражение с синтаксисом RE2, которое не должно совпадать.
dimensionFilterGroups[].filters[].expression string Значение, которое фильтр должен включать или исключать в зависимости от оператора.
dimensionFilterGroups[].filterLists[] list Необязательный параметр. Ноль или более фильтров параметров с несколькими значениями, которые нужно применить к строке. В отличие от оператора filters[], который сопоставляет одно значение на запись, оператор filterLists[] позволяет сопоставлять несколько значений точного соответствия для одного параметра в одном фильтре. Строка соответствует списку фильтров, если ее значение для указанного dimension равно любому из предоставленных expressions. Обратите внимание, что в одном запросе нельзя одновременно фильтровать один и тот же параметр в filters и filterLists.
dimensionFilterGroups[].filterLists[].dimension string [Обязательный параметр] Параметр, к которому применяется этот список фильтров.

Допустимые значения:
  • "country": фильтрация по указанным странам с использованием трехбуквенных кодов стран (ISO 3166-1 alpha-3).
  • "device": фильтрация по указанным типам устройств (DESKTOP, MOBILE, TABLET).
dimensionFilterGroups[].filterLists[].expressions[] list [Обязательный параметр] Список значений (string), по которым выполняется фильтрация.
aggregationType string

[Необязательно] Как агрегируются данные. Если данные агрегируются по ресурсу, то объединяются все данные для одного ресурса. Если данные агрегируются по странице, то объединяются все данные для одного канонического URI. Если вы фильтруете или группируете данные по страницам, выберите auto. В противном случае вы можете агрегировать данные по ресурсу или по странице в зависимости от того, как вы хотите их рассчитывать. Подробнее о том, как рассчитываются данные по сайту и по странице…

Примечание. Если вы группируете или фильтруете данные по страницам, то не сможете агрегировать их по ресурсам.

Если вы укажете любое другое значение, кроме auto, тип агрегирования в результате будет соответствовать запрошенному типу. Если вы запросите недопустимый тип, то получите сообщение об ошибке. API никогда не изменит тип агрегирования, если запрошенный тип недействителен.

Возможные значения:
  • "auto": [По умолчанию] Тип агрегирования определяется сервисом.
  • "byNewsShowcasePanel" – агрегированные значения по панелям "В фокусе". Этот оператор необходимо использовать в сочетании с фильтром NEWS_SHOWCASE searchAppearance и оператором type=discover или type=googleNews. Если вы группируете или фильтруете данные по страницам или фильтруете их по другому параметру searchAppearance, то вы не можете агрегировать их по параметру byNewsShowcasePanel.
  • "byPage" – агрегированные значения по URI.
  • byProperty – агрегированные значения по ресурсам. Не поддерживается для type=discover и type=googleNews
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 Как были агрегированы результаты. Подробнее о том, как рассчитываются данные по сайтам и по страницам…

Допустимые значения:
  • "auto"
  • byPage – результаты агрегированы по страницам.
  • "byProperty": результаты агрегированы по ресурсам.
metadata object

Объект, который может быть возвращен вместе с результатами запроса и содержит контекстную информацию о состоянии данных.

Если вы запрашиваете недавние данные (используя all или hourly_all для dataState), некоторые из возвращенных строк могут содержать неполные данные, поскольку они ещё собираются и обрабатываются. Этот объект метаданных помогает определить, когда именно начинается и заканчивается показ.

Все даты и время в этом объекте указаны в часовом поясе America/Los_Angeles.

Поле, возвращаемое в этом объекте, зависит от того, как вы сгруппировали данные в запросе:

  • first_incomplete_date (string) – первая дата, за которую данные все ещё собираются и обрабатываются. Формат: YYYY-MM-DD (расширенный формат ISO-8601 для местной даты).

    Это поле заполняется, только если в запросе для параметра dataState задано значение all, данные сгруппированы по параметру date, а запрошенный диапазон дат содержит неполные точки данных.

    Все значения после first_incomplete_date могут значительно измениться.

  • first_incomplete_hour (string) – первый час, за который данные ещё собираются и обрабатываются. Значение представлено в формате YYYY-MM-DDThh:mm:ss[+|-]hh:mm (расширенный формат даты и времени ISO-8601 со смещением).

    Это поле заполняется, только если в запросе dataState имеет значение hourly_all, данные сгруппированы по hour и запрошенный диапазон дат содержит неполные точки данных.

    Все значения после first_incomplete_hour могут значительно измениться.

Попробовать

Воспользуйтесь инструментом API Explorer ниже, чтобы применить этот метод к реальным данным и посмотреть, как он работает.