Mesh Data API v3 Overview

The Mesh Data API securely exposes your data in JSON format allowing you to build your own dashboard or integrate relevant data into your workflows. The Mesh Data API allows you to query for different type of data, different metrics and dimensions. 

Metrics calculation

The Streamroot Data API returns four main metrics: traffic, bandwidth, audience and buffering rate.

Traffic

Traffic is the quantity of data downloaded by your viewers (in bytes) broken down between cdn and P2P. We only ever take into account video data that was added to the video player buffer.

Bandwidth

Bandwidth is the quantity of data downloaded by your viewers per second (in bits/sec).
Traffic data is collected and aggregated in 5-minute intervals and converted to bandwidth.

Audience

Audience is the number of concurrent viewers using our technology.
For every 2 minutes interval, we count the number of viewers who were actively using Streamroot technology. For a larger request window, we will return the maximum and average of distinct viewers in those 2 minutes intervals.

Buffering

We break the buffering rate into two metrics: 

• The Time Played: this is the aggregated time spent playing video by your audience for a given period. This only includes time where the video was actually playing (excluding buffering time & paused time)
• The Time Buffered: this is the aggregated time spent with a buffering video player by your audience for a given period. 

You can then easily calculate the buffering ratio for the period:
Buffering Rate = Time Buffered / (Time Played + Time Buffered).

Authentication

API Key

To use our data APIs you need to authenticate via API Key set in the Authorization HTTP header.

You will soon be able to manage your API Keys from Streamroot Dashboard - in the meantime you can send a request to support@streamroot.io to get an API Key for your account.

Once you have the key, simply add this header to your HTTP requests: 

Authorization: API-Key {YOUR_API_KEY}  

Customer ID

You will also need your Customer ID which can be found in the Company tab of the Profile section:

Requests parameters

You can filter the data returned by the API by passing parameters in the JSON body of the request.

Examples

1. The since param is used to convey an elapsed time since the time of the request. It is a string (no whitespaces in it) with the following alternatives:

• h means hour. Ex: 1h, 15h
• d means day. Ex:1d 3d
• w means week. Ex:1w 6w

For example:

{
 "since": "16h",
 "contentType": "all"
}

2. The from and to params accept either a date with the format YYYY-MM-DD or a Unix timestamp in milliseconds. For example:

{
 "from": "2020-01-28",
 "to": "2020-01-29",
 "contentType": "live"
}

{
 "from": "1584441900000",
 "to": "1584528300000",
 "contentType": "vod"
}

Errors

When an error occurs, the API returns a NON 200 HTTP status code along with a JSON payload containing a message explaining the origin of the failure. Here are some examples:

HTTP 400
{
  "message": "invalid since param"
}

HTTP 400
{
  "error": "invalid content type"
}

List of endpoints

All of the following endpoints are accessed via POST, to allow you to pass query parameters in the JSON body of the request.

dna/data/audience

Returns the aggregated audience numbers for the selected period.

Endpoint

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/audience

Request Body Example

{
 "from": "1584441300000", 
 "to": "1584527700000",
 "contentType": "all",
 "platform": "web-desktop"
}

Response Example

[
    {
        "srKey": "yourStreamrootKey",
        "max": 6809,          // Maximum number of concurrent viewers during the period
        "average": 1559       // Average number of concurrent viewers during the period
        "audience95th" : 1234 // 95th percentile of concurrent viewers during the period
    }
]

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/audience/timeseries

{
 "from": "1584441300000", 
 "to": "1584527700000",
 "interval" : "10m"
 "content": "mainContent/myVODstream.m3u8"
}

[
   {
      "srKey": "yourStreamrootKey",
      "audience": [
          [
            1584441000000, // Timestamp marking the beginning of the current interval
            17311 // Number of concurrent viewers during that interval
          ],
          [
            1584441600000,
            17479
          ],
          [
            1584442200000,
            16995
          ],
          ...
      ]
   }
]

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/traffic

{
 "from": "1584441300000", 
 "to": "1584527700000",
 "contentType": "all"
}

