home.md

+# Web http API
+
+Сервер с API расположен по адресу `https://api.radioplayer.ru`
+
+API защищено токеном, уникальным для каждого партнёра. Токен необходимо передавать в query части любого запроса как параметр ?rp-api-token=XXXXXXXXXXXX Например: https://api.radioplayer.ru/api/web/stations?region=78&rp-api-token=Hh6d9cUaQfPDQ4dfG9pZe5TPVXRsPKva
+
+Все данные надо присылать в формате JSON, проставляя заголовок `Content-Type: application/json`. Возвращаемые данные также в формате JSON (если они есть).
+
+Сейчас доступны следующие методы.
+
+---
+
+### Отправка сообщения
+
+`POST`:`/api/web/message`
+
+Формат body:
+
+```
+{
+    "name": yup.string().trim().max(255).required(),
+    "email": yup.string().trim().max(255).required(),
+    "message": yup.string().trim().max(10000).required(),
+}
+```
+
+Возвращает 200 статус, если все ок.
+
+---
+
+### Получение региона по координатам
+
+`GET`: `/api/web/region?latitude=42.15546&longitude=54.13456`
+
+Возвращается объект JSON вида:
+
+```
+{ "id": 40, "name": "Москва" }
+```
+
+или `null` если ничего не было найдено.
+
+---
+
+### Получение списка регионов
+
+`GET`: `/api/web/regions`
+
+Возвращает массив регионов. Объект региона имеет вид:
+
+```
+{ "id": 1, "name": "Россия", "code": "RUS" }
+```
+
+---
+
+### Получение станций по id региона
+
+`GET`: `/api/web/stations?region=40`
+
+Возвращает массив станций, где все федеральные заменены на региональные для указанного региона, в случае если региональные потоки существуют.
+
+- Объект станции внутри массива содержит следующие поля:
+    - **id:** уникальный идентификатор станции
+    - **name:** название станции
+    - **source:** ссылка на поток *(зависит от региона)* Может содержать массив ссылок на равнозначные потоки. В случае если вместо одной ссылки указан массив, то запускать проигрывание можно любой из них
+    - **mobileSourceUrl:** ссылка на поток для плеера мобильного приложения. Формат m3u8 или json
+    - **reserveSourceUrl**: ссылка на резервный поток (зависит от региона)
+    - **logoWhite:** ссылка на белый логотип станции
+    - **logoBlack:** ссылка на тёмный логотип станции
+    - **logoColored:** ссылка на цветной логотип станции
+    - **socialLinks**: массив объектов веб-ресурсов станции со следующими полями
+        - **type**: тип веб-ресурса
+        - **url**: URL веб-ресурса
+    - **metadata:** *(не обязательное поле)* объект который может содержать в себе два поля. С их помощью по схеме [https://hostingradio.ru/mdsabout](https://hostingradio.ru/mdsabout) можно обновлять текущие метаданные для потока.
+        - **jsonUrl:** ссылка на json с полным описанием метаданных в потоке (сервер может отвечать долго)
+        - **uniqueIdJsonUrl:** *(не обязательное поле)* ссылка на идентификатор текущих метаданных. Служит для частого опроса на предмет изменений jsonUrl. Если идентификатор текущих метаданных меняется, то в этом случае нужно запрашивать jsonUrl. Есть не у всех станций. Отвечает в большинстве случаев быстро.
+    - **googleAnalytics:** *(не обязательное поле)* идентификатор станции для google аналитики
+    - **yandexMetrica:** *(не обязательное поле)* идентификатор станции для yandex метрики
+    - **frequency:** *(не обязательное поле)* частота вещания станции в текущем регионе. Для федеральных потоков отсутствует.
+    - **tags:** теги станции для поиска.
+    - **enabled:** доступность станции - значение false в случае если не доступен региональный поток и не доступен федеральный поток станции.
+
+Данный метод получает только те станции, которые вещают в FM-диапазоне / имеют федеральное или региональное вещание. Для получения списка цифровых станций необходимо дополнительно использовать метод [ниже](https://www.notion.so/Web-http-API-cd35dbf96fb140319c48efbef836851a).
+
+---
+
+### Получение списка цифровых станций
+
+`GET`: `/api/web/digital`
+
+Возвращает список цифровых станций, не имеющих FM-частоты.
+
+Вещание цифровых станций одинаково для любого региона. Формат отдаваемых данных [соответствует формату данных при получении станций по id региона](https://www.notion.so/Web-http-API-cd35dbf96fb140319c48efbef836851a).
+
+### Получение глобальных настроек
+
+`GET`: `/api/web/options`
+
+Возвращает объект вида:
+
+```
+{
+   "googleAnalytics": "IDENTIFIER_HERE",
+   "yandexMetrica": "IDENTIFIER_HERE",
+   "lastModifyTs": "UNIXTIME"	
+}
+```
+
+---
+
+### Отправка статистики при добавлении (удалении) станции в избранное
+
+`POST`: `/api/web/favorite`
+
+В body надо поместить JSON вида:
+
+```
+{
+   "stationId": 100500,
+   "liked": 1/0, // 0 если удалил из избранного
+}
+```
+
+Возвращает статус 200 если все ок.
+
+---
+
+### Ошибки
+
+При ошибках всегда приходит не 200 статус (обычно 500) и JSON вида:
+
+```
+{
+    "status": status,
+    "message": message,
+}
+```
\ No newline at end of file