Документация API · Burnt planet Analytics

Что это за API

Этот API отдаёт готовую статистику прослушиваний, накопленную в базе сервера, — за всё время или за любой период — в разрезе трек × площадка × страна × дата. Ниже — как получить ключ и делать запросы.

Базовый URL

—

Авторизация

Заголовок X-API-Key

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

JSON

Быстрый старт (3 шага)

Получите API-токен у администратора системы. У каждой интеграции — свой уникальный ключ вида ma_….
Добавляйте токен в заголовок X-API-Key к каждому запросу.
Делайте GET-запросы к https://api.bpmusic.ru/api и получайте статистику в JSON.

Минимальный пример

curl -H "X-API-Key: ВАШ_ТОКЕН" "https://api.bpmusic.ru/api/stats/summary"

1. Авторизация

Токен передаётся в заголовке X-API-Key (рекомендуется) или query-параметром api_key. Права токена: read — чтение статистики, write — загрузка своих строк.

curl -H "X-API-Key: ma_ваш_токен" "https://api.bpmusic.ru/api/stats/data?limit=100"

2. Эндпоинты

Метод	Путь	Права	Описание
GET	/api/health	—	Проверка доступности сервера
GET	/api/status	—	Статус сервисов
GET	/api/stats/data	read	Строки статистики с фильтрами и постраничностью
GET	/api/stats/summary	read	Сводка: сколько записей, треков, прослушиваний, период
GET	/api/stats/top	read	Топ треков по прослушиваниям за период
GET	/api/last-parse	read	Дата последнего обновления данных и история
POST	/api/statistics	write	Загрузка своих строк статистики (внешние источники)

3. Параметры GET /api/stats/data

Все параметры необязательны. Без параметров возвращаются все записи за всё время (постранично).

Параметр	Пример	Описание
date_from	2026-01-01	Дата «с» (включительно), формат ГГГГ-ММ-ДД
date_to	2026-09-14	Дата «по» (включительно)
isrc	USRC11700463	Один ISRC трека
isrcs	A,B,C	Несколько ISRC через запятую
platform	Spotify	Площадка (частичное совпадение, без учёта регистра)
country	RU	Код страны
limit	1000	Строк за раз (по умолчанию 1000, максимум 50000)
offset	1000	Сколько строк пропустить (для пагинации)

4. Примеры запросов

Вся аналитика за всё время (первая страница)

curl -H "X-API-Key: ТОКЕН" \
"https://api.bpmusic.ru/api/stats/data?limit=50000&offset=0"

За определённый период

curl -H "X-API-Key: ТОКЕН" \
"https://api.bpmusic.ru/api/stats/data?date_from=2026-08-01&date_to=2026-08-31&limit=50000"

Один трек (по ISRC) за период

curl -H "X-API-Key: ТОКЕН" \
"https://api.bpmusic.ru/api/stats/data?isrc=USRC11700463&date_from=2026-01-01&date_to=2026-09-14"

Несколько треков сразу

curl -H "X-API-Key: ТОКЕН" \
"https://api.bpmusic.ru/api/stats/data?isrcs=USRC11700463,GBUM72100830"

По площадке и стране

curl -H "X-API-Key: ТОКЕН" \
"https://api.bpmusic.ru/api/stats/data?platform=Spotify&country=RU&limit=5000"

Сводка по всем данным

curl -H "X-API-Key: ТОКЕН" "https://api.bpmusic.ru/api/stats/summary"

Топ-50 треков за месяц

curl -H "X-API-Key: ТОКЕН" \
"https://api.bpmusic.ru/api/stats/top?date_from=2026-08-14&date_to=2026-09-14&limit=50"

Когда данные последний раз обновлялись

curl -H "X-API-Key: ТОКЕН" "https://api.bpmusic.ru/api/last-parse"

5. Пагинация (как забрать всё за всё время)

За один запрос возвращается не больше 50000 строк. Поле total — сколько всего строк подходит под фильтр. Чтобы забрать всё, увеличивайте offset на limit, пока не получите меньше строк, чем limit.

offset=0 → строки 1…50000
offset=50000 → строки 50001…100000
offset=100000 → строки 100001…150000
и так далее, пока не придёт пустой массив data

6. Примеры ответов

/api/stats/data

{ "total": 125000, "limit": 50000, "offset": 0, "data": [ { "Дата": "2026-09-13", "ISRC": "USRC11700463", "Название трека": "Example Track", "Название площадки": "Spotify", "Код страны": "RU", "Прослушивания": 1523, "Загружено": "2026-09-14T03:00:12.000Z" } ] }

/api/stats/summary

