Введение в API — API Топвизор
URL запроса для обращения к серверу API
Все запросы к API должны направляться на https://api.topvisor.com с помощью метода POST.
URL запроса должен включать в себя следующие данные:
<!-- https://api.topvisor.com/{версия}/{формат}/{оператор действия}/{имя сервиса}[/{имя метода}] -->
Пример URL запроса:
<!-- https://api.topvisor.com/{версия}/{формат}/{оператор действия}/{имя сервиса}[/{метод}] -->
https://api.topvisor.com/v2/json/get/user/profile/avatar
Доступ и авторизация
Для работы с API необходимо получить API Key.
Заголовки запроса для авторизации:
User-Id: %USER_ID%
Authorization: bearer %USER_API_KEY%
Формат передачи данных
Все данные должны передаваться в кодировке utf-8.
Примеры заголовка запроса, устанавливающего тип передаваемых данных:
Content-type: application/json // JSONContent-type: ЛЮБОЙ_ДРУГОЙ // form-data (не рекомендуется, например x-www-form-urlencoded)
Формат ответа
Ответ приходит в кодировке utf-8.
Поддерживается только один формат ответа: JSON.
{"result": /* результат */,"nextOffset": /* число (может отсутствовать) */,"total": /* число (может отсутствовать) */,"errors":[/* массив ошибок (может отсутствовать) */],"messages":[/* массив строк с информационными сообщениями (может отсутствовать) */]}
Подробнее о nextOffset и total читайте на странице постраничная выборка.
Подробнее об errors читайте на странице обработка ошибок.
Ограничение на использование API
- В одном запросе на получение данных можно запросить не более 10 000 результатов
- С одного IP не более 5 одновременных запросов
- Для одного User-Id не более 5 одновременных запросов
При превышении ограничения API вернет ошибку с кодом 429.
Объекты данных
API позволяет получать, изменять и удалять объекты различных типов. Каждый сервис работает со своим типом данных. Перечень всех сервисов API и их объектов описан в разделе Сервисы.
Так к примеру сервис «Ключевые фразы» позволяет управлять такими объектами как «Ключевые фразы», «Группы» и «Папки».
Каждый тип данных имеет свой набор характеристик. Пример типа данных Ключевые фразы
topvisor.com
API Версии 1. Руководство разработчика
Документация содержит описание программного интерфейса (API Топвизор), а также информацию о том, как использовать API, включая описание методов и используемых форматов данных. Руководство предназначено для разработчиков и вебмастеров, которым необходим доступ к данным и возможностям сервиса Топвизор.Адрес сервера и авторизация
Все действия в API Топвизор выполняется от имени зарегистрированного в сервисе пользователя. Клиентское приложение должно быть авторизовано посредством API ключа.Чтобы получить ответ на запрос, необходимо обратиться к серверу API по адресу:
https://api.topvisor.com/
Постраничный доступ к данным
Для получения большого объема данных рекомендуется использовать постраничный вывод результатов.Для этого в запросе на получение данных необходимо указать аргумент:
getFormat=json_pager.
| Аргумент | Описание | Возможные значения |
|---|---|---|
| getFormat | Формат данных | Всегда json_pager |
| limit | Количество возвращаемых объектов на одну страницу |
От 1 до ∞. Разные методы могут иметь различные ограничения по максимальному значению. |
| * page | Номер страницы | От 1 до ∞ |
| * offset | Количество пропускаемых объектов | От 0 до ∞ |
* можно использовать либо page либо offset, в зависимости от реализуемой задачи.
Не рекомендуется одновременное использование этих параметров.
Ответы сервера для постраничных запросов
I — при использовании использование page
{
page: 1, // номер полученной страницы
total: 5, // всего страниц
limit: 10, // количество результатов на 1 страницу
records: 55, // всего найденных результатов
rows: [] // массив результатов
}
II — при использовании offset
{
limit: 10, // количество результатов, возвращаемых 1 запросом
offset: 0, // пропущенно результатов
records: 55, // всего найденных результатов
rows: [] // массив результатов
}
topvisor.com
| Код ошибки | Описание | Возможные причины |
| Другие ошибки | ||
|---|---|---|
| 0 | Нетипизированные ошибки | Описание ошибки см. в ответе API |
| 503 | Функции API временно недоступны | На сервере ведутся технические работы |
| 429 | Превышен лимит одновременных обращений к API |
|
| 10001 | Внутренняя ошибка | |
| Ошибки авторизации | ||
| 53 | Ошибка авторизации |
|
| 54 | Нет прав |
|
| Неверное обращение к API | ||
| 1000 | Неверное имя запроса |
Адрес запроса не соответствует формату: /v2/ajax/_operator_/_service_[/_method_] |
| 1001 | Неверно указан оператор | |
| 1002 | Неверно указан сервис | |
| 1003 | Неверно указан метод |
|
| 1004 | Неверная версия API | |
| Неверное значение поля | ||
| 2000 | Ошибка в формате передаваемых данных | |
| 2001 | Отсутствует обязательный параметр | |
| 2002 | Указан параметр с неверным типом |
|
| 2003 | Указан параметр с неверным значением | |
| 2004 | Неверно указаны параметры фильтра fitlers |
|
| 2005 | Неверно указаны параметры пагинации |
|
topvisor.com
Поля объектов и их типы
Сервисы API работают с различными моделями данных.
Каждая модель данных содержит свой набор полей.
Списки моделей данных и полей представлены в разделе Сервисы API.
Типы полей
- int — число
- float — число с плавающей точкой
- string — строка
- date — строка с датой в формате: «yyyy-mm-dd»
- datetime — строка с датой и временем в формате: «yyyy-mm-dd hh:mm:ss»
- array — массив
- object — объект / ассоциативный массив
- set — одно или несколько значений (разделяемых запятой) из списка допустимых значений
- enum
- int boolean — 0 или 1
- array of int — массив из чисел
- array of float — массив из чисел с плавающей точкой
- array of string — массив из строк
- array of date — массив из значений date
- array of enum — массив из значений enum
Описания часто используемых полей
| Имя поля | Название | Описание |
| id | ID объекта | ID объекта, с типом которого ведется работа. |
| project_id | ID проекта | Идентификатор проекта используется для указания проекта, с которым должна вестись работа. |
| searcher_key | ПС |
Ключ Поисковой Системы:
|
| region_key | Ключ региона |
Ключ региона (города, области, страны или другого территориального объекта), идентифицирующий его в сервисе Топвизор. Ключ региона является уникальным в контексте всего сервиса. |
| region_lang | Язык региона | Язык региона определяет язык интерфейса, на котором будет вестись проверка позиций. |
| region_index | Индекс региона |
Индекс региона определяет уникальный набор параметров searcher_key, region_key и region_lang. Индекс региона можно узнать в настройках регионов проекта, используя метод get/projects_2/projects. |
| volume | Частота запроса |
Частота запроса является составным полем и опредлеляется следующими характеристиками:
type может принимать следующие значения в зависимости от ПС: Яндекс:
Google: |
topvisor.com
get/positions_2/history — Сервисы API Топвизор
Описание метода
Получает историю проверки позиций.
Метод не работает с архивными проектами.
Параметры метода
| Параметр | Тип | Описание | По умолчанию |
| Обязательные | |||
|---|---|---|---|
| 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) |
Период дат Возможные значения:
|
2 |
| count_dates | int | Максмальное число возвращаемых дат (не более 31) | |
| only_exists_first_date | int boolean | Отображать только ключевые фразы, присутствующие в первой проверке указанного периода | |
| show_headers | int boolean | Добавить в результат заголовки результатов | 0 |
| show_exists_dates | int boolean | Добавить в результат даты, в которых были проверки | 0 |
| show_visitors | int boolean | Добавить в результат данные об общем количество визитов по каждой проверке | 0 |
| show_top_by_depth | int | Добавить в результат данные по ТОПу указанной глубины по каждой проверке | 0 |
| positions_fields | array(‘position’, ‘snippet’, ‘relevant_url’, ‘visitors’) |
Выбор столбцов данных с результатами проверки:
|
|
| filter_by_dynamic | set(‘>’, ‘ |
Фильтр по ключевым фразам, позиции которых поднялись/упали/не изменились за крайние даты периода * работает при получении позиций по одному проекту, одному региону для более чем одной даты |
|
| filter_by_positions | array of array(int, int) | Фильтр по ключевым фразам, позиции которых входят в указанные промежутки | |
Посмотреть в API Explorer
Возвращаемые данные
| Параметр | Тип | Описание |
| 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 по определителю |
topvisor.com
Апометр — API Топвизор
| Действие | Параметры GET | Параметры POST | Ответ |
|---|---|---|---|
| Получить данные календаря Апометра |
&oper=get&module=mod_common &func=apometr_calendar |
date_month – дата, action – способ выдачи(1 — Яндекс XML, -1 — Яндекс SERP, 0 — обычная выдача для других поисковиков), searcher, region_key, region_lang |
{ date, Am, is_update, is_update_text } |
| Получить степень изменения выдачи по категориям |
&oper=get&module=mod_common &func=apometr_history |
date – дата, searcher – поисковик, region_key– регион, avg– получить средний балл по всем категориям |
{ id, pool, action, searcher, region_key, region_lang, Am, is_update, is_storm, time } |
| Получить данные календаря текстовых апдейтов |
&oper=get&module=mod_common &func=apometr_text_calendar |
date – дата |
Массив с индексами времени, внутри которых массивы с индексами дат со значением количества страниц в индексе Яндекса |
Описание результата метода apometr_history:
- id – идентификатор записи
- pool – категория
- 0 — Все категории
- 1 — Разработка сайтов и продвижение
- 2 — Авто, мото
- 3 — Юридические услуги
- 4 — Электронная и бытовая техника
- 5 — Недвижимость
- 6 — Промышленное оборудование, станки
- 7 — Мебель, окна
- 8 — Страхование
- 9 — Ремонт квартир, стройматериалы и инструменты
- 10 — Аренда автомобилей, такси, логистика
- 11 — Туризм и отдых
- 12 — Красота и здоровье
- 13 — Финансы
- 14 — Одежда и аксессуары
- 17 — Онлайн-игры
- action – способ выдачи
- 1 — Яндекс XML
- -1 — Яндекс SERP
- 0 — обычная выдача для других поисковиков
- region_key – регион
- region_lang – язык выдачи
- Am – степень изменения выдачи
- is_update – флаг — зафиксирован апдейт
- is_storm – флаг — зафиксирован шторм
- time – Unix время
Получить данные календаря Апометра на 2019-12-24 Яндекс SERP Санкт-Петербург:
https://api.topvisor.com/?api_key=Ваш_Ключ&oper=get&module=mod_common&func=apometr_calendar
&post[date_month]=2019-12-24&post[action]=-1&post[searcher]=0&post[region_key]=2
&post[region_lang]=ru
Получить степень изменения выдачи по категориям на 2019-12-31 в Яндексе по Санкт-Петербургу
https://api.topvisor.com/?api_key=Ваш_Ключ&oper=get&module=mod_common&func=apometr_history
&post[date_month]=2019-12-31&post[searcher]=0&post[region_key]=2
Получить данные календаря текстовых апдейтов
https://api.topvisor.com/?api_key=Ваш_Ключ&oper=get&module=mod_common&func=apometr_text_calendar
&post[date_month]=2019-12-31
topvisor.com
| Основные | ||
|---|---|---|
| id | int | ID проекта |
| user_id | int | ID пользователя |
| name | string | Имя проекта |
| site | string | URL сайта |
| on | int |
Статус проекта:
|
| date | string (YYYY-MM-DD) | Дата создания проекта |
| update | string (YYYY-MM-DD) | Дата последней проверки |
| right | string | Права на проект |
| favorite | int boolean | Избранный проект |
| tags | set(от 1 до 10) | Номер тега |
| user_email | string | Email владельца |
| Статусы | ||
| status_positions | int boolean |
Статус проверки позиций Если 1, то в ответ будет добавлен параметр percent_of_parse с процентом завершенности проверки |
| status_volumes | int boolean | Статус проверки частоты |
| status_claster | int boolean | Статус кластеризации | Настройки проверки позиций |
| subdomains | int boolean | Учитывать/не учитывать поддомены |
| filter | int |
Фильтр:
|
| auto_correct | int boolean | Исправлять/не исправлять опечатки |
| with_snippets | int boolean | Собирать/не собирать сниппеты |
| do_snapshots | int |
Снимки выдачи:
|
| Дополнительные настройки | ||
| common_traffic | int boolean |
Трафик
|
| guest_link_right | string | Опции гостевой ссылки |
| Дополнительные | ||
| broker_count_campaigns | int | Количество загруженных рекламных кампаний |
| broker_count_banners | int | Количество активных объявлений |
| broker_count_banners_off | int | Количество неактивных объявлений |
| domain_expire | object | Информация о домене |
| COUNT(*) | int |
Число найденных объектов
|
topvisor.com