Search Analytics: query

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

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

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

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

См. пример вызова этого метода на Python .

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

Ознакомьтесь с ограничениями на объем доступных данных .

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

Допустимые значения:
  • " and ": Все фильтры в группе должны возвращать значение true для группы фильтров t быть правдой.
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". Полный список значений и их описания также доступны в справочной документации .
dimensionFilterGroups[].filters[]. operator string [ Необязательно ] Как указанное вами значение должно соответствовать (или не соответствовать) значению измерения для строки.

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

[ Необязательно ] Как агрегируются данные. При агрегации по свойству агрегируются все данные для этого свойства; при агрегации по странице все данные агрегируются по каноническому URI. Если вы фильтруете или группируете по странице, выберите «Авто»; в противном случае вы можете агрегировать либо по свойству, либо по странице, в зависимости от того, как вы хотите рассчитать данные; см. справочную документацию , чтобы узнать, чем отличается расчёт данных по сайту и по странице.

Примечание: при группировке или фильтрации по странице невозможно выполнить агрегацию по свойству.

Если указать любое значение, отличное от 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; Значение по умолчанию: 1 000 ] Максимальное количество возвращаемых строк. Для пролистывания результатов используйте смещение startRow .
startRow integer [ Необязательно; Значение по умолчанию: 0 ] Индекс первой строки ответа (отсчитывается от нуля). Должен быть неотрицательным числом. Если startRow превышает количество результатов запроса, ответ будет успешным и не будет содержать ни одной строки.
dataState string [ Необязательно ] Если указано «all» (без учета регистра), данные будут включать свежие данные . Если указано «final» (без учета регистра) или этот параметр пропущен, возвращаемые данные будут включать только финализированные данные. Если указано «hourly_all» (без учета регистра), данные будут включать почасовую разбивку. Это будет означать, что почасовые данные включают частичные данные и должны использоваться при группировке по измерению API HOUR.

Ответ

Результаты группируются в соответствии с параметрами, указанными в запросе. Все значения с одинаковым набором параметров будут сгруппированы в одну строку. Например, при группировке по параметру «страна» будут сгруппированы все результаты по запросу «usa», все результаты по запросу «mdv» и т. д. При группировке по параметру «страна и устройство» будут сгруппированы все результаты по запросу «usa, tablet», все результаты по запросу «usa, mobile» и т. д. Подробнее о том, как рассчитываются клики, показы и т. д., и что они означают, см. в документации по отчётам Search Analytics.

Результаты сортируются по количеству кликов в порядке убывания, если только вы не группируете по дате. В этом случае результаты сортируются по дате в порядке возрастания (сначала самые старые, затем самые новые). Если две строки совпадают, порядок сортировки произвольный.

См. Свойство 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 ниже, чтобы вызвать этот метод для реальных данных и увидеть ответ.