📖 Аналитика 2.0 · Документация API
📈 Статус 🔐 Кабинет

Что это за API

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

Базовый URL
—
Авторизация
Заголовок X-API-Key
Формат ответа
JSON

Как собираются данные (парсер MusicAlligator)

Это происходит на сервере автоматически, по расписанию:

Актуальное состояние и время последнего парсинга можно проверить без токена: https://status.bpmusic.ru или GET https://api.bpmusic.ru/api/status.

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

  1. Получите API-токен у администратора системы. У каждой интеграции — свой уникальный ключ вида ma_….
  2. Добавляйте токен в заголовок X-API-Key к каждому запросу.
  3. Делайте 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/datareadСтроки статистики с фильтрами и постраничностью
GET/api/stats/summaryreadСводка: сколько записей, треков, прослушиваний, период
GET/api/stats/topreadТоп треков по прослушиваниям за период
GET/api/last-parsereadДата последнего парсинга и история запусков
POST/api/statisticswriteЗагрузка своих строк статистики (внешние источники)

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

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

ПараметрПримерОписание
date_from2026-01-01Дата «с» (включительно), формат ГГГГ-ММ-ДД
date_to2026-09-14Дата «по» (включительно)
isrcUSRC11700463Один ISRC трека
isrcsA,B,CНесколько ISRC через запятую
platformSpotifyПлощадка (частичное совпадение, без учёта регистра)
countryRUКод страны
sourceMusicAlligatorФильтр по источнику данных
limit1000Строк за раз (по умолчанию 1000, максимум 50000)
offset1000Сколько строк пропустить (для пагинации)

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, "Источник": "MusicAlligator", "Загружено": "2026-09-14T03:00:12.000Z" } ] }

7. Пример ответа /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 }

8. Пример ответа /api/stats/top

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

9. Пример на 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);

10. Пример на 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"]))

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