Media Analytics API v1

Manage media report packs and fetch analytic data for a particular report pack.

Learn more:

Overview

Note: The Media Analytics v1 API is deprecated and will cease to operate by the end of June, 2019. Upgrade to the Media Analytics API v2 before that time.

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

See Get Started for guidance on making Akamai API calls.

URL structure

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

Generate the BASE_URL using the Manage APIs tool in Akamai 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 Analytics 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
    }
}

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 (Support ⇒ User and Developer Guides ⇒ EdgeScape ⇒ Data Codes ⇒ Country Codes) in 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.

Resources

This section provides details on the Media Analytics API’s set of URL operations.

API summary

Operation Method Endpoint
Audience Analytics
List Audience Analytics Report Packs GET /media-analytics/v1/audience-analytics/report-packs
Get a Audience Analytics Report Pack GET /media-analytics/v1/audience-analytics/report-packs/{reportPackId}
List Audience Analytics Data Stores GET /media-analytics/v1/audience-analytics/report-packs/{reportPackId}/data-stores
Get a Audience Analytics Data Store GET /media-analytics/v1/audience-analytics/report-packs/{reportPackId}/data-stores/{dataStoreId}
List Audience Analytics Data Sources GET /media-analytics/v1/audience-analytics/report-packs/{reportPackId}/data-sources
Get Audience Analytics Report Data GET /media-analytics/v1/audience-analytics/report-packs/{reportPackId}/data{?startDate,endDate,aggregation,dimensions,metrics,limit,offset,filterParams,sortParams}
QoS Monitor
List QoS Monitor Report Packs GET /media-analytics/v1/qos-monitor/report-packs
Get a QoS Monitor Report Pack GET /media-analytics/v1/qos-monitor/report-packs/{reportPackId}
List QoS Monitor Data Stores GET /media-analytics/v1/qos-monitor/report-packs/{reportPackId}/data-stores
Get a QoS Monitor Data Store GET /media-analytics/v1/qos-monitor/report-packs/{reportPackId}/data-stores/{dataStoreId}
List QoS Monitor Data Sources GET /media-analytics/v1/qos-monitor/report-packs/{reportPackId}/data-sources
Get QoS Monitor Report Data GET /media-analytics/v1/qos-monitor/report-packs/{reportPackId}/data{?startDate,endDate,aggregation,dimensions,metrics,limit,offset,filterParams,sortParams}
Viewer Diagnostics
List Viewer Diagnostics Report Packs GET /media-analytics/v1/viewer-diagnostics/report-packs
Get a Viewer Diagnostics Report Pack GET /media-analytics/v1/viewer-diagnostics/report-packs/{reportPackId}
List Viewer Diagnostics Data Stores GET /media-analytics/v1/viewer-diagnostics/report-packs/{reportPackId}/data-stores
Get a Viewer Diagnostics Data Store GET /media-analytics/v1/viewer-diagnostics/report-packs/{reportPackId}/data-stores/{dataStoreId}
List Viewer Diagnostics Data Sources GET /media-analytics/v1/viewer-diagnostics/report-packs/{reportPackId}/data-sources
Get Viewer Diagnostics Report Data GET /media-analytics/v1/viewer-diagnostics/report-packs/{reportPackId}/viewers/{viewerId}/data{?startDate,endDate,aggregation,dimensions,metrics,limit,offset,filterParams,sortParams}
Download Analytics
List Download Analytics Report Packs GET /media-analytics/v1/download-analytics/report-packs
Get a Download Analytics Report Pack GET /media-analytics/v1/download-analytics/report-packs/{reportPackId}
List Download Analytics Data Stores GET /media-analytics/v1/download-analytics/report-packs/{reportPackId}/data-stores
Get a Download Analytics Data Store GET /media-analytics/v1/download-analytics/report-packs/{reportPackId}/data-stores/{dataStoreId}
List Download Analytics Data Sources GET /media-analytics/v1/download-analytics/report-packs/{reportPackId}/data-sources
Get Download Analytics Report Data GET /media-analytics/v1/download-analytics/report-packs/{reportPackId}/data{?startDate,endDate,aggregation,dimensions,metrics,limit,offset,filterParams,sortParams}

List audience analytics report packs

Returns name, id, and timezone for all report packs created for your account.

GET /media-analytics/v1/audience-analytics/report-packs

Status 200 application/json

Response:

[
    {
        "id": 26273,
        "name": "TestingAudience",
        "isActive": true,
        "type": "ma",
        "subType": "Audience Analytics",
        "timezone": "GMT"
    },
    {
        "id": 5538,
        "name": "Live Streams",
        "isActive": true,
        "type": "ma",
        "subType": "Audience Analytics",
        "timezone": "EST5EDT"
    }
]

Relevant data members:

Member Type Description
id Number ID of the report pack.
name String Name of the report pack.
timezone String Timezone in which the data is returned.
type String This is an internal member.
subType String The type of the report-pack.

Get a audience analytics report pack

Details include name of the report pack, data sources, and metrics and dimensions used in the report pack.

GET /media-analytics/v1/audience-analytics/report-packs/{reportPackId}

Example: /media-analytics/v1/audience-analytics/report-packs/26273

Parameter Type Sample Description
Required
reportPackId Number 26273 The ID of the report pack

Status 200 application/json

Response:

{
    "id": 26273,
    "name": "TestingAudience",
    "isActive": true,
    "type": "ma",
    "subType": "Audience Analytics",
    "dataSources": [ { "id": 1336, "name": "Audience Analytics Data Source" } ],
    "dimensions": [
        { "id": 958, "name": "Live VOD 24x7", "type": "custom" },
        { "id": 956, "name": "Max Bitrate (Visit)", "type": "standard" },
        { "id": 957, "name": "Player Id", "type": "standard" }
    ],
    "metrics": [
        { "id": 546, "name": "Peeks" },
        { "id": 544, "name": "Play Duration per Visit" },
        { "id": 3, "name": "Sessions" }
    ],
    "filters": null,
    "dataStores": [
        {
            "id": 939,
            "name": "sample cube 1",
            "type": "standard",
            "description": "Sample Description"
        },
        {
            "id": 952,
            "name": "sample cube 2",
            "type": "custom",
            "description": "Sample Description"
        }
    ],
    "timezone": "GMT"
}

Relevant data members:

Member Type Description
id Number ID of the report pack.
name String Name of the report pack.
dataSources Array All data sources for the report pack. A data source is a collection of raw log data with detailed information on each access to your digital property made by a user. Each data source object provides information on name of the data source and its ID.
dimensions Array All dimensions for the report pack. A dimension acts like a key in data exploration. It answers questions such as who, what, where, which. Each dimension object provides information on the name, type and ID of the dimension.
metrics Array All metrics for the report pack. A metric is a numeric aggregation against one or more dimensions. Each metric object provides information on the name and ID of the metric. It answers questions on volume of activity or attack.
dataStores Array All data stores for the report pack. A data store is a collection of dimensions and metrics stored in a data base. Each data store object provides information on the name, type, short description and ID of the data store.
timezone String Timezone in which the data is returned.
filters Array The filters applied on the data captured in the report pack.
type String This is an internal member.
subType String The type of the report-pack.

List audience analytics data stores

A data store is a collection of dimensions and metrics stored in a database that you can use to create a sub-set and configure reports suited to your requirements. Data store details help you determine the combination of dimensions and metrics to query. Each report pack comes with its standard data stores. You cannot combine dimensions and metrics across data stores.

GET /media-analytics/v1/audience-analytics/report-packs/{reportPackId}/data-stores

Example: /media-analytics/v1/audience-analytics/report-packs/26273/data-stores

Parameter Type Sample Description
Required
reportPackId Number 26273 The ID of the report pack.

Status 200 application/json

Response:

