August 5, 2014

WMSPanel real-time stats API

WMSPanel is often used as part of complex streaming infrastructure. This may require interaction between various system parts hence the need for application programming interface (API). Our team previously introduced a series of APIs like daily statistics push API, pay-per-view framework and RTMP publish/unpublish notifications. Now it's time to provide more statistics.

This article describes the real-time statistics API. It allows getting the data which is used for drawing real-time chart on a client dashboard for data slice and for a given stream.

Let's follow these steps to get the info.

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 real-time stats you will need 2 API calls. First you will take data slices list and then you will be able to request realtime data which you see on the dashboard.
Each call in 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 real-time data for a data slice


Real-time data is requested with required frequency and gives the same snapshot as you can get on data slice dashboard.

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

Request parameters:
  • client_id - Client ID you've copied previously from UI
  • api_key - API key from UI
  • data_slice - the "id" which you got from the previous request.
Optional parameters:

The real-time stats may be obtained for single stream. This is available for regular data slices only, as lite slices have no streams' real-time.
  • stream - this ID can be obtained in WMSPanel UI while looking at stream real-time stats. This ID which is also received by streams list request in deep stats API
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 one 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:
https://api.wmspanel.com/v1/realtime_data?client_id=[client_id]&api_key=[api_key]&data_slice=53e03c9978a6fc8596000001


Response example:
{
  "status" : "Ok",
  "realtime_data" : {
    "connected" : 1,
    "bandwidth" : 267784,
    "geo" : [
      [
        "BR",
        1
      ],
      [        "US",        1      ], 
    ]
  }
}

Response parameters:
  • connected - amount of connections,
  • bandwidth - current transmission speed
  • geo - top-20 countries of visitors, the series of sets like [alpha2, connected_count]

Q: I cannot run API call from command line.

A: Please check this FAQ forum post.


You can see mentioned JSON response examples in our API github repository. New API code samples will be added there as well.


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

No comments:

Post a Comment