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. You can get your API Keys from your Streamroot Dashboard in the Profile Section:
Authenticate via API Key
To use our data APIs you need to authenticate via API Key set in the Authorization HTTP header.
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.
Parameter | Type | Description |
since | string |
Since given elapsed time - (s=seconds, d=days, h=hours, w=weeks). Cannot be passed in addition to (from, to). |
from | string | YYYY-MM-DD or Unix timestamp in milliseconds. Required if param 'to' present. Cannot be passed in addition to since. |
to | string |
YYYY-MM-DD or Unix timestamp in milliseconds. Required if param 'from' present. Cannot be passed in addition to since. |
contentType | string |
Possible values: |
content | string |
This optional parameter allows you to filter the data for a particular content. You can use the dna/data/streams endpoint to get your list of contents. |
platform | string |
This optional parameter allows you to filter the data for a particular platforms. You can use the dna/data/platforms endpoint to get your list of platforms. |
interval | string |
For timeseries endpoints: allows you to select the granularity of the timeserie. Streamroot data points are aggregated every 5 mins. By selecting an interval bigger than 5 minutes, each data point in the timeserie will be calculated by aggregating of all 5 minutes data points that fell into that interval. You can speficy your interval in s=seconds, d=days, h=hours, w=weeks with a maximum of 4 weeks. |
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
}
]
dna/data/audience/timeseries
Returns the audience numbers for the selected period broken down per time interval, allowing you to display the audience numbers as a function of time.
Endpoint
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/audience/timeseries
Request Body Example
{
"from": "1584441300000",
"to": "1584527700000",
"interval" : "10m"
"content": "mainContent/myVODstream.m3u8"
}
Response Example
[
{
"srKey": "yourStreamrootKey",
"audience": [
[
1584441000000, // Timestamp marking the beginning of the current interval
17311 // Number of concurrent viewers during that interval
],
[
1584441600000,
17479
],
[
1584442200000,
16995
],
...
]
}
]
dna/data/traffic
Returns the aggregated traffic numbers for the selected period.
Endpoint
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/traffic
Request Body Example
{
"from": "1584441300000",
"to": "1584527700000",
"contentType": "all"
}
Response Example
[
{
"srKey": "yourStreamrootKey",
"cdn": 1.37629688435669e+14, // Bytes downloaded through CDN during the period
"p2p": 1.41125192621073e+14 // Bytes downloaded through P2P during the period
}
]
dna/data/traffic/timeseries
Returns the traffic numbers for the selected period broken down per time interval, allowing you to display the traffic numbers as a function of time.
Endpoint
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/traffic/timeseries
Request Body Example
{
"from": "1584441300000",
"to": "1584527700000",
"interval" : "10m"
"contentType": "all"
}
Response Example
[
{
"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
],
...
]
}
]
dna/data/bandwidth
Returns the aggregated bandwidth numbers for the selected period.
Endpoint
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/bandwidth
Request Body Example
{
"from": "1584441300000",
"to": "1584527700000",
"contentType": "all"
}
Response Example
[
{
"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
}
]
dna/data/bandwidth/timeseries
Returns the bandwidth numbers for the selected period broken down per time interval, allowing you to display the bandwidth numbers as a function of time.
Endpoint
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/bandwidth/timeseries
Request Body Example
{
"from": "1584441300000",
"to": "1584527700000",
"interval" : "10m"
"contentType": "all"
}
Response Example
[
{
"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
],
...
]
}
]
dna/data/buffering
Returns the aggregated time spent playing and time spent rebuffering by your viewers for the selected period.
Endpoint
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/buffering
Request Body Example
{
"from": "1584441300000",
"to": "1584527700000",
"contentType": "all"
}
Response Example
[
{
"srKey": "yourStreamrootKey",
"played": 1572923133189, // Aggregated time spent playing content (excluding buffering time) by your audience
"buffered": 4954161073 // Aggregated time spent rebuffering by your audience
}
]
dna/data/buffering/timeseries
Returns the buffering numbers for the selected period broken down per time interval, allowing you to display the buffering numbers as a function of time.
Endpoint
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/buffering/timeseries
Request Body Example
{
"from": "1584441300000",
"to": "1584527700000",
"interval" : "10m"
"contentType": "all"
}
Response Example
[
{
"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
]
]
}
]
dna/data/platforms
Returns the list of platforms for which Mesh Delivery saw active traffic during the selected period.
Endpoint:
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/platforms
Request Body Example
{
"from": "1584441300000",
"to": "1584527700000",
"contentType": "all"
}
Response Example
[
{
"srKey": "yourStreamrootKey",
"platforms": [
"chromecast",
"desktop-electron",
"web-desktop",
"web-mobile",
"android-webview"
]
}
]
dna/data/streams
Returns the list of streams (manifest urls or Content IDs) for which Mesh Delivery saw active traffic during the selected period.
Endpoint:
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/data/streams
Request Body Example
{
"from": "1584441300000",
"to": "1584527700000",
"contentType": "all"
}
Response Example
[
{
"srKey": "yourStreamrootKey",
"streams": [
"mainContent/myVODstream.m3u8",
"mainContent/majorChannel.m3u8",
"mainContent/sportsLive.m3u8",
]
}
]