[
    {
        "id": 705,
        "name": "sample data store",
        "type": "standard",
        "dimensions": [
            {
                "id": 23,
                "name": "Continent",
                "type": "standard",
                "description": "Automatically set to the viewer\\'s continent based on mapping of the viewer\\'s IP address to their location by the Akamai EdgeScape service."
            },
            {
                "id": 9320,
                "name": "Device",
                "type": "standard",
                "description": "Can store the type of device used by the viewer, such as iPhone, iPad, PC. Use less than 10 values or the dimension will have too many values to provide helpful insights."
            },
            {
                "id": 122,
                "name": "Time",
                "type": "standard",
                "description": "Set automatically and indicates the Timestamp at which content was consumed and is converted to the time zone set during report pack configuration."
            }
        ],
        "metrics": [
            {
                "id": 5338,
                "name": "Plays per Viewer (Daily)",
                "description": "Plays divided by Daily Viewers"
            },
            {
                "id": 832,
                "name": "Startup Time",
                "description": "Average time between the initial play attempt and the first rendered frame, in seconds."
            },
            {
                "id": 5421,
                "name": "Visits per Viewer (Daily)",
                "description": "Sum of visits across viewers divided by the number of daily viewers"
            }
        ],
        "aggregation": 3600,
        "purgeIntervalInDays": 390,
        "maxQueryDurationInMinutes": 1440,
        "description": "Sample 1"
    },
    {
        "id": 766,
        "name": "sample data store 2",
        "type": "standard",
        "dimensions": [
            {
                "id": 2,
                "name": "Continent",
                "type": "standard",
                "description": "Automatically set to the viewer\\'s continent based on mapping of the viewer\\'s IP address to their location by the Akamai EdgeScape service."
            },
            {
                "id": 4,
                "name": "Country",
                "type": "standard",
                "description": "Automatically set to the viewer\\'s country based on mapping of the viewer\\'s IP address to their location by the Akamai EdgeScape service."
            }
        ],
        "metrics": [
            {
                "id": 542,
                "name": "Plays per Visit (Play Level)",
                "description": "Plays divided by Visits."
            },
            {
                "id": 544,
                "name": "Play Duration per Visit",
                "description": "Play Duration divided by (Sum of) Visits."
            }
        ],
        "aggregation": 86400,
        "purgeIntervalIndays": 390,
        "maxQueryDurationInMinutes": 1440,
        "description": "Sample 2"
    }
]

Relevant data members:

Member Type Description
id Number ID of the data store.
name String Name of the data store.
type String Type of data store (standard or custom).
dimensions Array All dimensions for the data store. A dimension acts like a key in data exploration. It answers questions such as who, what, where, which. Each dimension object provides information on the ID, name, type and description of the dimension.
metrics Array All metrics for the data store. A metric is a numeric aggregation against one or more dimensions. It answers questions on volume of activity or attack. Each metric object provides information on the name, description and ID of the metric.
aggregation Number Time (seconds) over which data is aggregated.
purgeIntervalInDays Number Number of days for which the data store keeps data.
maxQueryDurationInMinutes Number Maximum duration (in minutes) for which a user can query a data store. It is a system-imposed limit for better performance.
description String Text describing the data store.

Get a audience analytics data store

Details include list of dimensions, list of metrics, aggregation interval, purge interval, maximum allowed query interval and so on.

GET /media-analytics/v1/audience-analytics/report-packs/{reportPackId}/data-stores/{dataStoreId}

Example: /media-analytics/v1/audience-analytics/report-packs/26273/data-stores/307

Parameter Type Sample Description
Required
dataStoreId Number 307 The ID of the data store.
reportPackId Number 26273 The ID of the report pack.

Status 200 application/json

Response:

{
    "id": 175,
    "name": "Sample data store 175",
    "type": "standard",
    "dimensions": [
        {
            "id": 5,
            "name": "Region",
            "description": "Automatically set to the viewer\\'s state (US-only) or region based on mapping of the viewer\\'s IP address to their location by the Akamai EdgeScape service."
        },
        {
            "id": 6,
            "name": "City",
            "description": "Automatically set to the viewer\\'s city based on mapping of the viewer\\'s IP address to their location by the Akamai EdgeScape service."
        }
    ],
    "metrics": [
        {
            "id": 542,
            "name": "Plays per Visit (Play Level)",
            "description": "Plays divided by Visits."
        },
        {
            "id": 544,
            "name": "Play Duration per Visit",
            "description": "Play Duration divided by (Sum of) Visits."
        }
    ],
    "aggregation": 3600,
    "purgeIntervalInDays": 390,
    "maxQueryDurationInMinutes": 1440,
    "description": "Sample description"
}

Relevant data members:

Member Type Description
id Number Data Store ID.
name String Data Store name.
type String Type of Data Store (standard or custom).
dimensions Array All dimensions for the Data Store. A dimension acts like a key in data exploration. Each dimension object provides information on ID, name, type and description of the dimension. It answers questions such as who, what, where, which.
metrics Array All metrics for the Data Store. A metric is a numeric aggregation against one or more dimensions. Each metric object provides information on the name, description and ID of the metric. It answers questions on volume of activity or attack.
aggregation Number Time (seconds) over which data is aggregated.
purgeIntervalInDays Number Number of days for which the data store keeps data.
maxQueryDurationInMinutes Number Maximum duration (in minutes) for which a user can query a Data Store.
description String Text describing the Data Store.

List audience analytics data sources

A data source is a collection of raw log data with detailed information on each access to your digital property made by a user.

GET /media-analytics/v1/audience-analytics/report-packs/{reportPackId}/data-sources

Example: /media-analytics/v1/audience-analytics/report-packs/26273/data-sources

Parameter Type Sample Description
Required
reportPackId Number 26273 Report pack ID.

Status 200 application/json

Response:

[
    {
        "id": 223,
        "name": "DataSource_1",
        "type": "clientside_qos1_sm",
        "dsType": "policyId",
        "values": [ "jsbeacon8", "jsbeacon9"   ]
    },
    {
        "id": 70,
        "name": "CP Progressive Downloads",
        "type": "serverSide",
        "dsType": "cpCode",
        "values": [ "12345", "67890"   ]
    },
    {
        "id": 136,
        "name": "CBSi Audience Analytics",
        "type": "clientSide",
        "dsType": "beaconId",
        "configPath": "http://config.server/config/beacon-1336.xml",
        "values": [ "alphanum3r1cbeac0n1d" ]
    }
]

Relevant data members:

Member Type Description
id Number Data Source ID.
name String Name of the Data Source.
dsType String Data Source type.
values Array List of values that form the data source.
configPath String Represents the Beacon configuration path and is present only for clientSide data source type.

Get audience analytics report data

Retrieves data for a specific report based on query parameter criteria. The parameters filterParams and sortParams are used to filter and sort data. The values for these parameters must be UTF–8 encoded JSON strings. Example strings are provided in the parameter description below.

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

Example: /media-analytics/v1/audience-analytics/report-packs/26273/data?startDate=03%2F22%2F2014%3A15%3A30&endDate=03%2F23%2F2014%3A15%3A30&aggregation=day%2Cmonth%2C3600%2C900%2C60&dimensions=160%2C96%2C57&metrics=546%2C544%2C3&limit=300&offset=100&filterParams=%5B%7B%22type%22%3A%22dimension%22%2C%22values%22%3A%5B%22GB%22%5D%2C%22id%22%3A4%2C%22condition%22%3A%22in%22%7D%2C%7B%22type%22%3A%22metric%22%2C%22values%22%3A%5B16%5D%2C%22id%22%3A155%2C%22condition%22%3A%22gt%22%7D%5D&sortParams=%5B%7B%22type%22%3A%22metric%22%2C%22order%22%3A%22asc%22%2C%22id%22%3A40%7D%5D

Headers:

  • Accept: application/json

