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

Введение в API

  • URL запроса
  • Авторизация
  • Формат взаимодействия - запрос
  • Формат взаимодействия - ответ
  • Ограничения
  • Объекты данных
  • URL запроса для обращения к серверу API

    Все запросы к API должны направляться на https://api.topvisor.com с помощью метода POST.
    URL запроса должен включать в себя следующие данные:

    	<!-- https://api.topvisor.com/{версия}/{формат}/{оператор действия}/{имя сервиса}[/{имя метода}] -->
    
    • Версия API (v2);
    • Формат возвращаемых данных (поддерживается только JSON);
    • Оператор действия
    • Имя сервиса
    • Имя метода (необязательно)
    • Заголовок: Content-type (необязательно, рекомендуется "application/json");
    • Заголовок: User-Id;
    • Заголовок: Authorization.

    Пример 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
    Content-type: ЛЮБОЙ_ДРУГОЙ // например 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 и их объектов описан в разделе Сервисы.

    Так к примеру сервис "Ключевые фразы" позволяет управлять такими объектами как "Ключевые фразы", "Группы" и "Папки".

    Каждый тип данных имеет свой набор характеристик. Пример типа данных Ключевые фразы