Media Analytics API

Online audiences expect instant access to premium online video content and an uninterrupted viewing experience on any device, no matter where they are. Understanding audience behavior, the quality of service impacting performance, and viewer level diagnostics for live and on-demand digital media is a must to help companies deliver the online video experience viewers demand. With this insight, companies can address challenges that affect monetization, optimize product portfolios, prioritize marketing efforts, manage distribution strategies, address rights holder requirements, and monitor and allocate costs more strategically. Access to key video analytics through both simple and complex reports is a critical piece of successful content publishing. Media Analytics REST APIs provides access to these information and other report pack details.

The REST API responds to requests with standard HTTP status codes. Error messages are embedded in the JSON response in the event of a validation failure or when the API fails to process your request.

Getting Started

Visit the OPEN API Introduction section to get started and make Akamai OPEN API calls.

URL Structure

https://{BASE_URL}/media-analytics/v1

Generate the BASE_URL using the Manage APIs tool in Akamai Luna Control Center.

Sample Usage - Steps to Retrieve Data

Step 1: Retrieve Report Pack

A report pack is defined by a set of data stores, which are a collection of dimensions and metrics of interest, aggregated over time. For more details, refer to the User Guide. All Media Anlytics report packs can be retrieved using the resource given below. You may skip this step, if the report packs are known. A sample request and response is shown below:

GET: /media-analytics/v1/qos-monitor/report-packs

  • Response 200 (application/json)

    [
        {
            "id": 6833,
            "name": "ReportPack Qos",
            "isActive": true,
            "type": "qos",
            "subType": "QoS_Live Events",
            "timezone": "GMT"
        },
        {
            "id": 6311,
            "name": "HDS Test",
            "isActive": true,
            "type": "qos",
            "subType": "QoS_On-demand Streams",
            "timezone": "Asia/Calcutta"
        }
    ]
    

Step 2: Retrieve Report Pack Details

Next, you will need to retrieve the details of the report pack. Details include report pack name, data stores, data sources, metrics and dimensions used in the report pack.

Data store details help you determine the combination of dimensions and metrics to query. Remember, you cannot combine dimensions and metrics across data stores.

Seen below is how you can use report pack ID as the parameter to make an API call in order to obtain details of the report pack.

GET: /media-analytics/v1/qos-monitor/report-packs/{reportPackId}

A sample request and its response is shown below.

GET: /media-analytics/v1/qos-monitor/report-packs/6311

  • Response 200 (application/json)

    {
        "id": 6311,
        "name": "HDS Qos Test",
        "isActive": true,
        "type": "qos",
        "subType": "QoS_On-demand Streams",
        "dataSources": [
            { "id": 4553, "name": "Qos monitor data Source" }
        ],
        "dimensions": [
            { "id": 160, "name": "Title", "type": "standard" },
            { "id": 12, "name": "Time", "type": "standard" },
            { "id": 96, "name": "Start Up Time Range", "type": "standard" },
            { "id": 57, "name": "Country", "type": "custom" }
        ],
        "metrics": [
            { "id": 437, "name": "Plays with Rebuffers" },
            { "id": 156, "name": "Downshifts" },
            { "id": 179, "name": "Bitrate Views" },
            { "id": 188, "name": "Plays Started" }
        ],
        "filters": null,
        "dataStores": [
            {
                "id": 1238,
                "name": "Data Store for qos_vod",
                "type": "standard",
                "description": "Stores data relevant for qos_vod"
            },
            {
                "id": 1435,
                "name": "Encoded Bitrate(VOD)",
                "type": "standard",
                "description": "encoded bitrate data store for vod data"
            }
        ],
        "timezone": "GMT"
    }
    

Step 3: Retrieve Report Data

You can retrieve data for a specific report using the call below.

GET: /media-analytics/v1/qos-monitor/report-packs/{reportPackId}/data{?startDate,endDate,aggregation,dimensions,metrics,limit,offset,filterParams,sortParams}

Let’s assume that the dimension IDs 12,57 represent time,country and the metric ID 437 represents the metric “Plays with Rebuffers”. A sample call to fetch number of Plays with Rebuffers by countries for Nov 13, 2014 between 12 AM and 12:05 AM is shown below along with its response.

GET: /security-monitor/v1/report-packs/6311/data?dimensions=12,57&metrics=437&startDate=11/13/2014:00:00&endDate=11/13/2014:00:05&limit=5

  • Response 200 (application/json)

    {
        "columns": [
            {
                "type": "dimension",
                "name": "Time",
                "description": "Time as per time zone specified in the report",
                "index": 0
            },
            {
                "type": "dimension",
                "name": "Country",
                "description": "Country from which viewer requested media ",
                "index": 1
            },
            {
                "type": "metric",
                "name": "Plays with Rebuffers",
                "description": "Number of Plays with Rebuffers",
                "index": 2,
                "aggregate": "418",
                "peak": "156",
                "unit": null
            }
        ],
        "rows": [
            [ "1415837040", "US", "156" ],
            [ "1415837040", "CH", "136" ],
            [ "1415836980", "US", "113" ],
            [ "1415836980", "CH", "103" ],
            [ "1415836920", "US", "95" ]
        ],
        "metaData": {
            "aggregation": 60,
            "limit": 5,
            "startTimeInEpoch": 1415836800,
            "hasMoreData": false,
            "timeZone": "GMT",
            "offset": 0,
            "reportPack": "HDS Qos Test",
            "endTimeInEpoch": 1415837100
        }
    }
    

Response Codes

An API call can return any one of the following response codes:

Code Description
200 OK
204 No data
400 Bad input parameter. Error message indicates which one and why.
401 Authentication failure
403 Authorization failure
404 Resource not found
405 Request method not expected (generally should be GET)
409 Conflict
410 Requested resource is no longer available.
411 Content-length header not specified
413 Request body exceeds maximum allowable size.
423 Requested resource is locked.
429 Request rate limit exceeded. See here
500 Internal server error unexpected condition
501 Not supported
503 Too many requests; service is temporarily unavailable.
507 Data size is over allowable limit.

The error JSON below is returned for all non–2xx HTTPS status codes. The returned HTTP response code corresponds to the httpStatus member in the JSON response. This helps you avoid querying the header for the response code.

HTTP/1.1 404 Not Found

Content-Type: application/json
Reply Body:
{
    "httpStatus": 404,
    "detail": "additional non-http specific info where relevant",
    "title": "Resource not found"
}

Important Notes

Encoding of Request Parameters

All the request parameter values must be UTF–8 encoded.

Using Country Codes

Media Analytics API allows you to work with geographic lists of country codes. You will need to use the codes found on the Akamai EdgeScape country codes page (SupportUser and Developer GuidesEdgeScapeData CodesCountry Codes) in Akamai Luna Control Center.

Usage Criterion

Media Analytics API are available for occasional on-demand fetch of data only. Automated/programmed fetches in a “Poll” fashion are not supported & such usage will be scrutinized and could be dropped.

Rate Limiting

Media Analytics API endpoints are subject to a rate-limiting constraint, which is currently set at ten requests per minute. When this limit is exceeded, an HTTP 429 error (Too Many Requests) is returned. This should be considered carefully when implementing endpoints that act on single list entries in a loop.