Parameter Type Sample Description
Required
dimensions String 160,96,57 Comma-separated dimension identifiers. The ID can be obtained from the data stores API.
metrics String 546,544,3 Comma-separated metrics identifiers. The ID can be obtained from the data stores API.
reportPackId Number 26273 The ID of the report pack.
Optional
aggregation String day,month,3600,900,60 The aggregation in which the data is required to be grouped. It can be a number representing the aggregation in seconds or one of the following possible values day, week, month, year. If passed as a number, the allowed value is one of the aggregations of the available data stores listed by the data stores API.
endDate String 03/23/2014:15:30 The end date string in format MM/dd/yyyy:HH:mm. The time part is optional and should be in the 24-hour format.
filterParams String [{"type":"dimension","values":["GB"],"id":4,"condition":"in"},{"type":"metric","values":[16],"id":155,"condition":"gt"}] The UTF–8 URL-encoded JSON string of the filter parameters based on which the data is filtered. The structure of the JSON is explained above. By default, the data will not be filtered.
limit Number 300 The number of rows to return. Its value should lie between 1 and 10000 inclusive. If not specified, 300 rows will be returned by default.
offset Number 100 The offset of the row from which the data should start. This parameter can be used along with limit to get batches of data. For instance, if there are 1000 records in the result, 10 calls can be made with progressing offset. That is, first call with limit=100 and offset=0, second call with limit=100 and offset=100 so on and so forth. The default value is 0
sortParams String [{"type":"metric","order":"asc","id":40}] The UTF–8 URL-encoded JSON string of the sort parameters based on which the data is sorted. The structure of the JSON is explained above. By default, the data wil be sorted by time if time is selected as one of the dimensions or by the first metric in descending order if time is not selected.
startDate String 03/22/2014:15:30 The start date string in format MM/dd/yyyy:HH:mm. The time part is optional and should be in the 24-hour format.
All JSON object members of the filterParams parameter are required.
Member Type Description
Required
type Enumeration Specifies whether the parameter ID provided is a dimension or metric
id Number The ID of the filtering entity (dimension/metric).
condition String For Dimensions: in, nin, contains, ncontains, starts, nstarts, ends, nends. For Metrics: eq, neq, gt, gte, lt, lte. The n prefix reverses the result.
values Array List of values used to filter the result. Multiple values are supported for dimension filters.

All JSON object members of the sortParams parameter are required.

Member Type Description
Required
type Enumeration Specifies whether the parameter ID provided is a dimension or metric
id Number The ID of the sorting entity.
order Enumeration Represents asc for ascending or desc for descending order.

Status 200 application/json

Response:

{
    "columns": [
        { "name": "Country", "aggregate": "-", "index": 0 },
        { "name": "Region", "aggregate": "-", "index": 1 },
        { "name": "% Rebuffering Plays", "aggregate": "20.06", "index": 2 }
    ],
    "rows": [
        [ "GB", "WA", "18.15" ],
        [ "GB", "EN", "16.74" ],
        [ "GB", "NI", "66.06" ]
    ],
    "metaData": {
        "limit": 3,
        "endTimeInEpoch": 1392598800,
        "startTimeInEpoch": 1392595200,
        "hasMoreData": false,
        "timeZone": "EST",
        "offset": 0,
        "reportPack": "Sample Audience Analytics Report Pack",
        "aggregation": "3600"
    }
}

Relevant data members:

Member Type Description
columns Array Each column provides details such as the type (metric/dimension), name, description, index of the column. If the column is of type metric, then aggregate value of the metric and the max value (peak) is also returned.
rows Array Data rows.
aggregation Number Time (seconds) over which data is aggregated.
limit Number Number of data rows returned.
offset Number The offset of the row from which the data starts.
hasMoreData Boolean true if there are more data rows for the query than returned in the response.
reportPack String Name of the report pack.
startTimeInEpoch Number Start time of the query in Unix epoch seconds.
endTimeInEpoch Number End time of the query in Unix epoch seconds.
timezone String Timezone of the report pack or timezone in which the data is returned.

List QoS monitor report packs

Returns name, id, and timezone for all report packs created for your account.

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

Status 200 application/json

Response:

[
    {
        "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"
    }
]

Relevant data members:

Member Type Description
id Number ID of the report pack.
name String Name of the report pack.
timezone String Timezone in which the data is returned.
type String This is an internal member.
subType String The type of the report-pack.

Get a QoS monitor report pack

Details include name of the report pack, data sources, and metrics and dimensions used in the report pack.

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

Example: /media-analytics/v1/qos-monitor/report-packs/26273

Parameter Type Sample Description
Required
reportPackId Number 26273 The ID of the report pack

Status 200 application/json

Response:

{
    "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": 96, "name": "Start Up Time Range", "type": "standard" },
        { "id": 57, "name": "Qos Custom Dim", "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"
}

Relevant data members:

Member Type Description
id Number ID of the report pack.
name String Name of the report pack.
dataSources Array All data sources for the report pack. A data source is a collection of raw log data with detailed information on each access to your digital property made by a user. Each data source object provides information on name of the data source and its ID.
dimensions Array All dimensions for the report pack. A dimension acts like a key in data exploration. It answers questions such as who, what, where, which. Each dimension object provides information on the name, type and ID of the dimension.
metrics Array All metrics for the report pack. A metric is a numeric aggregation against one or more dimensions. Each metric object provides information on the name and ID of the metric. It answers questions on volume of activity or attack.
dataStores Array All data stores for the report pack. A data store is a collection of dimensions and metrics stored in a data base. Each data store object provides information on the name, type, short description and ID of the data store.
timezone String Timezone in which the data is returned.
filters Array The filters applied on the data captured in the report pack.
type String This is an internal member.
subType String The type of the report-pack.

List QoS monitor data stores

A data store is a collection of dimensions and metrics stored in a database that you can use to create a sub-set and configure reports suited to your requirements. Data store details help you determine the combination of dimensions and metrics to query. Each report pack comes with its standard data stores. You cannot combine dimensions and metrics across data stores.

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

Example: /media-analytics/v1/qos-monitor/report-packs/26273/data-stores

Parameter Type Sample Description
Required
reportPackId Number 26273 The ID of the report pack.

Status 200 application/json

Response:

[
    {
        "id": 1238,
        "name": "Data Store for qos_vod",
        "type": "standard",
        "description": "Stores data relevant for qos_vod",
        "dimensions": [
            {
                "id": 83,
                "name": "Time",
                "type": "standard",
                "description": "Time as per time zone specified in the report   "
            }
        ],
        "metrics": [
            {
                "id": 323,
                "name": "HD Play Duration",
                "description": "The time over which the stream played in HD quality (>=2.5mpbs, in hours)"
            },
            {
                "id": 652,
                "name": "HQ Play Duration",
                "description": "The time over which the stream played in HQ quality (>=1.5 mpbs and <2.5mbps, in hours)"
            },
            {
                "id": 171,
                "name": "SD Play Duration",
                "description": "The time over which the stream played in SD quality (<1.5 mpbs, in hours)"
            }
        ],
        "aggregation": 60,
        "purgeIntervalInDays": 2,
        "maxQueryDurationInMinutes": 120
    },
    {
        "id": 1234,
        "name": "Sample Data Store for qos_live",
        "type": "standard",
        "description": "Stores data relevant for qos_live",
        "dimensions": [
            {
                "id": 83,
                "name": "Time",
                "type": "standard",
                "description": "Time as per time zone specified in the report   "
            },
            {
                "id": 55,
                "name": "Country",
                "type": "standard",
                "description": "Country from which viewer requested media"
            },
            {
                "id": 57,
                "name": "Continent",
                "type": "standard",
                "description": "Viewer location. Available granularities are Continent, Region, Country & City"
            }
        ],
        "metrics": [
            {
                "id": 349,
                "name": "Bitrate Views",
                "description": "Number of times the bitrate was experienced by endusers"
            },
            {
                "id": 444,
                "name": "Sessions.",
                "description": "The number of sessions that experienced a particular bitrate"
            },
            {
                "id": 344,
                "name": "Play Duration per Session.",
                "description": "The average play time per session under a particular encoded bitrate"
            }
        ],
        "aggregation": 60,
        "purgeIntervalInDays": 2,
        "maxQueryDurationInMinutes": 120
    }
]

Relevant data members:

