Stat API

Stat API служит для предоставления провайдерам статистики взаимодействия абонентов с TMS в формате JSON.

В рамках Stat API доступно три эндпоинта для выполнения GET-запроса:

/api/stats/subscription - получение статистки по подпискам.
/api/stats/device - получение статистики по устройствам.
/api/stats/account - получение статистики по аккаунту.

Обязательными параметрами запросов для каждого эндпоинта являются начальная и конечная даты временного диапазона в формате yyyy-mm-dd (год-месяц-день) для которого запрашивается статистика. Если в системе зарегистрировано более одного провайдера, можно запросить выдачу статистики только для одного из них с помощью параметра provider_id. Если этот параметр не включён в запрос, то API вернёт запрашиваемую статистику для всех провайдеров, зарегистрированных в TMS.

В ответ на запрос статистки по любому из эндпоинтов система возвращает JSON-объект в котором обозначены начальная и конечная даты временного диапазона, для которого запрашивается статистика, а также массив provider_stat, содержащий объект запрашиваемой статистики для интересующего провайдера (или по одному такому объекту для каждого провайдера, зарегистрированного в системе, если их более одного и в запросе не указан параметр provider_id).

При использовании API ваша система должна проходить простую basic авторизацию, используя логин и пароль администратора. Cоветуем создать для этих целей отдельного администратора в TMS.

Для практической оценки возможностей сбора статистики, тестирования запросов и подробного ознакомления со Stat API в TMS предусмотрен Swagger UI, доступный по адресу https://<tms_server>/api/stats/swagger-ui/index.html

Статистика подписок

Пример запроса к Stats API для получения статистики по подпискам для провайдера c двумя активными тарифами и c provider_id = 1 в период со второго по четвертое июня 2025 года:

GET https://<tms_server>/api/stats/subscription?from=2025-06-02&to=2025-06-04&provider_id=1

Полученный от TMS ответ на него:

{
  "from": "2025-06-02",
  "to": "2025-06-04",
  "provider_stat": [
    {
      "provider_id": 1,
      "subscriptions_stat": [
        {
          "date": "2025-06-02",
          "subscriptions": [
            {
              "tariff_id": 1,
              "name": "Example_tariff_1",
              "enabled_count": 150,
              "enabled_device_count": 200,
              "active_count": 126,
              "disabled_count": 21,
              "enabled_account_with_devices": 150
            }
            {
              "tariff_id": 2,
              "name": "Example_tariff_2",
              "enabled_count": 100,
              "enabled_device_count": 121,
              "active_count": 74,
              "disabled_count": 3,
              "enabled_account_with_devices": 100
            }
          ]
        },
        {
          "date": "2025-06-03",
          "subscriptions": [
            {
              "tariff_id": 1,
              "name": "Example_tariff_1",
              "enabled_count": 160,
              "enabled_device_count": 211,
              "active_count": 150,
              "disabled_count": 21,
              "enabled_account_with_devices": 160
            },
            {
              "tariff_id": 2,
              "name": "Example_tariff_2",
              "enabled_count": 99,
              "enabled_device_count": 3,
              "active_count": 72,
              "disabled_count": 4,
              "enabled_account_with_devices": 99
            }
          ]
        }
      ]
    }
  ]
}

Элементы массива subscribtion_stat содержат в себе статистику по всем тарифам провайдера за соотвествующие даты в виде массивов subscriptions, объекты в которых имеют следующие поля:

tariff_id:: Идентификаитор тарифа.
name:: Наименование тарифа.
enabled_count:: Количество включенных абонентов с подпиской на этот тариф по состоянию на конец дня.
enabled_device_count:: Количество устройств, зарегистрированных у включенных аккаунтов по состоянию на конец дня.
active_count:: Количество аккаунтов, с которых за сутки осуществлялся просмотр хотя бы одного канала.
disabled_count:: Количество отключенных аккаунтов с подпиской на этот тариф по состоянию на конец дня.
enabled_account_with_devices:: Количество включенных аккаунтов с подпиской на этот тариф, к которым привязано как минимум к одно устройство по состоянию на конец дня.

Статистика устройств

Пример запроса к Stats API для получения статистики по устройствам для провайдера c provider_id = 1 в период со второго по четвертое июня 2025 года:

GET https://<tms_server>/api/stats/device?from=2025-06-02&to=2025-06-04&provider_id=1

Полученный от TMS ответ на него:

{
  "from": "2025-06-02",
  "to": "2025-06-04",
  "provider_stat": [
    {
      "provider_id": 1,
      "device_stat": [
        {
          "class": "phone",
          "live_hours": 4,
          "dvr_hours": 1,
          "live_minutes": 243,
          "dvr_minutes": 61,
          "unique_devices": 4
        },
        {
          "class": "stb",
          "live_hours": 153,
          "dvr_hours": 15,
          "live_minutes": 9180,
          "dvr_minutes": 903,
          "unique_devices": 170
        },
        {
          "class": "tv",
          "live_hours": 120,
          "dvr_hours": 30,
          "live_minutes": 7200,
          "dvr_minutes": 1800,
          "unique_devices": 102
        },
        {
          "class": "web",
          "live_hours": 3,
          "dvr_hours": 0,
          "live_minutes": 181,
          "dvr_minutes": 0,
          "unique_devices": 2
        }
      ]
    }
  ]
}

