Api topvisor – Документация для разработчиков — API Топвизор

Введение в API — API Топвизор

  • URL запроса
  • Авторизация
  • Формат взаимодействия — запрос
  • Формат взаимодействия — ответ
  • Ограничения
  • Объекты данных
  • 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.

    Данные могут передаваться в теле запроса двумя способами: JSON или form-data.

    Примеры заголовка запроса, устанавливающего тип передаваемых данных:

    Content-type: application/json // JSON
    Content-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

    Список возможных ошибок — API Топвизор

    Код ошибки Описание Возможные причины
    Другие ошибки
    0 Нетипизированные ошибки Описание ошибки см. в ответе API
    503 Функции API временно недоступны На сервере ведутся технические работы
    429 Превышен лимит одновременных обращений к API
    • С одного IP поступило более 5 одновременных запросов
    • Для одного User-Id поступило более 5 одновременных запросов
    10001 Внутренняя ошибка
    Ошибки авторизации
    53 Ошибка авторизации
    • Авторизационный токен не указан или указан неверно
      (заголовок Authorization)
    • ID пользователя не указан или указан неверно
      (заголовок User-Id)
    • Токен не соответствует ID пользователя
    54 Нет прав
    • Нет прав на просмотр запрашиваемых данных объекта
    • Нет прав на редактирование указанного объекта
    Неверное обращение к API
    1000 Неверное имя запроса Адрес запроса не соответствует формату:
    /v2/ajax/_operator_/_service_[/_method_]
    1001 Неверно указан оператор
    1002 Неверно указан сервис
    1003 Неверно указан метод
    • Указанный метод отсутствует в указанном сервисе
    • Указанный метод не соответствует указанному оператору
    1004 Неверная версия API
    Неверное значение поля
    2000 Ошибка в формате передаваемых данных
    2001 Отсутствует обязательный параметр
    2002 Указан параметр с неверным типом
    • Вместо числа передан другой тип
    • Вместо объекта передан другой тип
    2003 Указан параметр с неверным значением
    2004 Неверно указаны параметры фильтра fitlers
    • fitlers имеет неверную стркутуру
    • Элемент fitlers имеет неверный оператор
    • Элемент fitlers имеет неверный операнд
    2005 Неверно указаны параметры пагинации
    • limits или offset являются отрицательными
    • limits превышает 10000

    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 ПС

    Ключ Поисковой Системы:

    • 0 — Yandex
    • 1 — Google
    • 2 — go.Mail
    • 3 — Sputnik
    • 4 — YouTube
    • 5 — Bing
    • 6 — Yahoo
    • 7 — Seznam
    • 8 — AppStore
    • 9 — GooglePlay
    • 20 — Yandex.com
    • 21 — Yandex.com.tr
    region_key Ключ региона

    Ключ региона (города, области, страны или другого территориального объекта), идентифицирующий его в сервисе Топвизор.

    Ключ региона является уникальным в контексте всего сервиса.

    region_lang Язык региона Язык региона определяет язык интерфейса, на котором будет вестись проверка позиций.
    region_index Индекс региона

    Индекс региона определяет уникальный набор параметров searcher_key, region_key и region_lang.

    Индекс региона можно узнать в настройках регионов проекта, используя метод get/projects_2/projects.

    volume Частота запроса

    Частота запроса является составным полем и опредлеляется следующими характеристиками:

    • region_key — ключ региона
    • searcher_key — ключ ПС
    • type — номер формы частоты

    type может принимать следующие значения в зависимости от ПС:

    Яндекс:
    • 1 — Частота
    • 2 — «Частота»
    • 3 — «!Частота»
    • 5 — «[Частота]»
    • 6 — «[!Частота]»

    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)

    Период дат

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

    • 0 — весь период без ограничений
    • 1 — только апдейты
    • 2 — период до 31 даты
    • 3 — две даты
    • 4 — одна дата
    • 5 — последняя дата каждого месяца
    • 6 — даты через равные промежутки
    • 7 — две последние даты проверок
    • 100 — произвольные даты (иcпользуется только с параметром dates)
    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’)

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

    • 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

    Проекты — Сервисы API Топвизор

    Основные
    id int ID проекта
    user_id int ID пользователя
    name string Имя проекта
    site string URL сайта
    on int Статус проекта:
    • 0 — обычный проект
    • -1 — в архиве
    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 Фильтр:
    • 0 — без ограничений
    • 1 — умеренный фильтр
    • 2 — семейный поиск
    auto_correct int boolean Исправлять/не исправлять опечатки
    with_snippets int boolean Собирать/не собирать сниппеты
    do_snapshots int Снимки выдачи:
    • 0 — не собирать снимки выдачи
    • 2 — собирать снимки выдачи ТОП20
    • 3 — собирать снимки выдачи ТОП30
    • 5 — собирать снимки выдачи ТОП50
    • 9 — собирать снимки выдачи ТОП100
    Дополнительные настройки
    common_traffic int boolean Трафик
    • 0 — трафик по регионам
    • 1 — общий трафик
    guest_link_right string Опции гостевой ссылки
    Дополнительные
    broker_count_campaigns int Количество загруженных рекламных кампаний
    broker_count_banners int Количество активных объявлений
    broker_count_banners_off int Количество неактивных объявлений
    domain_expire object Информация о домене
    COUNT(*) int Число найденных объектов
    • Не имеет смысла использовать с другими полями
    • В результате будет возвращен один объект

    topvisor.com

    Добавить комментарий

    Ваш адрес email не будет опубликован. Обязательные поля помечены *