October 23, 2014

Daily statistics API

One of the most popular statistics for media servers in WMSPanel is daily statistics report. As our customers want to integrate our stats into their of workflow, our team provides pull API for obtaining the aggregated data.
Now we've made a pull API for daily stats in order to give more flexibility in data analysis.

All you need 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 create user-specific ID and key, 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 daily stats you will need 2 API calls.

  • Take data slices list for further operations. It will give IDs of slices for further re-use in other calls.
  • Request data for the selected data slice and dates range.

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 daily stats


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

Request parameters:

  • client_id - is [client_id] you've copied previously from UI
  • api_key - is [api_key] from UI
  • 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
  • data_slice - the "id" which you got from the previous request. If you have user-based authorization, then this parameter is optional - in this case the data will be selected by the slice where a user is assigned to.

Optional parameters:

You may also request data for separate server, just as you can in web UI.
  • server - is the ID of the server to filter data for. To get server ID, choose Servers menu, then go to server details and check its URL - the big ID would be the line you need. If no server is specified in request, the data is presented as described above.


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

Response example:

{
  "status" : "Ok",
  "stats" : [
    {
      "message_out" : 0,
      "mgh_viewers" : 0,
      "rtmp_viewers" : 39,
      "message_lost" : 0,
      "max_message_in_rate" : 51425008,
      "total_view_time" : 31044,
      "max_message_out_rate" : 370556200,
      "dvr_viewers" : 0,
      "date" : "2014-10-17",
      "dash_viewers" : 0,
      "message_in" : 0,
      "ice_viewers" : 0,
      "rtsp_viewers" : 6,
      "smooth_viewers" : 0,
      "viewers" : 96,
      "pd_viewers" : 0,
      "hds_viewers" : 0,
      "hls_viewers" : 51
    },
    {
      "message_out" : 0,
      "mgh_viewers" : 0,
      "rtmp_viewers" : 0,
      "message_lost" : 0,
      "max_message_in_rate" : 0,
      "total_view_time" : 17460,
      "max_message_out_rate" : 127307424,
      "dvr_viewers" : 0,
      "date" : "2014-10-20",
      "dash_viewers" : 0,
      "message_in" : 0,
      "ice_viewers" : 0,
      "rtsp_viewers" : 0,
      "smooth_viewers" : 0,
      "viewers" : 16,
      "pd_viewers" : 0,
      "hds_viewers" : 0,
      "hls_viewers" : 16
    }
  ]
}
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
  • mgh_viewers - MPEG-DASH connections
  • dvr_viewers - DVR connections
  • ice_viewers - Icecast connections
  • pd_viewers - progressive download connections
  • message_in - incoming traffic
  • message_out - outgoing traffic
  • message_lost - lost traffic
  • max_message_in_rate - maximum incoming bandwidth (transmission speed)
  • max_message_our_rate - maximum outgoing bandwidth (transmission speed)
  • total_view_time - total amount of view time

Q: I cannot run API call from command line.

A: Please check this FAQ forum post.


Please also check full WMSPanel API reference.

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


No comments:

Post a Comment