October 23, 2014

Players and devices statistics API

WMSPanel gives statistics for media servers which include statistics for players and devices. 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 players and devices 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 players statistics


Request URL:
https://api.wmspanel.com/v1/players_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. If the stream ID is specified with server ID, this will show real-time stats for specific stream on a specific server.

Request example:
http://api.wmspanel.com/v1/players_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" : [
    {
      "Safari" : 9,
      "Unknown" : 45,
      "date" : "2014-10-17",
      "MSIE" : 3,
      "Flash" : 39
    },
    {
      "Safari" : 12,
      "Unknown" : 0,
      "date" : "2014-10-20",
      "MSIE" : 4,
      "Flash" : 0
    }
  ]
}

Response fields:
  • date - the day for which the data is exposed
  • Unknown - total amount of connections from unknown players
  • Flash  - total mount of Flash players
  • Safari, MSIE, Chrome etc. - numbers of connections for known browsers and players.
If some players were not used, they won't appear in results.
If some day does not have results, won't appear in results.

4. Get devices statistics


Request URL:
https://api.wmspanel.com/v1/devices_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. If the stream ID is specified with server ID, this will show real-time stats for specific stream on a specific server.

Request example:
http://api.wmspanel.com/v1/devices_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" : [
    {
      "iPhone" : 6,
      "iPad" : 6,
      "Macintosh" : 3,
      "Unknown" : 21,
      "Linux" : 12,
      "date" : "2014-10-17",
      "Windows" : 48
    },
    {
      "Unknown" : 0,
      "date" : "2014-10-20",
      "Windows" : 16
    }
  ]
}

Response fields:
  • date - the day for which the data is exposed
  • Unknown - total amount of connections from unknown devices
  • Windows, Linux etc. - total mount of connections from mentioned OSes
  • iPad, iPhone, SmartTV etc. - total mount of connections from mentioned devices

If some devices were not used, they won't appear in results.
If some day does not have results, won't appear in results.

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