August 7, 2014

WMSPanel in-depth stats API

WMSPanel provides a wide variety of statistics for media servers. This includes In-depth statistics, or "Deep stats". This report gives a high detail picture of streaming, so no wonder that our users may need that for integration with their own assets management systems, administration consoles or public appearance.

This is why we introduce a pull API which will help integrating WMSPanel with any system which may need the streaming statistics. All you need to use it, is to make some setup on WMSPanel side and then make proper API calls using any programming technology you like.

Let's go step by step.

1. Set up API on WMSPanel side


To start using the API, you need to make small setup on WMSPanel side.

First, the API should be enabled by WMSPanel team, so please contact us to enable it for your account. Then you need to follow these steps:
  1. Go to Control menu -> API setup -> Pull API tab.
  2. Copy Client ID for further usage in your scripts.
  3. Click on "Generate New Key" to copy API key as well. This will be used for further authorization.
  4. Populate white list with IPs of the hosts where you will be making API call from, like your development machine or your web server. Just enter new IP and click on "Add IP to Whitelist" one by one.
Check this screenshot as a reference:




Setting up pull API parameters.

Another way for getting API ID and API key is to define them for separate users. This is useful when your client want to have direct access to his data. Read this article to learn more about it. Once you get user-specific ID and key the he may use them instead of account-wise client ID and API key. The data scope for this client ID and key will be limited to the client's data slices settings. All parameters mentioned below remain the same.

Now you're ready to request the data.

For streams stats you will need 3 API calls.

  • Take data slices list for further operations. It will give IDs of slices for further re-use in other calls.
  • Take streams list by the exact name or regexp.
  • Request stream data which you see in stream daily stats.

Each call is a GET request via HTTPS. You need to use HTTPS for all connections.
As a response you get JSON structure with required data.

If you have incorrect credentials for any request, the response code will be 403.

2. Get data slices list


You need to know your data slice ID in order to request stats for it. This ID does not change over time so you may obtain it just once and use it going forward.

Request URL:
https://api.wmspanel.com/v1/data_slices

Request parameters:
  • client_id - is [client_id] you've copied previously from UI
  • api_key - is [api_key] from UI

Request example:
https://api.wmspanel.com/v1/data_slices?client_id=[client_id]&api_key=[api_key]

Response example:
{
  "status" : "Ok",
  "data_slices" : [
    {
      "id" : "53e03c9978a6fc8596000001",
      "name" : "Full data slice"
    },
    {
      "id" : "53e03ca678a6fc8599000001",
      "name" : "DS2"
    }
  ]
}
Each data slice is described with the name and its unique ID for further usage.


3. Get streams list and total stats


Request URL:
https://api.wmspanel.com/v1/deep

