Duration statistics API

WMSPanel provides various statistics for media servers which include playback duration statistics. As our customers need to integrate these stats into their of workflow, our team provides pull API for obtaining the aggregated data.
We introduce a pull API for duration metrics 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 duration 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 duration statistics

Request URL:
https://api.wmspanel.com/v1/duration_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 ine you need. If no server is specified in request, the data is presented as described above.

Request example:

http://api.wmspanel.com/v1/duration_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" : [
    {
      "up_to_20_secs" : 3,
      "up_to_2_hours" : 0,
      "more_than_3_hours" : 0,
      "total_view_time" : 31044,
      "up_to_15_secs" : 0,
      "up_to_15_mins" : 15,
      "up_to_10_secs" : 0,
      "up_to_5_secs" : 0,
      "date" : "2014-10-17",
      "up_to_5_mins" : 63,
      "up_to_1_hour" : 3,
      "up_to_30_secs" : 6,
      "up_to_30_mins" : 6,
      "viewers" : 96,
      "up_to_3_hours" : 0,
      "up_to_25_secs" : 0
    },
    {
      "up_to_20_secs" : 0,
      "up_to_2_hours" : 0,
      "more_than_3_hours" : 0,
      "total_view_time" : 17460,
      "up_to_15_secs" : 0,
      "up_to_15_mins" : 0,
      "up_to_10_secs" : 0,
      "up_to_5_secs" : 0,
      "date" : "2014-10-20",
      "up_to_5_mins" : 4,
      "up_to_1_hour" : 4,
      "up_to_30_secs" : 4,
      "up_to_30_mins" : 4,
      "viewers" : 16,
      "up_to_3_hours" : 0,
      "up_to_25_secs" : 0
    }
  ]
}

Response fields:

• date - the day for which the data is exposed
• viewers - total amount of connections
• total_view_time - total amount of view time
• up_to_5_secs - number of connections for up to 5 seconds
• up_to_10_secs - number of connections more than 5 seconds up to 10
• up_to_15_secs - up to 15 seconds
• up_to_20_secs - up to 20 seconds
• up_to_25_secs - up to 25 seconds
• up_to_30_secs - up to 30 seconds
• up_to_5_mins - up to 5 minutes
• up_to_15_mins - up to 15 minutes
• up_to_30_mins - up to 30 minutes
• up_to_1_hour - up to 1 hour
• up_to_2_hours - up to 2 hours
• up_to_3_hours - up to 3 hours
• more_than_3_hours  - more than 3 hours

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.

Related documentation

Media servers reporting, WMSPanel API reference, Daily stats API, Players and devices stats API, Real-time stats API, Daily stats push API, Pay-per-view framework,  User access for WMSPanel API,