Элементы массива device_stat содержат статистику по использованию устройств конкретного класса в виде объектов, имеющих следующие поля:

class:: Класс устройства. На данный момент сбор обособленной статистики возможен для классов tv (приложения для Smart TV), phone (мобильные телефоны), stb (медиацентры), tablet (планшеты), web (веб-плеер TMS). Учёт статистики для конкретного класса устройств наинается со дня первого подключения устройства этого класса к TMS.
live_hours:: Время в часах, проведённое абонентами за просмотром трансляции телевидения с использованием устройств данного класса за запрошенный промежуток времени.
dvr_hours:: Время в часах, проведённое абонентами за просмотром архива DVR с использованием устройств данного класса за запрошенный промежуток времени.

Предупреждение

Поля live_hours и dvr_hours считаются устаревшими. При работе со Stat API следует использовать минутные поля, представленные ниже.
live_minutes:: Время в минутах, проведённое абонентами за просмотром трансляции телевидения с использованием устройств данного класса за запрошенный промежуток времени.
dvr_minutes:: Время в минутах, проведённое абонентами за просмотром архива DVR с использованием устройств данного класса за запрошенный промежуток времени.
unique_devices:: Количество уникальных устройств данного класса, использованных абонентами для просмотра контента за запрошенный промежуток времени.

Статистика просмотра каналов абонентами

Пример запроса к Stats API для получения статистики просмотра каналов абонентами для провайдера c provider_id = 1 в период со второго по четвертое июня 2025 года:

GET https://<tms_server>/api/stats/account?from=2025-06-02&to=2025-06-04&provider_id=1

Полученный от TMS ответ на него:

{
  "from": "2025-06-02",
  "to": "2025-06-04",
  "provider_stat": [
    {
      "providerId": 1,
      "account_stat": [
        {
          "account_id": 9,
          "account_contract": "",
          "channels": [
            {
              "channel_id": 1,
              "live_hours": 4,
              "dvr_hours": 0,
              "live_minutes": 240,
              "dvr_minutes": 0
            },
            {
              "channel_id": 2,
              "live_hours": 0,
              "dvr_hours": 0,
              "live_minutes": 2,
              "dvr_minutes": 0
            }
          ]
        }
      ],
      "channels": [
        {
          "id": 1,
          "name": "News Channel",
          "favorites": [
            1
          ]
        },
        {
          "id": 2,
          "name": "HD Classics",
          "favorites": [
            2
          ]
        }
      ],
      "favorites": [
        {
          "id": 1,
          "name": "News"
        },
        {
          "id": 2,
          "name": "Movies"
        }
      ]
    }
  ]
}

Элементы массива account_stat содержат объекты статистики просмотра каналов конкретными абонентами. В ответе также представлены перечни каналов (массив channels) и их тематик (массив favorites). В сочетании со сведениями, предоствленными в персональных отчётах, эти данные позволяют гибко производить оценку популярности у абонентов определенных тематик или составлять рейтинги просмотров телеканалов.

В объектах массива account_stat предусмотрены следующие поля:

account_id:

Идентификатор абонента в системе.

account_contract:

Строка, содержащая данные о договоре с абонентом.

channels:

Массив, содержащий объекты статистики для каналов, просмотренных абонентом за запрошенный промежуток времени. В каждом объекте статистики канала представлны следующие поля:

channel_id:: Идентификатор канала в системе.
live_hours:: Время в часах, проведённое данным абонентом за просмотром трансляции канала за запрошенный промежуток времени.
dvr_hours:: Время в часах, проведённое данным абонентом за просмотром архива DVR канала за запрошенный промежуток времени.

Предупреждение

Поля live_hours и dvr_hours считаются устаревшими. При работе со Stat API следует использовать минутные поля, представленные ниже.
live_minutes:: Время в минутах, проведённое данным абонентом за просмотром трансляции канала за запрошенный промежуток времени.
dvr_minutes:: Время в минутах, проведённое данным абонентом за просмотром архива DVR канала за запрошенный промежуток времени.

В объектах массива каналов (channels) предусмотрены следующие поля:

id:: Идентификатор канала в системе.
name:: Наименование канала.
favorites:: Массив идентификаторов тематик, соответствующих контентному наполнению данного канала.

В объектах массива тематик (favorites) предусмотрены следующие поля:

id:: Идентификатор тематики в системе.
name:: Наименование тематики.

Пример приложения для экспорта и анализа статистики

Пример экспортирования статистики на typescript https://github.com/tvip/tms-stat-viewer-example.

Также доступен веб интерфейс примера имплементации Stat API https://tvip.github.io/tms-stat-viewer-example.

Авторизоваться в веб интерфейсе можно используя адрес TMS, логин и пароль администратора.

Ниже приведены некоторые примеры отображения статистики.

В разделе Report options нужно выбрать Provider и период для отображения статистики.

Пример отображения Channels Stat:

Статистика Live и DVR просмотров:

Пример отображения Device Stat: