Измените язык, если вам нужно работать с Топвизором на другом языке. Язык интерфейса можно изменить в любое время в настройках аккаунта. Измените язык, если вам нужно работать с Топвизором на другом языке. 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. Индекс будет в параметре index.
Также region_index можно найти в адресной строке браузера в разделе Проверка позиций или в консоли разработчика.
{
	"limit": 10,
	"show_searchers_and_regions": "1"
}
Как увидеть позиции по отдельной группе или папке?
Добавьте фильтр group_id с id группы запросов или group_folder_id с id папки.

Папки и группы →
{
	"project_id": "5046129",
	"limit": 10,
	"regions_indexes": [
		"1"
	],
	"dates": [
		"2024-05-04",
		"2024-05-03"
	],
	"filters": [
		{
			"name": "group_id",
			"operator": "EQUALS",
			"values": [
				"28574159"
			]
		}
	]
}
Как увидеть запросы из определенного ТОПа? Например ТОП-10?
Используйте массив filter_by_positions, где укажите крайние позиции в ТОПе для фильтрации. То есть для того, чтобы увидеть позиции в ТОП‑10, нужно указать 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
{
	"project_id": "5046129",
	"limit": 10,
	"regions_indexes": [
		"1"
	],
	"dates": [
		"2024‑05‑04",
		"2024‑05‑03"
	],
	"positions_fields": [
		"relevant_url",
		"snippet"
	],
	"fields": [
		"volume:213:0:1"
	]
}
Как можно получить список всех регионов сервиса?
Получить все доступные регионы списком возможности нет, однако вы можете осуществить поиск по базе регионов с помощью get/system_2/common/regions
Подробнее о методе →
Например, с помощью запроса ниже мы узнаем ID, то есть region key, который можно использовать для добавления региона в проект.
{
	"limit": 10,
	"searcher_key": "1",
	"search": "филад"
}

Как получить процент запросов в ТОПе?
Используйте параметр show_top_by_depth типа int. Используйте 3 для ТОП-3, 1 для ТОП-1 и т.д. Процент запросов будет отображаться в конце списка возвращаемых данных.
{
	"limit": 10,
	"project_id": "5046129",
	"regions_indexes": [
		"1"
	],
	"dates": [
		"2024‑04‑10",
		"2024‑04‑19"
	],
	"show_top_by_depth": "3"
}
Как увидеть позиции по нескольким сайтам (конкурентам) в одном запросе? 
Используйте дополнительный параметр competitors_ids типа массив, в нем укажите id конкурентов, добавленных в настройках проекта.
Если вы хотите дополнительно получить историю по основному домену, чтобы сравнить ее с конкурентами, добавьте id проекта к списку id конкурентов в параметре competitors_ids.
{
	"limit": 10,
	"project_id": "5046129",
	"regions_indexes": [
		"1"
	],
	"dates": [
		"2024‑04‑10",
		"2024‑04‑19"
	],
	"competitors_ids": [
		"5046130",
		"5098972",
		"7471344"
	]
}
Как посмотреть процент выполнения проверки?
Укажите получаемое поле (field) positions_percent в методе get/projects_2/projects.
{
	"limit": 10,
	"fields": [
		"name",
		"positions_percent"
	]
}
Как можно запустить проверку?
Используйте метод 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 по определителю