API - программный интерфейс Панели управления Интернет-радио от Radio-Tochka.com

Документация к API

В этом разделе показано, как использовать API нашей панели управления Интернет-радио для получения информации о состоянии эфира и других данных у себя на сайте. Используя наш API Вы можете строить свои собственные скрипты и модули для сайта своего радио.

В результате запроса к API будут выданы данные в формате JSON/JSONP.

Вызов API происходит по адресу <адрес Вашей панели на сервере>/api/<параметры>, например: http://demo.radio-tochka.com:8080/api/djs/?limit=1.

На настоящий момент реализовн API к следующим ресурсам:

Сервер/Server - получение информации о серверах, созданных в панели управления
Канал/Channel - информация о каналах сервера (получения списка, битрейта и прочих данных)
История/History - история эфира
Диджей/DJ - информация о диджеях радио

Для каждого из ресурсов можно запросить их список, например:

/api/servers/ - получение списка серверов
/api/channels/ - список всех каналов
/api/djs/ - получение списка диджеев
/api/history/ - история эфира

Формат ответа сервера

{
    "meta": {
        "limit": <количество объектов на странице>,
        "next": <uri для получения слудеющей страницы>,
        "offset": <начиная с какого элемента нужно отдавать данные>,
        "previous": <uri для получения предыдущей страницы>,
        "total_count": <общее количество элементов>
    },
    "objects": [
        <объект 1>,
        <объект 2>,
        ...
        <объект n>
    ]
}

Можно изменять количество объектов в запросе и устанавливать лимиты выборки, манипулируя параметрами limit и offset.

Например:

/api/djs/?limit=1 - получить только одного (первого) диджея
/api/history/?limit=1 - текущая песня в эфире (первая в истории эфира)

Фильтрации запросов

Параметры фильтраций передаются как параметры GET-запроса.

Фильтры нужны для того, чтобы выбрать не все объекты, а конкретные, например список только активных диджеев. Для объектов доступны следующие фильтры:

Server - нет фильтров
Channel - [server <id сервера>]
History - [server <id сервера>]
DJ - [server <id сервера> | active <0|1> | connected <0|1> | on_air <0|1>], где:

active - включен ли диджей (может ли он подключаться к эфиру)
connected - подключен ли диджей в данный момент
on_air - если равно 1, значит диджей подключен, активен и сейчас находится в эфире.

Примеры фильтраций:

/api/djs/?limit=1?server=1&on_air=1 - получить данные о диджее в эфире на сервере 1
/api/channels/?server=1 - получить список каналов сервера 1
/api/history/?server=1&limit=1 - текущая песня в эфире сервера 1

Примеры использования API

Текущий трэк в эфире

В этом простом примере мы будем запрашивать каждые 5 секунд название текущего трека на радио и выводить его на странице.

<html>
  <body>
    <div id="track"></div>

    <script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
    <script>
     $( document ).ready(function() {
         function updateTrack(){
             $.ajax({
                 // Дополнительно передается два параметра
                 // callback & format для получения данных
                 // в формате JSONP. Это позволит преодолеть CORS ограничение
                 url: "http://demoaccount.s02.radio-tochka.com:8080/api/history/?server=1&limit=1&callback=callback&format=jsonp",
                 jsonp: "callback",
                 dataType: "jsonp",
                 method: "GET",
                 success: function( response ) {
                     var trackTitlte = response.objects[0].metadata;
                     $("#track").text(trackTitlte);
                 }
             });
         }
         updateTrack();
         setInterval(updateTrack, 5*1000);
     });
    </script>
  </body>
</html>

Загрузка радио станций из панели управления

/api/v2/servers/ - подгрузка всех радио-серверов из панели управления

/api/v2/channels/?server=1 - подгрузка радио-каналов радио сервера 1

Голосование за треки

Чтобы принять голос за трек, сначала необходимо загрузить его ID в базе треков. ID есть только для треков, закачанных в AutoDJ, поэтому голосовать слушатель может только за них. Если трек играет в прямом эфире - ID такого трека будет null и проголосовать за него возможности нет. Сначала нужно загрузить ID текущего трека GET запросом по URL /api/v2/history/?limit=10&offset=0&server=1 где limit - это количество треков истории воспроизведения на радио, которые Вам нужны. Если, например, нужен только текущий трек, то URL будет /api/v2/history/?limit=1&offset=0&server=1 плюс необходимо выставить параметр server в ID радио сервера, играющий трек с которого нужно загрузить. Если запрос прошел корректно, то в ответе сервера Вы получите ID текущего трека, например id: 577810.

Теперь, когда известен ID трека - POST запрос на URL /api/v2/music/577810/like/ поставит лайк, POST на /api/v2/music/577810/dislike/ поставит дизлайк, 577810 в URL поменяйте на соответствующий ID трека.

Авторизация в API

Для тех методов API, которые изменяют что-либо на сервере, необходимо получить API ключ.

Для получения API ключа необходимо отправить POST запрос на API

/api/v2/api-token-auth/

Со следующими данными:

{  
   "username":"логин аккаунта",
   "password":"пароль аккаунта"
}

В ответ будет отправлен API ключ, например:

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX"
}

Этот ключ необходимо включать в HTTP заголовок "Authorization:"

Authorization: JWT eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX

Переключение диджея на следующи трек

Для этого метода требуется авторизация

POST /api/v2/djs/<DJ_ID>/rewind/

Где DJ_ID - ID диджея в панели управления.

Удаление трека

Для этого метода требуется авторизация

POST /api/v2/music/remove/

Payload:
{"server_id":1,"files":[1193, ]}

Где server_id - ID сервера из панели управления, files - массив ID треков

Примеры использования API в виджетах

Исходные коды виджета заказа трэков доступны здесь

Исходные коды виджета текущего статуса радио доступны здесь

Информация

В раздел информации

Наш сервис

API программный интерфейс Интернет-радио