Endpoints¶

The Edge Analytics API is a versioned JSON API which endpoints are organized into two main groups:

v1/: grouping all the new metrics endpoints along with the query endpoint.
legacy/: containing all endpoints ported from the Legacy Stats API to ease the migration to the Edge Analytics API. Please find the Legacy endpoints reference here.

This section of the documentation will focus on the new set of endpoints (under v1/) because the legacy set of endpoints inherit the interface from the Legacy Stats API.

API base URL: https://api.system73.com/analytics

Remember

The API swagger/OpenAPI reference is available on https://api.system73.com/analytics/docs/.

Metrics endpoints (`v1/metrics/`)¶

This set of endpoints share the same interface and capabilities as all of them provide a metric and allow you to filter the results with predefined set of filters.

Data filters¶

You can filter metrics results by the following properties:

These filters are optional and any filter combination can be applied.

Time interval¶

You must specify the timeframe of the metric to be calculated with the parameters from_date and to_date. The time boundaries are strings containing a date and time in the ISO-8601 format with a precision of up to seconds. Microseconds are truncated from the input.

Valid inputs

"2012-01-01T10:12:30.000Z"
"2012-01-01T10:12:30"

Granularity¶

You can choose any query granularity from the list of supported granularities:

second
minute
fifteen_minute
thirty_minute
hour
day
week
month
quarter
year
all (buckets everything into a single time bucket)

However, depending on the data layer you have the following restrictions:

Realtime: you can use from second to thirty_minute for time intervals of up to 48h.
Historical: the finest supported granularity is minute because of the historical datasources characteristics.

Data layer¶

You must choose the data layer (realtime or historical) depending on the granularity and the query time interval restrictions.

Take into account the data layer supported query granularity and data retention as described in the Architecture section.

Tip

The performance of a query is always affected by the combination of data layer, time interval and granularity. As a general rule of thumb fine query granularities must be used on short time intervals and longer time intervals benefit from coarser granularities.

Query endpoint (`v1/query/sql`)¶

This endpoint allows you to get metrics from custom SQL queries with the constructs supported by the Druid SQL dialect. In general, this dialect offers much of the same functionality you can get from traditional relational databases but it is highly recommended to read the linked documentation so you get more familiar with Druid specifics.

Requirements¶

Additionally, there is a series of restrictions that need to be followed in order to produce valid queries:

Schema fields

You can only reference datasource fields belonging to your Analytics tier. Check the Schema section of the Data Model for more information.
Example

A customer in the Lite tier cannot issue the following query because the field ConnectionType belongs to the Advanced tier.
```
SELECT TIME_FLOOR(__time, 'PT1M') AS "timestamp", AVG(BufferHealth) as "avg_buffer_health"
FROM "sdk-emea-realtime"
WHERE CustomerId = '1234' AND ConnectionType = 'ETHERNET'
    AND __time >= '2022-12-30' AND __time < '2022-12-31'
GROUP BY 1
```
Note

The use of SELECT * statement over EI datasources is allowed with certain restrictions.
CustomerId and region

Queries must always filter by your assigned CustomerId.

Also, you need to select the datasource that corresponds to your data deployment region.
Example
```
SELECT TIME_FLOOR(__time, 'P1D') AS "timestamp", AVG(BufferHealth) as "avg_buffer_health"
FROM "sdk-americas-historical-hour"
WHERE CustomerId = '1234'
    AND __time >= '2022-01-01T00:00:00' AND __time < '2022-04-01T00:00:00'
GROUP BY 1
```
Important

Please send an email to support@system73.com to request your assigned CustomerId and corresponding region.

Restrictions¶

Select-star queries¶

SELECT * queries are allowed as long as you include a LIMIT clause that is subject to a restriction on the maximum number of rows depending on your Analytics Tier:

Tier	Max rows
Lite	1,000 rows
Advanced	10,000 rows

Example

SELECT *
FROM "sdk-americas-historical-hour"
WHERE CustomerId = '1234'
LIMIT 50

Best practices¶

As in other big data solutions, the following recommendations will help making the most out of the queries while ensuring acceptable performance levels and resource usage:

Avoid queries including too many fields or SELECT * queries.
Always include a filter for __time to limit the amount of data than needs to be scanned.
Avoid queries spanning large intervals of time (e.g., >48h) on realtime datasources.
Avoid fine granularities on large time interval queries.
Try to avoid subqueries underneath joins: they affect both performance and scalability.

Legacy endpoints (`legacy/stats/`)¶

Overview¶

This legacy section of the Edge Analytics provides summarized statistics of the system like P2P or CDN throughput, buffer health, buffer filling rate, and more.

Data is provided by the customer, and can be filtered by channel and stream, and some endpoints can also be filtered by bitrate.

Exposed Metrics¶

The following list describes the available metrics. All metrics refer to the latest time window:

Name	Description
Buffer health	The amount playback time (milliseconds) that remains on the buffers of all video players.
Buffer filling rate	The ratio between the playback time and the download time.
Connection type	The type of the current devices.
Dropped frames	The number of dropped frames reported by all players.
Operating system	The name of the operating systems of all devices.
Platforms	The name of the platforms of the current devices.
Rebuffering	The ratio between the rebuffering duration and the actual duration of video played.
Throughput	The amount of data downloaded during the reporting window.

Available Filters¶

Time¶

All data returned by the Stats API is aggregated in different time windows and these aggregations can be requested using the right filter. Below are the available time filters:

live: Time aggregation window of 5 seconds
10m: Time aggregation window of 10 minutes
1h: Time aggregation window of 1 hour
24h: Time aggregation window of 1 day
1w: Time aggregation window of 1 week
1M: Time aggregation window of 1 month
2M: Time aggregation window of 2 months
CM: Time aggregation window of the current month
LM: Time aggregation window of last month

Examples:

https://api.system73.com/analytics/legacy/stats/throughput/agg?time=live
https://api.system73.com/analytics/legacy/stats/throughput/agg?time=10m

Source¶

Some endpoints can be filtered by source, this means choosing between CDN or peer-to-peer(P2P) data.

cdn: information related to data downloaded from the CDN.
p2p: information related to data relayed over the peer-to-peer network.

Examples:

https://api.system73.com/analytics/legacy/stats/throughput/agg?time=10m&source=cdn
https://api.system73.com/analytics/legacy/stats/throughput/agg?time=10m&source=p2p

Summary¶

`/summary`¶

Method: GET

Description

Provides information about customer's channels such as throughput, devices and viewing time of each one. The throughput unit is kbps and the viewing time is in seconds. The endpoints can be paginated using the appropriate query parameters.

Required parameters:

time=[time filters]

Success Response:

200 OK

[
   {
       "channel_id": [string],
       "cdn_throughput": [numeric],
       "p2p_throughput": [numeric],
       "total_throughput": [numeric],
       "cdn_devices": [numeric],
       "p2p_devices": [numeric],
       "not_compatible_devices": [numeric],
       "cdn_viewing_time": [numeric],
       "p2p_viewing_time": [numeric],
       "total_viewing_time": [numeric],
       "total_pretty_viewing_time": [string]
   },
   { ... }
]

Call samples:

/summary?time=live
/summary?time=24h

Sample Response

[
   {
      "channel_id": "1",
      "cdn_throughput": 40000,
      "p2p_throughput": 180000,
      "total_throughput": 220000,
      "cdn_devices": 2,
      "p2p_devices": 9,
      "not_compatible_devices": 0,
      "cdn_viewing_time": 10,
      "p2p_viewing_time": 45,
      "total_viewing_time": 55,
      "total_pretty_viewing_time": "0:00:55"
   },
   { ... }
]

`/summary/agg`¶

Method: GET

Description

Provides aggregated information depending on the endpoint such as throughput, devices and viewing time. The throughput unit is kbps and the viewing time is in seconds.

Required parameters:

time=[time filters]

Success Response:

200 OK

[
   {
      "aggregate": [string],
      "cdn_throughput": [numeric],
      "p2p_throughput": [numeric],
      "total_throughput": [numeric],
      "cdn_devices": [numeric],
      "p2p_devices": [numeric],
      "not_compatible_devices": [numeric],
      "cdn_viewing_time": [numeric],
      "p2p_viewing_time": [numeric],
      "total_viewing_time": [numeric],
      "total_pretty_viewing_time": [string]
   },
   { ... }
]