Member Type Description
id Number ID of the data store.
name String Name of the data store.
type String Type of data store. QOS Monitor uses standard data stores.
dimensions Array All dimensions for the data store. A dimension acts like a key in data exploration. It answers questions such as who, what, where, which. Each dimension object provides information on the ID, name, type and description of the dimension.
metrics Array All metrics for the data store. A metric is a numeric aggregation against one or more dimensions. It answers questions on volume of activity or attack. Each metric object provides information on the name, description and ID of the metric.
aggregation Number Time (seconds) over which data is aggregated.
purgeIntervalInDays Number Number of days for which the data store keeps data.
maxQueryDurationInMinutes Number Maximum duration (in minutes) for which a user can query a data store. It is a system-imposed limit for better performance.
description String Text describing the data store.

Get a QoS monitor data store

Details include list of dimensions, list of metrics, aggregation interval, purge interval, maximum allowed query interval and so on.

GET /media-analytics/v1/qos-monitor/report-packs/{reportPackId}/data-stores/{dataStoreId}

Example: /media-analytics/v1/qos-monitor/report-packs/26273/data-stores/307

Parameter Type Sample Description
Required
dataStoreId Number 307 The ID of the data store.
reportPackId Number 26273 The ID of the report pack.

Status 200 application/json

Response:

{
    "aggregation": 60,
    "description": "Stores data relevant for qos_live",
    "id": 1234,
    "maxQueryDurationInMinutes": 1440,
    "name": "Sample Data Store for qos_live",
    "purgeIntervalInDays": 2,
    "type": "standard",
    "dimensions": [
        {
            "description": "Time as per time zone specified in the report   ",
            "id": 83,
            "name": "Time",
            "type": "standard"
        },
        {
            "description": "Country from which viewer requested media",
            "id": 55,
            "name": "Country",
            "type": "standard"
        },
        {
            "description": "Viewer location. Available granularities are Continent, Region, Country & City",
            "id": 57,
            "name": "Continent",
            "type": "standard"
        }
    ],
    "metrics": [
        {
            "description": "Number of times the bitrate was experienced by endusers",
            "id": 349,
            "name": "Bitrate Views"
        },
        {
            "description": "The number of sessions that experienced a particular bitrate",
            "id": 444,
            "name": "Sessions."
        },
        {
            "description": "The average play time per session under a particular encoded bitrate",
            "id": 344,
            "name": "Play Duration per Session."
        }
    ]
}

Relevant data members:

Member Type Description
id Number Data Store ID.
name String Data Store name.
type String Type of Data Store. QOS Monitor uses standard data stores.
dimensions Array All dimensions for the Data Store. A dimension acts like a key in data exploration. Each dimension object provides information on ID, name, type and description of the dimension. It answers questions such as who, what, where, which.
metrics Array All metrics for the Data Store. A metric is a numeric aggregation against one or more dimensions. Each metric object provides information on the name, description and ID of the metric. It answers questions on volume of activity or attack.
aggregation Number Time (seconds) over which data is aggregated.
purgeIntervalInDays Number Number of days for which the data store keeps data.
maxQueryDurationInMinutes Number Maximum duration (in minutes) for which a user can query a Data Store.
description String Text describing the Data Store.

List QoS monitor data sources

A data source is a collection of raw log data with detailed information on each access to your digital property made by a user.

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

Example: /media-analytics/v1/qos-monitor/report-packs/26273/data-sources

Parameter Type Sample Description
Required
reportPackId Number 26273 The ID of the report pack.

Status 200 application/json

Response:

[
    {
        "id": 2340,
        "name": "HDS Test Data Source",
        "type": "clientSide",
        "dsType": "beaconId",
        "configPath": "http://datasource.host.net/config/beacon-2340.xml",
        "values": [ "4adf65da4ecf15750" ]
    }
]

Relevant data members:

Member Type Description
id Number Data Source ID.
name String Name of the Data Source.
dsType String Data Source type.
values Array List of values that form the data source.
configPath String Represents the Beacon configuration path and is present only for clientSide data source type.

Get QoS monitor report data

Retrieves data for a specific report based on query parameter criteria. The parameters filterParams and sortParams are used to filter and sort data. The values for these parameters must be UTF–8 encoded JSON strings. Example strings are provided in the parameter description below.

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

Example: /media-analytics/v1/qos-monitor/report-packs/26273/data?startDate=03%2F22%2F2014%3A15%3A30&endDate=03%2F23%2F2014%3A15%3A30&aggregation=day%2Cweek%2Cmonth%2C3600%2C900%2C60&dimensions=160%2C96%2C57&metrics=546%2C544%2C3&limit=300&offset=100&filterParams=%5B%7B%22type%22%3A%22dimension%22%2C%22values%22%3A%5B%22GB%22%5D%2C%22id%22%3A4%2C%22condition%22%3A%22in%22%7D%2C%7B%22type%22%3A%22metric%22%2C%22values%22%3A%5B16%5D%2C%22id%22%3A155%2C%22condition%22%3A%22gt%22%7D%5D&sortParams=%5B%7B%22type%22%3A%22metric%22%2C%22order%22%3A%22asc%22%2C%22id%22%3A40%7D%5D

Headers:

  • Accept: application/json

Parameter Type Sample Description
Required
dimensions String 160,96,57 Comma-separated dimension identifiers. The ID can be obtained from the data stores API.
metrics String 546,544,3 Comma-separated metrics identifiers. The ID can be obtained from the data stores API.
reportPackId Number 26273 The ID of the report pack.
Optional
aggregation String day,week,month,3600,900,60 The aggregation in which the data is required to be grouped. It can be a number representing the aggregation in seconds or one of the following possible values day, week, month, year. If passed as a number, the allowed value is one of the aggregations of the available data stores listed by the data stores API.
endDate String 03/23/2014:15:30 The end date string in format MM/dd/yyyy:HH:mm. The time part is optional and should be in the 24-hour format.
filterParams String [{"type":"dimension","values":["GB"],"id":4,"condition":"in"},{"type":"metric","values":[16],"id":155,"condition":"gt"}] The UTF–8 URL-encoded JSON string of the filter parameters based on which the data is filtered. The structure of the JSON is explained above. By default, the data will not be filtered.
limit Number 300 The number of rows to return. Its value should lie between 1 and 10000 inclusive. If not specified, 300 rows will be returned by default.
offset Number 100 The offset of the row from which the data should start. This parameter can be used along with limit to get batches of data. For instance, if there are 1000 records in the result, 10 calls can be made with progressing offset. That is, first call with limit=100 and offset=0, second call with limit=100 and offset=100 so on and so forth. The default value is 0
sortParams String [{"type":"metric","order":"asc","id":40}] The UTF–8 URL-encoded JSON string of the sort parameters based on which the data is sorted. The structure of the JSON is explained above. By default, the data wil be sorted by time if time is selected as one of the dimensions or by the first metric in descending order if time is not selected.
startDate String 03/22/2014:15:30 The start date string in format MM/dd/yyyy:HH:mm. The time part is optional and should be in the 24-hour format.

All JSON object members of the filterParams parameter are required.

Member Type Description
Required
type Enumeration Specifies whether the parameter ID provided is a dimension or metric
id Number The ID of the filtering entity (dimension/metric).
condition String For Dimensions: in, nin, contains, ncontains, starts, nstarts, ends, nends. For Metrics: eq, neq, gt, gte, lt, lte. The n prefix reverses the result.
values Array List of values used to filter the result. Multiple values are treated as inclusions. For exclusions use another filter object with appropriate values.

All JSON object members of the sortParams parameter are required.

Member Type Description
Required
type Enumeration Specifies whether the parameter ID provided is a dimension or metric
id Number The ID of the sorting entity.
order Enumeration Represents asc for ascending or desc for descending order.

Status 200 application/json

Response:

{
    "columns": [
        { "name": "Country", "aggregate": "-", "index": 0 },
        { "name": "Region", "aggregate": "-", "index": 1 },
        { "name": "% Rebuffering Plays", "aggregate": "20.06", "index": 2 }
    ],
    "rows": [
        [ "GB", "WA", "18.15" ],
        [ "GB", "EN", "16.74" ],
        [ "GB", "NI", "66.06" ]
    ],
    "metaData": {
        "limit": 3,
        "endTimeInEpoch": 1392598800,
        "startTimeInEpoch": 1392595200,
        "timeZone": "EST",
        "hasMoreData": false,
        "offset": 0,
        "reportPack": "Sample QoS Monitor Report Pack",
        "aggregation": "3600"
    }
}

