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 а также «дата». Значения группирующего измерения объединяются для создания уникального ключа для каждой строки результата. Если размеры не указаны, все значения будут объединены в одну строку. Нет ограничений на количество измерений, по которым можно группировать, но нельзя группировать по одному и тому же измерению дважды. Пример: [страна, устройство]
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 альфа-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 »: агрегированные значения по панели «Витрина новостей» . Его необходимо использовать в сочетании с фильтром searchAppearance NEWS_SHOWCASE и 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 [ Необязательно ] Если указано «все» (без учета регистра), данные будут включать свежие данные . Если «final» (без учета регистра) или если этот параметр опущен, возвращаемые данные будут включать только завершенные данные.

Ответ

Результаты группируются по размерам, указанным в запросе. Все значения с одинаковым набором значений измерения будут сгруппированы в одну строку. Например, если вы группируете по параметру «Страна», все результаты по запросу «США» будут сгруппированы вместе, все результаты по запросу «MDV» будут сгруппированы вместе и т. д. Если вы сгруппировали по стране и устройству, то будут сгруппированы все результаты по запросу «США, планшет», все результаты по запросу «США, мобильный телефон» и т. д. См. документацию по отчету 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 »: результаты были агрегированы по свойствам.

Попробуйте!

Используйте API-обозреватель ниже, чтобы вызвать этот метод для реальных данных и просмотреть ответ.

,

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

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

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

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

См. пример 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 а также «дата». Значения группирующего измерения объединяются для создания уникального ключа для каждой строки результата. Если размеры не указаны, все значения будут объединены в одну строку. Нет ограничений на количество измерений, по которым можно группировать, но нельзя группировать по одному и тому же измерению дважды. Пример: [страна, устройство]
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 альфа-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 »: агрегированные значения по панели «Витрина новостей» . Его необходимо использовать в сочетании с фильтром searchAppearance NEWS_SHOWCASE и 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 [ Необязательно ] Если указано «все» (без учета регистра), данные будут включать свежие данные . Если «final» (без учета регистра) или если этот параметр опущен, возвращаемые данные будут включать только завершенные данные.

Ответ

Результаты группируются по размерам, указанным в запросе. Все значения с одинаковым набором значений измерения будут сгруппированы в одну строку. Например, если вы группируете по параметру «Страна», все результаты по запросу «США» будут сгруппированы вместе, все результаты по запросу «MDV» будут сгруппированы вместе и т. д. Если вы сгруппировали по стране и устройству, то будут сгруппированы все результаты по запросу «США, планшет», все результаты по запросу «США, мобильный телефон» и т. д. См. документацию по отчету 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 »: результаты были агрегированы по свойствам.

Попробуйте!

Используйте API-обозреватель ниже, чтобы вызвать этот метод для реальных данных и просмотреть ответ.

,

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

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

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

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

См. пример 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 а также «дата». Значения группирующего измерения объединяются для создания уникального ключа для каждой строки результата. Если размеры не указаны, все значения будут объединены в одну строку. Нет ограничений на количество измерений, по которым можно группировать, но нельзя группировать по одному и тому же измерению дважды. Пример: [страна, устройство]
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 альфа-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 »: агрегированные значения по панели «Витрина новостей» . Его необходимо использовать в сочетании с фильтром searchAppearance NEWS_SHOWCASE и 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 [ Необязательно ] Если указано «все» (без учета регистра), данные будут включать свежие данные . Если «final» (без учета регистра) или если этот параметр опущен, возвращаемые данные будут включать только завершенные данные.

Ответ

Результаты группируются по размерам, указанным в запросе. Все значения с одинаковым набором значений измерения будут сгруппированы в одну строку. Например, если вы группируете по параметру «Страна», все результаты по запросу «США» будут сгруппированы вместе, все результаты по запросу «MDV» будут сгруппированы вместе и т. д. Если вы сгруппировали по стране и устройству, то будут сгруппированы все результаты по запросу «США, планшет», все результаты по запросу «США, мобильный телефон» и т. д. См. документацию по отчету 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 »: результаты были агрегированы по свойствам.

Попробуйте!

Используйте API-обозреватель ниже, чтобы вызвать этот метод для реальных данных и просмотреть ответ.

,

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

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

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

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

См. пример 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 а также «дата». Значения группирующего измерения объединяются для создания уникального ключа для каждой строки результата. Если размеры не указаны, все значения будут объединены в одну строку. Нет ограничений на количество измерений, по которым можно группировать, но нельзя группировать по одному и тому же измерению дважды. Пример: [страна, устройство]
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 альфа-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 »: агрегированные значения по панели «Витрина новостей» . Его необходимо использовать в сочетании с фильтром searchAppearance NEWS_SHOWCASE и 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 [ Необязательно ] Если указано «все» (без учета регистра), данные будут включать свежие данные . Если «final» (без учета регистра) или если этот параметр опущен, возвращаемые данные будут включать только завершенные данные.

Ответ

Результаты группируются по размерам, указанным в запросе. Все значения с одинаковым набором значений измерения будут сгруппированы в одну строку. Например, если вы группируете по параметру «Страна», все результаты по запросу «США» будут сгруппированы вместе, все результаты по запросу «MDV» будут сгруппированы вместе и т. д. Если вы сгруппировали по стране и устройству, то будут сгруппированы все результаты по запросу «США, планшет», все результаты по запросу «США, мобильный телефон» и т. д. См. документацию по отчету 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 »: результаты были агрегированы по свойствам.

Попробуйте!

Используйте API-обозреватель ниже, чтобы вызвать этот метод для реальных данных и просмотреть ответ.