Call samples:

/summary/agg?time=live
/summary/agg?time=24h

Sample Response

[
   {
      "aggregate": "aggregate",
      "cdn_throughput": 40000,
      "p2p_throughput": 180000,
      "total_throughput": 220000,
      "cdn_devices": 2,
      "p2p_devices": 9,
      "not_compatible_devices": 0,
      "cdn_viewing_time": 10,
      "p2p_viewing_time": 45,
      "total_viewing_time": 55,
      "total_pretty_viewing_time": "0:00:55"
   }
]

System Statistics¶

`/stats/throughput/agg`¶

URLs:

/stats/throughput/agg
/channels/{channel_id}/stats/throughput/agg
/channels/{channel_id}/streams/{stream_id}/stats/throughput/agg

Method: GET

Description

Provides information about the aggregated throughput for a customer, specific channel or stream. Throughput unit is kbps.

Required parameters:

time=[time filters]
source=[source filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "agg_throughput_{source}": [numeric]
   },
   { ... }
]

Call example:

/throughput/agg?time=live&source=cdn

Sample Response

[
   {
       "datetime": 1686667767000.0,
       "agg_throughput_cdn": 1.0
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

`/stats/buffer_health/avg`¶

URLs:

/stats/buffer_health/avg
/channels/{channel_id}/stats/buffer_health/avg
/channels/{channel_id}/streams/{stream_id}/stats/buffer_health/avg

Method: GET

Description

Provides information about the average buffer health for a customer or specific channel. Buffer health unit is milliseconds.

Required parameters:

time=[time filters]
source=[source filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "avg_buffer_health_{source}": [numeric]
   },
   { ... }
]

Call example:

/buffer_health/avg?time=live&source=cdn

Sample Response

[
   {
       "datetime": 1686667767000.0,
       "avg_buffer_health_cdn": 228212.0
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

`/stats/rebuffering/ratio`¶

URLs:

/stats/rebuffering/ratio
/channels/{channel_id}/stats/rebuffering/ratio
/channels/{channel_id}/streams/{stream_id}/stats/rebuffering/ratio

Method: GET

Description

Provides information about the rebuffering ratio for a customer or specific channel.

Required parameters:

time=[time filters]
source=[source filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "rebuffering_ratio": [numeric]
   },
   { ... }
]

Call example:

/rebuffering/ratio?time=live&source=cdn

Sample Response

[
   {
       "datetime": 1686667767000.0,
       "rebuffering_ratio": 0.1
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

`/stats/buffer_filling_rate/avg`¶

URLs:

/channels/{channel_id}/stats/buffer_filling_rate/avg
/channels/{channel_id}/streams/{stream_id}/stats/buffer_filling_rate/avg

Method: GET

Description

Provides information about the average buffer filling rate for a specific channel.

Required parameters:

time=[time filters]
source=[source filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "avg_buffer_filling_rate_{source}": [numeric]
   },
   { ... }
]

Call example:

/buffer_filling_rate/avg?time=live&source=cdn

Sample Response

[
   {
       "datetime": 1686667767000.0,
       "avg_buffer_filling_rate_cdn": 3.4
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

`/stats/dropped_frames/avg`¶

URLs:

/channels/{channel_id}/stats/dropped_frames/avg
/channels/{channel_id}/streams/{stream_id}/stats/dropped_frames/avg

Method: GET

Description

Provides information about the average dropped frames for a specific channel.

Required parameters:

time=[time filters]
source=[source filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "avg_dropped_frames_{source}": [numeric]
   },
   { ... }
]

Call example:

/dropped_frames/avg?time=live&source=p2p

Sample Response

[
   {
       "datetime": 1686667767000.0,
       "avg_dropped_frames_p2p": 0
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

Devices Statistics¶

`/stats/os`¶

URLs:

/stats/os
/channels/{channel_id}/stats/os
/channels/{channel_id}/streams/{stream_id}/stats/os

Method: GET

Description

Provides information about the operating systems and the number of devices of each one for a customer or specific channel.

Required parameters:

time=[time filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "operating_systems": [object]
   },
   { ... }
]

Call example:

/os?time=live

Sample Response

[
   {
       "datetime": 1686649896000.0,
       "operating_systems": {
           "MAC_OS": 1,
           "LINUX": 2,
           "WINDOWS": 1
      }
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

`/stats/platforms`¶

URLs:

/stats/platforms
/channels/{channel_id}/stats/platforms
/channels/{channel_id}/streams/{stream_id}/stats/platforms

Method: GET

Description

Provides information about the platforms and the number of devices of each one for a customer or specific channel.

Required parameters:

time=[time filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "platforms": [object]
   },
   { ... }
]

Call example:

/platforms?time=live

Sample Response

[
   {
       "datetime": 1686650018000.0,
       "platforms": {
           "FIREFOX": 1,
           "CHROME": 2,
           "EDGE": 1
      }
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

`/stats/connection_types`¶

URLs:

/stats/connection_types
/channels/{channel_id}/stats/connection_types
/channels/{channel_id}/streams/{stream_id}/stats/connection_types

Method: GET

Description

Provides information about the connection types and the number of devices of each one for a customer or specific channel.

Required parameters:

time=[time filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "connection_types": [object]
   },
   { ... }
]

Call example:

/connection_types?time=live

Sample Response

[
   {
       "datetime": 1686650123000.0,
       "connection_types": {
           "ETHERNET": 1,
           "WIFI": 2,
           "CELLULAR": 1
      }
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

Client Errors¶

Below you will find the client errors that might be returned by the API.

400 Bad Request¶

Not sending the required query parameter for each endpoint will result in a 400 Bad Request response.

Example of body response:

{
    "detail": [
        {
            "loc": [
                "query",
                "time"
            ],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}

Sending a wrong value in the query parameters will result in a 400 Bad Request response. Example of body response:

{
    "detail": [
      {"loc": [
        "query",
        "source"
      ],
        "msg": "value is not a valid enumeration member; permitted: 'cdn', 'p2p'",
        "type": "type_error.enum",
        "ctx": {
          "enum_values": [
            "cdn",
            "p2p"
          ]
        }
      }
    ]
}

401 Unauthorized¶

401 Unauthorized will be received when performing the following actions:

Not sending the authorization header will result in a 401 Unauthorized response.
Sending an invalid authorization header will result in a 401 Unauthorized response.

{
  "type": "not-authenticated",
  "title": "Not authenticated"
}

404 Not Found¶

Doing a request to a URL that does not exist will result in a 404 Not Found response. Example of body response:

{
  "detail": "Not Found"
}

Last update: 2023-07-24

Endpoints¶

Metrics endpoints (v1/metrics/)¶

Data filters¶

Time interval¶

Granularity¶

Data layer¶

Query endpoint (v1/query/sql)¶

Requirements¶

Restrictions¶

Select-star queries¶

Best practices¶

Legacy endpoints (legacy/stats/)¶

Overview¶

Exposed Metrics¶

Available Filters¶

Time¶

Source¶

Summary¶

/summary¶

/summary/agg¶

System Statistics¶

/stats/throughput/agg¶

/stats/buffer_health/avg¶

/stats/rebuffering/ratio¶

/stats/buffer_filling_rate/avg¶

/stats/dropped_frames/avg¶

Devices Statistics¶

/stats/os¶

/stats/platforms¶

/stats/connection_types¶

Client Errors¶

400 Bad Request¶

401 Unauthorized¶

404 Not Found¶

Metrics endpoints (`v1/metrics/`)¶

Query endpoint (`v1/query/sql`)¶

Legacy endpoints (`legacy/stats/`)¶

`/summary`¶

`/summary/agg`¶

`/stats/throughput/agg`¶

`/stats/buffer_health/avg`¶

`/stats/rebuffering/ratio`¶

`/stats/buffer_filling_rate/avg`¶

`/stats/dropped_frames/avg`¶

`/stats/os`¶

`/stats/platforms`¶

`/stats/connection_types`¶