Request parameters:

  • client_id - is [client_id] from UI
  • api_key - is [api_key] from UI
  • data_slice - data slice ID for further usage
  • from - report beginning date, the format is YYYY-MM-DD, e.g. 2014-08-01
  • to - report ending date with the same format, like 2014-12-31
  • stream - regex or full name of the stream to search for
  • top - how many streams to have in result output (20, 50, 100), it's 20 by default
  • kind - sort criteria: "played", "traffic", "view_time", "avg_view_time" (it's "played" by default)
  • sort - sorting mode: "least", "most" ("most" by default)
  • total - whether to aggregate results and make last line as the total amounts of values as it's made in Deep stats UI ("false" by default)

Request example:
https://api.wmspanel.com/v1/deep?client_id=[client_id]&api_key=[api_key]&data_slice=53e03ca678a6fc8599&from=2014-01-01&to=2014-12-31&stream=live&top=20&kind=traffic&sort=least&total=true

Response example:
{
  "status" : "Ok",
  "streams" : [
    {
      "played" : 1,
      "id" : -567265953,
      "traffic" : 0,
      "avg_view_time" : 1,
      "view_time" : 1,
      "name" : "localhost:8081/live/sample.mp4"
    },
    {
      "played" : 1,
      "id" : 884562081,
      "traffic" : 163643,
      "avg_view_time" : 80,
      "view_time" : 80,
      "name" : "_defaultVHost_/live/_definst_/stream"
    },
    {
      "played" : 2,
      "id" : 957567282,
      "traffic" : 44105071,
      "avg_view_time" : 400,
      "view_time" : 800,
      "name" : "localhost:8081/live/stream"
    },
    {
      "played" : 11,
      "id" : 458257673,
      "traffic" : 79347999,
      "avg_view_time" : 290,
      "view_time" : 3197,
      "name" : "localhost:8081/live/stream/video.ts"
    },
    {
      "played" : 29,
      "id" : 0,
      "traffic" : 149174693,
      "avg_view_time" : 197,
      "view_time" : 5723,
      "name" : "Total (5 streams)"
    }
  ]
}

Response fields:
  • played - amount of connections;
  • id - ID of the stream within WMSPanel, it's used for detailed stream-related requests;
  • traffic - bytes of traffic;
  • avg_view_time - average view time;
  • view_time - total view time;
  • name - public name of the stream, as appears in WMSPanel streams report.

4. Get single stream daily stats


Request URL:
http://api.wmspanel.com/v1/deep_daily

Request parameters:
  • client_id - is [client_id] from UI
  • api_key - is [api_key] from UI
  • data_slice - data slice ID for further usage
  • from - report beginning date, the format is YYYY-MM-DD, e.g. 2014-08-01
  • to - report ending date with the same format, like 2014-12-31
  • stream - the ID which is received by previous streams list request; this ID can also be obtained in WMSPanel UI while looking at stream real-time stats.

Request example:
http://api.wmspanel.com/v1/deep_daily?client_id=[client_id]&api_key=[api_key]&from=2014-01-01&to=2014-12-31&data_slice=53e03ca678a6fc8599&stream=957567282

Response example:
{
  "status" : "Ok",
  "stats" : [
    {
      "pd_viewers" : 6,
      "date" : "2014-08-01",
      "total_view_time" : 809,
      "hls_viewers" : 6,
      "message_out" : 41528276,
      "viewers" : 12,
      "message_in" : 68072
    },
    {
      "pd_viewers" : 12,
      "date" : "2014-08-02",
      "total_view_time" : 668,
      "hls_viewers" : 8,
      "message_out" : 65361320,
      "viewers" : 20,
      "message_in" : 69941
    },
    {
      "pd_viewers" : 4,
      "date" : "2014-08-03",
      "total_view_time" : 585,
      "hls_viewers" : 7,
      "message_out" : 29922755,
      "viewers" : 11,
      "message_in" : 43654
    },
    {
      "date" : "2014-08-04",
      "total_view_time" : 1075,
      "hls_viewers" : 13,
      "message_out" : 36573313,
      "viewers" : 13,
      "message_in" : 84323
    },
    {
      "pd_viewers" : 5,
      "date" : "2014-08-05",
      "total_view_time" : 1528,
      "hls_viewers" : 12,
      "message_out" : 66173365,
      "viewers" : 17,
      "message_in" : 107114
    },
    {
      "pd_viewers" : 8,
      "date" : "2014-08-07",
      "total_view_time" : 596,
      "hls_viewers" : 9,
      "message_out" : 28151857,
      "viewers" : 17,
      "message_in" : 44666
    },
    {
      "pd_viewers" : 24,
      "date" : "2014-08-06",
      "total_view_time" : 1575,
      "hls_viewers" : 34,
      "message_out" : 117408560,
      "viewers" : 58,
      "message_in" : 167024
    },
    {
      "date" : "2014-08-08",
      "total_view_time" : 108,
      "hls_viewers" : 2,
      "message_out" : 3487210,
      "viewers" : 2,
      "message_in" : 8456
    }
  ]
}

Response fields:
  • date - the day for which the data is exposed
  • viewers - amount of connection
  • hls_viewers - amount of connections via HLS
  • hds_viewers - HDS connections
  • smooth_viewers - SmoothStreaming connections
  • rtsp_viewers - RTSP connections
  • rtmp_viewers - RTMP connections
  • dash_viewers - MPEG-DASH connections
  • dvr_viewers - DVR connections
  • pd_viewers - progressive download connections
  • message_in - incoming traffic
  • message_out - outgoing traffic
  • message_lost - lost traffic
  • total_view_time - total amount of view time

If some protocol does not have stats, it is not included in the response.
If some day does not have stats, it is not included in the response.


Q: I cannot run API call from command line.

A: Please check this FAQ forum post.


Please also check full WMSPanel API reference for other API methods.

More APIs to come soon, so if you want to have more, just let us know about it.


No comments:

Post a Comment