Relevant data members:

Member Type Description
columns Array Each column provides details such as the type (metric/dimension), name, description, index of the column. If the column is of type metric, then aggregate value of the metric and the max value (peak) is also returned.
rows Array Data rows.
aggregation Number Time (seconds) over which data is aggregated.
limit Number Number of data rows returned.
offset Number The offset of the row from which the data starts.
hasMoreData Boolean true if there are more data rows for the query than returned in the response.
reportPack String Name of the report pack.
startTimeInEpoch Number Start time of the query in Unix epoch seconds.
endTimeInEpoch Number End time of the query in Unix epoch seconds.
timezone String Timezone of the report pack or timezone in which the data is returned.

List viewer diagnostics report packs

Returns name, id, and timezone for all report packs created for your account.

GET /media-analytics/v1/viewer-diagnostics/report-packs

Status 200 application/json

Response:

[
    {
        "id": 2340,
        "name": "Sample Viewer Diags",
        "isActive": true,
        "type": "ma",
        "subType": "Viewer Diagnostics",
        "timezone": "EST5EDT"
    }
]

Relevant data members:

Member Type Description
id Number ID of the report pack.
name String Name of the report pack.
timezone String Timezone in which the data is returned.
type String This is an internal member.
subType String The type of the report-pack.

Get a viewer diagnostics report pack

Details include name of the report pack, data sources, and metrics and dimensions used in the report pack.

GET /media-analytics/v1/viewer-diagnostics/report-packs/{reportPackId}

Example: /media-analytics/v1/viewer-diagnostics/report-packs/26273

Parameter Type Sample Description
Required
reportPackId Number 26273 The ID of the report pack

Status 200 application/json

Response:

{
    "id": 23040,
    "name": "Sample Viewer Diagnostics Report Pack",
    "isActive": true,
    "type": "ma",
    "subType": "Viewer Diagnostics",
    "dataSources": [
        { "id": 4444, "name": "Sample Stream" },
        { "id": 1111, "name": "HTML5 Player" },
        { "id": 2222, "name": "Audience Analytics" }
    ],
    "dimensions": [
        { "id": 123111, "name": "Session ID", "type": "standard" },
        { "id": 321212, "name": "Time", "type": "standard" },
        { "id": 45645, "name": "Viewer ID", "type": "standard" },
        { "id": 789456, "name": "Visit ID", "type": "standard" }
    ],
    "metrics": [
        { "id": 89911, "name": "Ad Abandoned" },
        { "id": 99811, "name": "Ad Plays " },
        { "id": 112211, "name": "Visit End Time" },
        { "id": 211211, "name": "Visit Start Time" }
    ],
    "filters": [
        {
            "name": "Includes Channel 1 Viewers",
            "type": "Include",
            "condition": "matches",
            "value": "Sample Channel 1",
            "id": 12221
        },
        {
            "name": "Includes Channel 2 Viewers",
            "type": "Include",
            "condition": "matches",
            "value": "Sample Channel 2",
            "id": 12221
        }
    ],
    "dataStores": [
        {
            "id": 22221,
            "name": "Viewer Diagnostic",
            "type": "standard",
            "description": "Viewer Diagnostic"
        }
    ],
    "timezone": "EST5EDT"
}

Relevant data members:

Member Type Description
id Number ID of the report pack.
name String Name of the report pack.
dataSources Array All data sources for the report pack. A data source is a collection of raw log data with detailed information on each access to your digital property made by a user. Each data source object provides information on name of the data source and its ID.
dimensions Array All dimensions for the report pack. A dimension acts like a key in data exploration. It answers questions such as who, what, where, which. Each dimension object provides information on the name, type and ID of the dimension.
metrics Array All metrics for the report pack. A metric is a numeric aggregation against one or more dimensions. Each metric object provides information on the name and ID of the metric. It answers questions on volume of activity or attack.
dataStores Array All data stores for the report pack. A data store is a collection of dimensions and metrics stored in a data base. Each data store object provides information on the name, type, short description and ID of the data store.
timezone String Timezone in which the data is returned.
filters Array The filters applied on the data captured in the report pack.
type String This is an internal member.
subType String The type of the report-pack.

List viewer diagnostics data stores

A data store is a collection of dimensions and metrics stored in a database that you can use to create a sub-set and configure reports suited to your requirements. Data store details help you determine the combination of dimensions and metrics to query. Each report pack comes with its standard data stores. You cannot combine dimensions and metrics across data stores.

GET /media-analytics/v1/viewer-diagnostics/report-packs/{reportPackId}/data-stores

Example: /media-analytics/v1/viewer-diagnostics/report-packs/26273/data-stores

Parameter Type Sample Description
Required
reportPackId Number 26273 The ID of the report pack.

Status 200 application/json

Response:

[
    {
        "id": 22221,
        "name": "Viewer Diagnostic",
        "type": "standard",
        "description": "Viewer Diagnostic",
        "dimensions": [
            {
                "id": 123111,
                "name": "Session ID",
                "description": "Session ID",
                "type": "standard"
            },
            {
                "id": 321212,
                "name": "Time",
                "description": "Set automatically and indicates the Timestamp at which content was consumed and is converted to the time zone set during report pack configuration.",
                "type": "standard"
            },
            {
                "id": 45645,
                "name": "Viewer ID",
                "description": "Viewer ID",
                "type": "standard"
            },
            {
                "id": 789456,
                "name": "Visit ID",
                "description": "Visit ID",
                "type": "standard"
            }
        ],
        "metrics": [
            { "id": 89911, "name": "Ad Abandoned", "description": "Ad Abandoned" },
            { "id": 99811, "name": "Ad Plays ", "description": "Ad Plays " },
            { "id": 112211, "name": "Visit End Time", "description": "Visit End Time" },
            { "id": 211211, "name": "Visit Start Time", "description": "Visit Start Time" }
        ],
        "aggregation": 86400,
        "purgeIntervalInDays": 60,
        "maxQueryDurationInMinutes": 600
    }
]

Relevant data members:

Member Type Description
id Number ID of the data store.
name String Name of the data store.
type String Type of data store. Viewer Diagnostic uses standard data stores.
dimensions Array All dimensions for the data store. A dimension acts like a key in data exploration. It answers questions such as who, what, where, which. Each dimension object provides information on the ID, name, type and description of the dimension.
metrics Array All metrics for the data store. A metric is a numeric aggregation against one or more dimensions. It answers questions on volume of activity or attack. Each metric object provides information on the name, description and ID of the metric.
aggregation Number Time (seconds) over which data is aggregated.
purgeIntervalInDays Number Number of days for which the data store keeps data.
maxQueryDurationInMinutes Number Maximum duration (in minutes) for which a user can query a data store. It is a system-imposed limit for better performance.
description String Text describing the data store.

Get a viewer diagnostics data store

Details include list of dimensions, list of metrics, aggregation interval, purge interval, maximum allowed query interval and so on.

GET /media-analytics/v1/viewer-diagnostics/report-packs/{reportPackId}/data-stores/{dataStoreId}

Example: /media-analytics/v1/viewer-diagnostics/report-packs/26273/data-stores/307

Parameter Type Sample Description
Required
dataStoreId Number 307 The ID of the data store.
reportPackId Number 26273 The ID of the report pack.

Status 200 application/json

Response:

{
    "id": 22221,
    "name": "Viewer Diagnostic",
    "type": "standard",
    "description": "Viewer Diagnostic",
    "dimensions": [
        {
            "id": 123111,
            "name": "Session ID",
            "description": "Session ID",
            "type": "standard"
        },
        {
            "id": 321212,
            "name": "Time",
            "description": "Set automatically and indicates the Timestamp at which content was consumed and is converted to the time zone set during report pack configuration.",
            "type": "standard"
        },
        {
            "id": 45645,
            "name": "Viewer ID",
            "description": "Viewer ID",
            "type": "standard"
        },
        {
            "id": 789456,
            "name": "Visit ID",
            "description": "Visit ID",
            "type": "standard"
        }
    ],
    "metrics": [
        { "id": 89911, "name": "Ad Abandoned", "description": "Ad Abandoned" },
        { "id": 99811, "name": "Ad Plays ", "description": "Ad Plays " },
        { "id": 112211, "name": "Visit End Time", "description": "Visit End Time" },
        { "id": 211211, "name": "Visit Start Time", "description": "Visit Start Time" }
    ],
    "aggregation": 86400,
    "purgeIntervalInDays": 60,
    "maxQueryDurationInMinutes": 600
}

Relevant data members:

Member Type Description
id Number Data Store ID.
name String Data Store name.
type String Type of Data Store. Viewer Diagnostic uses standard data stores.
dimensions Array All dimensions for the Data Store. A dimension acts like a key in data exploration. Each dimension object provides information on ID, name, type and description of the dimension. It answers questions such as who, what, where, which.
metrics Array All metrics for the Data Store. A metric is a numeric aggregation against one or more dimensions. Each metric object provides information on the name, description and ID of the metric. It answers questions on volume of activity or attack.
aggregation Number Time (seconds) over which data is aggregated.
purgeIntervalInDays Number Number of days for which the data store keeps data.
maxQueryDurationInMinutes Number Maximum duration (in minutes) for which a user can query a Data Store.
description String Text describing the Data Store.

List viewer diagnostics data sources

A data source is a collection of raw log data with detailed information on each access to your digital property made by a user.

GET /media-analytics/v1/viewer-diagnostics/report-packs/{reportPackId}/data-sources

Example: /media-analytics/v1/viewer-diagnostics/report-packs/26273/data-sources

Parameter Type Sample Description
Required
reportPackId Number 26273 The ID of the report pack.

Status 200 application/json

Response:

[
    {
        "id": 4444,
        "name": "Sample Stream",
        "type": "clientSide",
        "dsType": "beaconId",
        "configPath": null,
        "values": [ "a1phanum3rica15tr1ng" ]
    },
    {
        "id": 1111,
        "name": "HTML5 Player",
        "type": "clientSide",
        "dsType": "beaconId",
        "configPath": "http://config.server/config/beacon-config.xml",
        "values": [ "a1phanum3rica15tr1ng" ]
    },
    {
        "id": 2222,
        "name": "Audience Analytics",
        "type": "clientSide",
        "dsType": "beaconId",
        "configPath": "http://ma102-r.analytics.edgesuite.net/config/beacon-config.xml",
        "values": [ "a1phanum3rica15tr1ng" ]
    }
]

Relevant data members:

Member Type Description
id Number Data Source ID.
name String Name of the Data Source.
dsType String Data Source type.
values Array List of values that form the data source.
configPath String Represents the Beacon configuration path and is present only for clientSide data source type.

Get viewer diagnostics report data

Retrieves data for a specific report based on query parameter criteria. The parameters filterParams and sortParams are used to filter and sort data. The values for these parameters must be UTF–8 encoded JSON strings. Example strings are provided in the parameter description below.

GET /media-analytics/v1/viewer-diagnostics/report-packs/{reportPackId}/viewers/{viewerId}/data{?startDate,endDate,aggregation,dimensions,metrics,limit,offset,filterParams,sortParams}

Example: /media-analytics/v1/viewer-diagnostics/report-packs/26273/viewers/2340/data?startDate=03%2F22%2F2014&endDate=03%2F23%2F2014&aggregation=day%2Cmonth%2C3600%2C900%2C60&dimensions=160%2C96%2C57&metrics=546%2C544%2C3&limit=300&offset=100&filterParams=%5B%7B%22type%22%3A%22dimension%22%2C%22values%22%3A%5B%22GB%22%5D%2C%22id%22%3A4%2C%22condition%22%3A%22in%22%7D%2C%7B%22type%22%3A%22metric%22%2C%22values%22%3A%5B16%5D%2C%22id%22%3A155%2C%22condition%22%3A%22gt%22%7D%5D&sortParams=%5B%7B%22type%22%3A%22metric%22%2C%22order%22%3A%22asc%22%2C%22id%22%3A40%7D%5D

Headers:

  • Accept: application/json

Parameter Type Sample Description
Required
dimensions String 160,96,57 Comma-separated dimension identifiers. The ID can be obtained from the data stores API.
metrics String 546,544,3 Comma-separated metrics identifiers. The ID can be obtained from the data stores API.
reportPackId Number 26273 The ID of the report pack.
viewerId Number 2340 The ID representing the viewer.
Optional
aggregation String day,month,3600,900,60 The aggregation in which the data is required to be grouped. It can be a number representing the aggregation in seconds or one of the following possible valuesday, week, month, year. If passed as a number, the allowed value is one of the aggregations of the available data stores listed by the data stores API.
endDate String 03/23/2014 The end date string in format MM/dd/yyyy:HH:mm. The time part is optional and should be in the 24-hour format. Depending on the aggregation of the data-store, time part may or may not be applicable. All the data-stores are of daily aggregation for Viewer Diagnostic.
filterParams String [{"type":"dimension","values":["GB"],"id":4,"condition":"in"},{"type":"metric","values":[16],"id":155,"condition":"gt"}] The UTF–8 URL-encoded JSON string of the filter parameters based on which the data is filtered. The structure of the JSON is explained above. By default, the data will not be filtered.
limit Number 300 The number of rows to return. Its value should lie between 1 and 10000 inclusive. If not specified, 300 rows will be returned by default.
offset Number 100 The offset of the row from which the data should start. This parameter can be used along with limit to get batches of data. For instance, if there are 1000 records in the result, 10 calls can be made with progressing offset. That is, first call with limit=100 and offset=0, second call with limit=100 and offset=100 so on and so forth. The default value is 0
sortParams String [{"type":"metric","order":"asc","id":40}] The UTF–8 URL-encoded JSON string of the sort parameters based on which the data is sorted. The structure of the JSON is explained above. By default, the data wil be sorted by time if time is selected as one of the dimensions or by the first metric in descending order if time is not selected.
startDate String 03/22/2014 The start date string in format MM/dd/yyyy:HH:mm. The time part is optional and should be in the 24-hour format. Depending on the aggregation of the data-store, time part may or may not be applicable. All the data-stores are of daily aggregation for Viewer Diagnostic.

All JSON object members of the filterParams parameter are required.

Member Type Description
Required
type Enumeration Specifies whether the parameter ID provided is a dimension or metric
id Number The ID of the filtering entity (dimension/metric).
condition String For Dimensions: in, nin, contains, ncontains, starts, nstarts, ends, nends. For Metrics: eq, neq, gt, gte, lt, lte. The n prefix reverses the result.
values Array List of values used to filter the result. Multiple values are treated as inclusions. For exclusions use another filter object with appropriate values.

All JSON object members of the sortParams parameter are required.

Member Type Description
Required
type Enumeration Specifies whether the parameter ID provided is a dimension or metric
id Number The ID of the sorting entity.
order Enumeration Represents asc for ascending or desc for descending order.

Status 200 application/json

Response:

{
    "columns": [
        {
            "name": "Time",
            "aggregate": "-",
            "unit": null,
            "index": 0
        },
        {
            "name": "Title",
            "aggregate": "Unthinkable Trailer",
            "unit": null,
            "index": 2
        },
        {
            "name": "Average Bitrate ",
            "aggregate": "843.38",
            "unit": "kbps",
            "index": 3
        }
    ],
    "rows": [
        [ "1399791600", "Unthinkable Trailer", "200.00" ],
        [ "1399791600", "Unthinkable Trailer", "250.00" ]
    ],
    "metaData": {
        "limit": 100,
        "startTimeInEpoch": 1399705200,
        "aggregation": 86400,
        "hasMoreData": false,
        "timeZone": "PDT",
        "endTimeInEpoch": 1400137200,
        "offset": 0,
        "reportPack": "Sample Viewer Diagnostics"
    }
}

Relevant data members:

Member Type Description
columns Array Each column provides details such as the type (metric/dimension), name, description, index of the column. If the column is of type metric, then aggregate value of the metric and the max value (peak) is also returned.
rows Array Data rows.
aggregation Number Time (seconds) over which data is aggregated.
limit Number Number of data rows returned.
offset Number The offset of the row from which the data starts.
hasMoreData Boolean true if there are more data rows for the query than returned in the response.
reportPack String Name of the report pack.
startTimeInEpoch Number Start time of the query in Unix epoch seconds.
endTimeInEpoch Number End time of the query in Unix epoch seconds.
timezone String Timezone of the report pack or timezone in which the data is returned.

List download analytics report packs

Returns name, id, and timezone for all report packs created for your account.

GET /media-analytics/v1/download-analytics/report-packs

Status 200 application/json

Response:

[
    {
        "id": 123,
        "name": "Demo Analyzer",
        "isActive": false,
        "type": "dla",
        "subType": "Downloads",
        "timezone": "GMT"
    },
    {
        "id": 456,
        "name": "Internal Analyzer",
        "isActive": false,
        "type": "dla",
        "subType": "Downloads",
        "timezone": "GMT"
    }
]

Relevant data members:

Member Type Description
id Number ID of the report pack.
name String Name of the report pack.
timezone String Timezone in which the data is returned.
type String This is an internal member.
subType String The type of the report-pack.

Get a download analytics report pack

Details include name of the report pack, data sources, and metrics and dimensions used in the report pack.

GET /media-analytics/v1/download-analytics/report-packs/{reportPackId}

Example: /media-analytics/v1/download-analytics/report-packs/26273

Parameter Type Sample Description
Required
reportPackId Number 26273 The ID of the report pack

Status 200 application/json

Response:

{
    "id": 123,
    "name": "Demo Analyzer",
    "isActive": false,
    "type": "dla",
    "subType": "Downloads",
    "dataSources": [
        { "id": 11, "name": "dlm Datasource" }
    ],
    "dimensions": [
        { "id": 104, "name": "City", "type": "standard" },
        { "id": 461, "name": "Connection Speed", "type": "standard" },
        { "id": 101, "name": "Continent", "type": "standard" }
    ],
    "metrics": [
        { "id": 17, "name": "Bytes Delivered (Sum)" },
        { "id": 22, "name": "Completion Rate" }
    ],
    "filters": [
        {
            "name": "URL image filter",
            "type": "Exclude",
            "condition": "endswith",
            "value": ".GIF",
            "id": 269
        }
    ],
    "dataStores": [
        {
            "id": 307,
            "name": "DLM Cube",
            "type": "standard",
            "description": "DLM Cube"
        },
        {
            "id": 306,
            "name": "Summary Cube",
            "type": "standard",
            "description": "Summary Cube"
        }
    ],
    "timezone": "GMT"
}

Relevant data members:

Member Type Description
id Number ID of the report pack.
name String Name of the report pack.
dataSources Array All data sources for the report pack. A data source is a collection of raw log data with detailed information on each access to your digital property made by a user. Each data source object provides information on name of the data source and its ID.
dimensions Array All dimensions for the report pack. A dimension acts like a key in data exploration. It answers questions such as who, what, where, which. Each dimension object provides information on the name, type and ID of the dimension.
metrics Array All metrics for the report pack. A metric is a numeric aggregation against one or more dimensions. Each metric object provides information on the name and ID of the metric. It answers questions on volume of activity or attack.
dataStores Array All data stores for the report pack. A data store is a collection of dimensions and metrics stored in a data base. Each data store object provides information on the name, type, short description and ID of the data store.
timezone String Timezone in which the data is returned.
filters Array The filters applied on the data captured in the report pack.
type String This is an internal member.
subType String The type of the report-pack.

List download analytics data stores

A data store is a collection of dimensions and metrics stored in a database that you can use to create a sub-set and configure reports suited to your requirements. Data store details help you determine the combination of dimensions and metrics to query. Each report pack comes with its standard data stores. You cannot combine dimensions and metrics across data stores.

GET /media-analytics/v1/download-analytics/report-packs/{reportPackId}/data-stores

Example: /media-analytics/v1/download-analytics/report-packs/26273/data-stores

Parameter Type Sample Description
Required
reportPackId Number 26273 The ID of the report pack.

Status 200 application/json

Response:

[
    {
        "id": 307,
        "name": "DLM Cube",
        "type": "standard",
        "description": "DLM Cube",
        "dimensions": [
            {
                "id": 104,
                "name": "City",
                "description": "name of city",
                "type": "standard"
            },
            {
                "id": 461,
                "name": "Connection Speed",
                "description": "Connection Speed",
                "type": "standard"
            },
            {
                "id": 101,
                "name": "Continent",
                "description": "Viewer location. Available granularities are Continent, Region, Country boston",
                "type": "standard"
            }
        ],
        "metrics": [
            {
                "id": 17,
                "name": "Bytes Delivered (Sum)",
                "unit": "bytes",
                "type": null,
                "description": "Total Bytes Delivered"
            },
            {
                "id": 28,
                "name": "DLM Cancels",
                "unit": null,
                "type": null,
                "description": "Total Cancels for Akamai DLM"
            },
            {
                "id": 19,
                "name": "DLM Completes",
                "unit": null,
                "type": null,
                "description": "Total Completions from DLM"
            }
        ],
        "aggregationInSeconds": 86400,
        "purgeIntervalInDays": 403,
        "maxQueryDurationInMinutes": 580320
    },
    {
        "id": 306,
        "name": "Summary Cube",
        "type": "standard",
        "description": "Summary Cube",
        "dimensions": [
            {
                "id": 461,
                "name": "Connection Speed",
                "description": "Connection Speed",
                "type": "standard"
            },
            {
                "id": 101,
                "name": "Continent",
                "description": "Viewer location. Available granularities are Continent, Region, Country boston",
                "type": "standard"
            },
            {
                "id": 102,
                "name": "Country",
                "description": "country",
                "type": "standard"
            },
            {
                "id": 400,
                "name": "Day",
                "description": "Time Dimension for DLA",
                "type": "standard"
            }
        ],
        "metrics": [
            {
                "id": 17,
                "name": "Bytes Delivered (Sum)",
                "unit": "bytes",
                "type": null,
                "description": "Total Bytes Delivered"
            },
            {
                "id": 22,
                "name": "Completion Rate",
                "unit": "%",
                "type": null,
                "description": "Completion Rates"
            },
            {
                "id": 35,
                "name": "Completion Rate",
                "unit": "%",
                "type": null,
                "description": "Average Completion Rate for Akamai DLM"
            },
            {
                "id": 43,
                "name": "File Size",
                "unit": "bytes",
                "type": null,
                "description": "Average FileSize"
            }
        ],
        "aggregationInSeconds": 86400,
        "purgeIntervalInDays": 403,
        "maxQueryDurationInMinutes": 580320
    }
]

Relevant data members:

Member Type Description
id Number ID of the data store.
name String Name of the data store.
type String Type of data store (standard or custom).
dimensions Array All dimensions for the data store. A dimension acts like a key in data exploration. It answers questions such as who, what, where, which. Each dimension object provides information on the ID, name, type and description of the dimension.
metrics Array All metrics for the data store. A metric is a numeric aggregation against one or more dimensions. It answers questions on volume of activity or attack. Each metric object provides information on the name, description and ID of the metric.
aggregation Number Time (seconds) over which data is aggregated.
purgeIntervalInDays Number Number of days for which the data store keeps data.
maxQueryDurationInMinutes Number Maximum duration (in minutes) for which a user can query a data store. It is a system-imposed limit for better performance.
description String Text describing the data store.

Get a download analytics data store

Details include list of dimensions, list of metrics, aggregation interval, purge interval, maximum allowed query interval and so on.

GET /media-analytics/v1/download-analytics/report-packs/{reportPackId}/data-stores/{dataStoreId}

Example: /media-analytics/v1/download-analytics/report-packs/26273/data-stores/307

