Пред. След.

Введение в API

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 // 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 и их объектов описан в разделе Сервисы.

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

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

Настройка столбцов