{ "total_records": 125000, "unique_dates": 240, "unique_tracks": 87, "unique_platforms": 12, "unique_countries": 45, "earliest_date": "2026-01-18", "latest_date": "2026-09-14", "total_plays": 9821543 }

/api/stats/top

{ "data": [ { "isrc": "USRC11700463", "track_name": "Example Track", "plays": 48213 }, { "isrc": "GBUM72100830", "track_name": "Another Track", "plays": 31980 } ] }

7. Примеры кода

JavaScript (fetch)

const res = await fetch("https://api.bpmusic.ru/api/stats/data?date_from=2026-08-01&date_to=2026-08-31&limit=50000", {
headers: { "X-API-Key": "ВАШ_ТОКЕН" }
});
const json = await res.json();
console.log("Всего строк:", json.total);
console.log(json.data);

Python (requests)

import requests

r = requests.get(
  "https://api.bpmusic.ru/api/stats/data",
  headers={"X-API-Key": "ВАШ_ТОКЕН"},
  params={"date_from": "2026-08-01", "date_to": "2026-08-31", "limit": 50000}
)
data = r.json()
print(data["total"], len(data["data"]))

8. Коды ответов и лимиты

200 — успех.
401 — токен не указан.
403 — токен недействителен, отключён, просрочен или не хватает прав.
429 — превышен лимит запросов (по умолчанию 300 запросов в минуту). Добавьте паузу между запросами.
Максимум 50000 строк за один запрос — используйте offset для пагинации.
Даты принимаются и возвращаются в формате ГГГГ-ММ-ДД.

9. Аналитика прокатов

Это отдельный источник данных — статистика прокатов треков в заведениях (фитнес-клубы, бары, кибер-клубы и т.д.). Данные накапливаются в базе сервера и отдаются через эндпоинты /api/places….

Это единая система с одним API: аналитика прокатов доступна по тому же единому ключу X-API-Key. Отдельных ключей для прокатов нет — один токен открывает и стриминговую статистику, и прокаты.

10. Эндпоинты прокатов

Метод	Путь	Права	Описание
GET	/api/places	read	Аналитика прокатов, сгруппированная по исполнителям (основной формат)
GET	/api/places/data	read	Плоский список прокатов с фильтрами и постраничностью
GET	/api/places/summary	read	Сводка: прокаты, исполнители, треки, места, города, период
GET	/api/places/imports	read	История загрузок отчётов и запусков

Параметры (для /api/places и /api/places/data)

Параметр	Пример	Описание
date_from	2026-08-01	Дата «с» (включительно), ГГГГ-ММ-ДД
date_to	2026-08-31	Дата «по» (включительно)
artist	Daria Kupr	Исполнитель (в /places — точное совпадение, в /places/data — частичное)
isrc	RUA1D2481418	ISRC трека
city	Москва	Город (только /places/data, частичное совпадение)
limit / offset	1000 / 0	Постраничность (только /places/data, максимум 50000)

11. Формат ответа /api/places

Массив исполнителей; у каждого — треки, у каждого трека — список прокатов (plays).

[ { "artist": "Daria Kupr", "total_plays": 128, "tracks": [ { "title": "Kiss Me", "isrc": "RUA1D2481418", "album": "Daria Kupr - Kiss Me", "count": 128, "plays": [ { "date": "31.05.2026 22:43:54", "place": "Крафт бар \"CLAW\"", "city": "Владимир", "address": "ул. Добросельская, д. 188" } ] } ] } ]

/api/places/summary

{ "total_plays": 80870, "unique_artists": 24, "unique_tracks": 33, "unique_places": 5120, "unique_cities": 340, "earliest_date": "2023-03-01", "latest_date": "2026-05-31" }

12. Примеры запросов (прокаты)

Вся аналитика прокатов (группировка по исполнителям)

curl -H "X-API-Key: ТОКЕН" "https://api.bpmusic.ru/api/places"

Прокаты за период

curl -H "X-API-Key: ТОКЕН" \
"https://api.bpmusic.ru/api/places?date_from=2026-08-01&date_to=2026-08-31"

По одному исполнителю

curl -H "X-API-Key: ТОКЕН" \
"https://api.bpmusic.ru/api/places?artist=Daria%20Kupr"

Плоский список с пагинацией

curl -H "X-API-Key: ТОКЕН" \
"https://api.bpmusic.ru/api/places/data?city=Москва&limit=5000&offset=0"

Сводка и история загрузок

curl -H "X-API-Key: ТОКЕН" "https://api.bpmusic.ru/api/places/summary"
curl -H "X-API-Key: ТОКЕН" "https://api.bpmusic.ru/api/places/imports"