Parameter Type Sample Description
Required
dataStoreId Number 307 The ID of the data store.
reportPackId Number 26273 The ID of the report pack.

Status 200 application/json

Response:

{
    "aggregationInSeconds": 86400,
    "description": "DLM Cube",
    "id": 307,
    "maxQueryDurationInMinutes": 580320,
    "name": "DLM Cube",
    "purgeIntervalInDays": 403,
    "type": "standard",
    "dimensions": [
        {
            "description": "name of city",
            "id": 104,
            "name": "City",
            "type": "standard"
        },
        {
            "description": "Connection Speed",
            "id": 461,
            "name": "Connection Speed",
            "type": "standard"
        },
        {
            "description": "Viewer location. Available granularities are Continent, Region, Country boston",
            "id": 101,
            "name": "Continent",
            "type": "standard"
        }
    ],
    "metrics": [
        {
            "description": "Total Bytes Delivered",
            "id": 17,
            "name": "Bytes Delivered (Sum)",
            "type": null,
            "unit": "bytes"
        },
        {
            "description": "Total Cancels for Akamai DLM",
            "id": 28,
            "name": "DLM Cancels",
            "type": null,
            "unit": null
        },
        {
            "description": "Total Completions from DLM",
            "id": 19,
            "name": "DLM Completes",
            "type": null,
            "unit": null
        }
    ]
}

Relevant data members:

Member Type Description
id Number Data Store ID.
name String Data Store name.
type String Type of Data Store (standard or custom).
dimensions Array All dimensions for the Data Store. A dimension acts like a key in data exploration. Each dimension object provides information on ID, name, type and description of the dimension. It answers questions such as who, what, where, which.
metrics Array All metrics for the Data Store. A metric is a numeric aggregation against one or more dimensions. Each metric object provides information on the name, description and ID of the metric. It answers questions on volume of activity or attack.
aggregation Number Time (seconds) over which data is aggregated.
purgeIntervalInDays Number Number of days for which the data store keeps data.
maxQueryDurationInMinutes Number Maximum duration (in minutes) for which a user can query a Data Store.
description String Text describing the Data Store.

List download analytics data sources

A data source is a collection of raw log data with detailed information on each access to your digital property made by a user.

GET /media-analytics/v1/download-analytics/report-packs/{reportPackId}/data-sources

Example: /media-analytics/v1/download-analytics/report-packs/26273/data-sources

Parameter Type Sample Description
Required
reportPackId Number 26273 Report pack ID.

Status 200 application/json

Response:

[
    {
        "id": 419,
        "name": "dlm Datasource",
        "type": "serverSide",
        "dsType": "cpCode",
        "values": [ "7907" ]
    }
]

Relevant data members:

Member Type Description
id Number Data Source ID.
name String Name of the Data Source.
dsType String Data Source type.
values Array List of values that form the data source.
configPath String Represents the Beacon configuration path and is present only for clientSide data source type.

Get download analytics report data

Retrieves data for a specific report based on query parameter criteria. The parameters filterParams and sortParams are used to filter and sort data. The values for these parameters must be UTF–8 encoded JSON strings. Example strings are provided in the parameter description below.

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

Example: /media-analytics/v1/download-analytics/report-packs/26273/data?startDate=03%2F22%2F2014%3A15%3A30&endDate=03%2F23%2F2014%3A15%3A30&aggregation=day%2Cmonth%2C3600%2C900%2C60&dimensions=160%2C96%2C57&metrics=546%2C544%2C3&limit=300&offset=100&filterParams=%5B%7B%22type%22%3A%22dimension%22%2C%22values%22%3A%5B%22GB%22%5D%2C%22id%22%3A4%2C%22condition%22%3A%22in%22%7D%2C%7B%22type%22%3A%22metric%22%2C%22values%22%3A%5B16%5D%2C%22id%22%3A155%2C%22condition%22%3A%22gt%22%7D%5D&sortParams=%5B%7B%22type%22%3A%22metric%22%2C%22order%22%3A%22asc%22%2C%22id%22%3A40%7D%5D

Headers:

  • Accept: application/json

Parameter Type Sample Description
Required
dimensions String 160,96,57 Comma-separated dimension identifiers. The ID can be obtained from the data stores API.
metrics String 546,544,3 Comma-separated metrics identifiers. The ID can be obtained from the data stores API.
reportPackId Number 26273 The ID of the report pack.
Optional
aggregation String day,month,3600,900,60 The aggregation in which the data is required to be grouped. It can be a number representing the aggregation in seconds or one of the following possible values day, week, month, year. If passed as a number, the allowed value is one of the aggregations of the available data stores listed by the data stores API.
endDate String 03/23/2014:15:30 The end date string in format MM/dd/yyyy:HH:mm. The time part is optional and should be in the 24-hour format.
filterParams String [{"type":"dimension","values":["GB"],"id":4,"condition":"in"},{"type":"metric","values":[16],"id":155,"condition":"gt"}] The UTF–8 URL-encoded JSON string of the filter parameters based on which the data is filtered. The structure of the JSON is explained above. By default, the data will not be filtered.
limit Number 300 The number of rows to return. Its value should lie between 1 and 10000 inclusive. If not specified, 300 rows will be returned by default.
offset Number 100 The offset of the row from which the data should start. This parameter can be used along with limit to get batches of data. For instance, if there are 1000 records in the result, 10 calls can be made with progressing offset. That is, first call with limit=100 and offset=0, second call with limit=100 and offset=100 so on and so forth. The default value is 0
sortParams String [{"type":"metric","order":"asc","id":40}] The UTF–8 URL-encoded JSON string of the sort parameters based on which the data is sorted. The structure of the JSON is explained above. By default, the data wil be sorted by time if time is selected as one of the dimensions or by the first metric in descending order if time is not selected.
startDate String 03/22/2014:15:30 The start date string in format MM/dd/yyyy:HH:mm. The time part is optional and should be in the 24-hour format.

All JSON object members of the filterParams parameter are required.

Member Type Description
Required
type Enumeration Specifies whether the parameter ID provided is a dimension or metric
id Number The ID of the filtering entity (dimension/metric).
condition String For Dimensions: in, nin, contains, ncontains, starts, nstarts, ends, nends. For Metrics: eq, neq, gt, gte, lt, lte. The n prefix reverses the result.
values Array List of values used to filter the result. Multiple values are supported for dimension filters.

All JSON object members of the sortParams parameter are required.

Member Type Description
Required
type Enumeration Specifies whether the parameter ID provided is a dimension or metric
id Number The ID of the sorting entity.
order Enumeration Represents asc for ascending or desc for descending order.

Status 200 application/json

Response:

{
    "columns": [
        { "name": "Country", "aggregate": "-", "index": 0 },
        { "name": "Region", "aggregate": "-", "index": 1 },
        { "name": "Bytes Delivered (Sum)", "aggregate": "20.06", "index": 2 }
    ],
    "rows": [
        [ "GB", "WA", "18.15" ],
        [ "GB", "EN", "16.74" ],
        [ "GB", "NI", "66.06" ]
    ],
    "metaData": {
        "limit": 3,
        "endTimeInEpoch": 1392598800,
        "startTimeInEpoch": 1392595200,
        "hasMoreData": false,
        "timeZone": "EST",
        "offset": 0,
        "reportPack": "Sample Download Analytics Report Pack",
        "aggregation": "3600"
    }
}

Relevant data members:

Member Type Description
columns Array Each column provides details such as the type (metric/dimension), name, description, index of the column. If the column is of type metric, then aggregate value of the metric and the max value (peak) is also returned.
rows Array Data rows.
aggregation Number Time (seconds) over which data is aggregated.
limit Number Number of data rows returned.
offset Number The offset of the row from which the data starts.
hasMoreData Boolean true if there are more data rows for the query than returned in the response.
reportPack String Name of the report pack.
startTimeInEpoch Number Start time of the query in Unix epoch seconds.
endTimeInEpoch Number End time of the query in Unix epoch seconds.
timezone String Timezone of the report pack or timezone in which the data is returned.

Errors

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.
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"
}