Измените язык, если вам нужно работать с Топвизором на другом языке. Язык интерфейса можно изменить в любое время в настройках аккаунта. Измените язык, если вам нужно работать с Топвизором на другом языке. ru Русский Выбрать

get/positions_2/history

Получает историю проверки позиций. Метод не работает с архивными проектами.

Параметры метода

Параметр Тип Описание По умолчанию
Обязательные
project_id int ID проекта
regions_indexes array(int) Индексы регионов
dates array of date Произвольные даты проверок
(dates является обязательным, если date1 и date2 не указаны)
date1, date2 date Крайние даты периода
(date1 и date2 являются обязательным, если dates не указан)
Дополнительные
fields array fields
of keywords
Возвращаемые поля объекта "Ключевая фраза"
competitors_ids array(int) ID конкурентов (или ID проекта), добавленных в настройках проекта
type_range enum(0, 1, 2, 3, 4, 5, 6, 7, 100)

Период дат

Возможные значения:

  • 0 — весь период без ограничений
  • 1 — только апдейты
  • 2 — период до 31 даты
  • 3 — две даты
  • 4 — одна дата
  • 5 — последняя дата каждого месяца
  • 6 — даты через равные промежутки
  • 7 — две последние даты проверок
  • 100 — произвольные даты (иcпользуется только с параметром dates)
2
count_dates int Максмальное число возвращаемых дат (не более 31)
only_exists_first_date boolean Отображать только ключевые фразы, присутствующие в первой проверке указанного периода
show_headers boolean Добавить в результат заголовки результатов 0
show_exists_dates boolean Добавить в результат даты, в которых были проверки 0
show_visitors boolean Добавить в результат данные об общем количество визитов по каждой проверке 0
show_top_by_depth int Добавить в результат данные по ТОПу указанной глубины по каждой проверке 0
positions_fields array('position', 'snippet', 'relevant_url', 'visitors')

Выбор столбцов данных с результатами проверки:

  • position — позиция запроса
  • snippet — сниппет
  • relevant_url — релевантная страница
  • visitors — количество визитов
filter_by_dynamic set('>', '<', '=') Фильтр по ключевым фразам, позиции которых поднялись/упали/не изменились за крайние даты периода
* работает при получении позиций по одному проекту, одному региону для более чем одной даты
filter_by_positions array of array(int, int) Фильтр по ключевым фразам, позиции которых входят в указанные промежутки

Пример запроса на получение истории позиций:

{
	"project_id": "5046129",
	"regions_indexes": [
		"1"
	],
	"dates": [
		"2023‑09‑10",
		"2023‑09‑14"
	],
	"limit": 10
}

Посмотреть в API Explorer

Как узнать regions_indexes?
Индекс региона можно узнать в настройках регионов проекта, используя метод get/projects_2/projects с дополнительным параметром show_searchers_and_regions.
Также region_index можно найти в адресной строке браузера в разделе Проверка позиций или в консоли разработчика.
{
	"limit": 10,
	"show_searchers_and_regions": "1"
}
Как увидеть позиции по отдельной группе или папке?
Добавьте фильтр group_id с id группы запросов или group_folder_id с id папки.

Папки и группы
Как увидеть позиции по определенному ТОПу? Например ТОП-10?
Используйте параметр filter_by_positions, где в массиве укажите крайние позиции в ТОПе для фильтрации. То есть для того, чтобы увидеть позиции в ТОП-10, нужно указать 0:1, 1:10
{
	"limit": 10,
	"project_id": "7357609",
	"regions_indexes": [
		"1"
	],
	"dates": [
		"2024-02-12"
	],
	"filter_by_positions": [
		"1",
		"10"
	]
}
Как получить по API еще частоту, релевантные страницы и сниппеты?
Частота: указать как получаемые данные volume:213:0:1, где параметр - volume, 213 - ключ региона, 0 - ключ ПС, 1 - индекс типа частоты.
Релевантные страницы: параметр positions_fields[] со значением relevant_url
Сниппеты: параметр positions_fields[] со значением snippet
Как можно получить список всех регионов сервиса?
Получить все доступные регионы списком возможности нет, однако вы можете осуществить поиск по базе регионов с помощью get/system_2/common/regions

Подробнее о методе
Как получить процент запросов в ТОПе?
Используйте параметр show_top_by_depth типа int. Процент запросов будет отображаться в конце списка возвращаемых данных.
Как увидеть позиции по нескольким сайтам (конкурентам) в одном запросе?
Используйте дополнительный параметр competitors_ids типа массив, в нем укажите id конкурентов, добавленных в настройках проекта.
Как посмотреть процент выполнения проверки?
Параметр positions_percent в методе projects_2/projects.
Как можно запустить проверку?
Необходимо использовать метод edit/positions_2/checker/go

Возвращаемые данные

Параметр Тип Описание
result (объект)
keywords array of keywords Отчет по ключевым словам и другие поля ключевых фраз
keywords.positionsData object(определитель => object) Данные по проверке
headers array Заголовки результатов (если show_headers = 1)
existsDates array(date) Даты, в которых были проверки (если show_exists_dates = 1)
visitors object(определитель => object) Данные об общем количество визитов по каждой проверке (если show_visitors = 1)
tops object(определитель => object) Данные по ТОПу указанной глубины по каждой проверке (если show_top_by_depth = N)
result.keywords[N].positionsData[date:projectId:regionIndex]
position int или string('‑‑') Позиция запроса
relevant_url string Релевантная страница
visitors int Количество визитов
result.headers (если show_headers = 1)
fieldsLabels array Объекты заголовков запрошенных полей (параметр fields)
positionsFields array Соответствует входному параметру positions_fields
dates array Даты проверок, вошедших в отчет
projects array Проекты (конкуренты) с их поисковыми системами и регионами
result.visitors (если show_visitors = 1)
%Y‑d‑m:project_id:region_index% int Количество визитов по определителю
result.tops (если show_top_by_depth = N)
%Y‑d‑m:project_id:region_index% int Процент ключевых фраз в ТОП‑N по определителю