[
    {
        "srKey": "yourStreamrootKey",
        "cdn": 1.37629688435669e+14, // Bytes downloaded through CDN during the period
        "p2p": 1.41125192621073e+14 // Bytes downloaded through P2P during the period
    }
]

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/traffic/timeseries

{
 "from": "1584441300000", 
 "to": "1584527700000",
 "interval" : "10m"
 "contentType": "all"
}

[
   {
      "SrKey": "6fa93815-2dc9-4df6-9967-3bb108d14bb5",
      "p2p": [
          [
             1584441000000, // Timestamp marking the beginning of the current interval
             644588686300 // Bytes downloaded through P2P during the interval
          ],
          [
             1584441600000,
             1353212135116
          ],
          ...
       ],
       "cdn": [
          [
             1584441000000, // Timestamp marking the beginning of the current interval
             286686641593 // Bytes downloaded through CDN during the interval
          ],
          [
             1584441600000,
             613745948608
          ],
          ...
       ]
   }
]  

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/bandwidth

{
 "from": "1584441300000", 
 "to": "1584527700000",
 "contentType": "all"
}

[
   {
     "srKey": "yourStreamrootKey",
     "p2pAvegage": 2456328260, // Average P2P bandwidth during the period in bits/second
     "cdnMax": 6133702320, // Maximum CDN bandwidth during the period in bits/second
     "p2pMax": 2111377784, // Maximum P2P bandwidth during the period in bits/second
     "max": 8245080104, // Maximum bandwidth (P2P + CDN) during the period in bits/second
     "p2p95th": 7845080104 // 95th bandwidth percentile during the period in bits/second
   }
]

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/bandwidth/timeseries

{
 "from": "1584441300000", 
 "to": "1584527700000",
 "interval" : "10m"
 "contentType": "all"
}

[
   {
      "SrKey": "yourStreamrootKey",
      "p2p": [
          [
             1584441000000, // Timestamp marking the beginning of the current interval
             145966012227.653351 // Average P2P bandwidth during the interval in bits/second
          ],
          [
             1584441600000,
             15202062708.880001
          ],
          ...
       ],
       "cdn": [
          [
             1584441000000, // Timestamp marking the beginning of the current interval
             49680800245.733337 // Average CDN bandwidth during the interval in bits/second
          ],
          [
             1584441600000,
             6826110576.000000
          ],
          ...
       ]
   }
]  

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/buffering

{
 "from": "1584441300000", 
 "to": "1584527700000",
 "contentType": "all"
}

[
   {
     "srKey": "yourStreamrootKey",
     "played": 1572923133189, // Aggregated time spent playing content (excluding buffering time) by your audience
     "buffered": 4954161073 // Aggregated time spent rebuffering by your audience
    }
]

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/buffering/timeseries

{
 "from": "1584441300000", 
 "to": "1584527700000",
 "interval" : "10m"
 "contentType": "all"
}

[
    {
        "srKey": "6fa93815-2dc9-4df6-9967-3bb108d14bb5",
        "played": [
            [
                1584403200000, // Timestamp marking the beginning of the current interval
                1317094954139 // Aggregated time spent playing content (excluding buffering time) by your audience during the interval
            ],
            [
                1584489600000,
                255828179050
            ]
        ],
        "buffered": [
            [
                1584403200000, // Timestamp marking the beginning of the current interval
                4179122884 // Aggregated time spent rebuffering by your audience during the interval
            ],
            [
                1584489600000,
                775038189
            ]
        ]
    }
]

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/platforms

{
 "from": "1584441300000", 
 "to": "1584527700000",
 "contentType": "all"
}

[
    {
        "srKey": "yourStreamrootKey",
        "platforms": [
            "chromecast",
            "desktop-electron",
            "web-desktop",
            "web-mobile",
            "android-webview"
        ]
    }
]

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/streams

{
 "from": "1584441300000", 
 "to": "1584527700000",
 "contentType": "all"
}

[
    {
        "srKey": "yourStreamrootKey",
        "streams": [
            "mainContent/myVODstream.m3u8",
            "mainContent/majorChannel.m3u8",
            "mainContent/sportsLive.m3u8",
        ]
    }
]