Media Analytics API

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

Learn more:


Overview

The Media Analytics API allows you to capture and monitor viewer engagement details through both simple and complex reports. Information on how quality of service impacts performance helps you deliver the online video experience viewers demand. Key video analytics is a critical piece of successful content publishing.

Important note. You can access Audience Analytics, Download Analytics, and Viewer Diagnostics API endpoints at Media Analytics API v1.

Getting started

To configure this API for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named Media Analytics API, and set the access level to READ-ONLY.

Rate limiting

The Media Analytics API imposes a rate-limiting constraint of 20 requests per minute. Exceeding that limit results in a 429-error response. Consider this especially when calling successive operations as part of a loop. The following response headers provide rate limit information:

  • X-RateLimit-Limit: The maximum number of tokens allowed.

  • X-RateLimit-Remaining: The number of tokens remaining.

  • X-RateLimit-Next: The time when you can make one more request. For example: 2018-05-11T07:04:40.004Z.

Once X-RateLimit-Remaining becomes 0, you get a 429 error the next time you make an API call.

If you do not make any more API calls after you receive a 429 error, X-RateLimit-Remaining gradually increases and becomes equal to X-RateLimit-Limit.

API workflow

Follow the steps below to query a report:

  1. Retrieve information on the report packs available for the account.

  2. Choose a report pack from which you can extract data store metadata that provides information on the metrics and dimensions grouped together in the report pack.

  3. Select the required combinations of metrics and dimensions to create customized reports tailored to your specifications.

Step 1: Retrieve report pack

You can retrieve report packs using the resource given below. Skip this step if you already know the report pack you need. The sample request and response below shows how to generate a QoS Monitor report pack: (See List QoS Monitor report packs):

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

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

Report pack details include report pack name, data stores, data sources, metrics, and dimensions used in the report pack.

You can run the API operation below to retrieve details for a specific report pack using its ID as a parameter:

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

The sample request and response below shows how to generate a QoS Monitor report: (See Get a QoS Monitor report pack):.

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

    {
        "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 to 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

To retrieve data for a specific report, you can use the sample request and response below that shows how to generate a QoS Monitor report. The first GET line represents the URL template syntax. The second GET line is an actual sample URL (See Get QoS Monitor report data):

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

Assume that the dimension ID 12,57 represents Time and the metric ID 437 represents the metric Plays with Rebuffers. The sample URL below reports on the number of plays with rebuffers by time for a period starting 11/13/2014:00:00 to 11/13/2014:05:00 for a specific report pack:

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

    {
        "columns": [
            {
                "type": "dimension",
                "name": "Time",
                "description": "Indicates the time at which content was consumed in the time zone specified in the report pack.",
                "index": 0
            },
            {
                "type": "dimension",
                "name": "Country",
                "description": "Country from which media was requested. ",
                "index": 1
            },
            {
                "type": "metric",
                "name": "Plays with Rebuffers",
                "description": "Sum of plays with at least one rebuffering event.",
                "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
        }
    }

Resources

This section provides details on the API’s various URL resources and the methods and parameters you use to call them.

Below is a road map of all the conceptual objects you deal with when interacting with the Media Analytics API:

  • Report pack: A set of data stores that include dimensions and metrics of interest aggregated over time.

  • Report: Dimensions and metrics combined together to provide in-depth information on gathered data.

  • Data store: A database that hosts a collection of dimensions and metrics for use in creating a report. 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.

  • Data source: A data source is a collection of raw log data consisting of detailed information for each end-user access attempt made to your digital property.

  • Dimensions: Dimensions in a data store are slotted into three information deriving levels: viewer, visit and play. Title, device, and city are some examples of dimensions.

  • Metrics: A metric is a parameter by which we can measure dimensions. Startup time, availability, connection speed, and audience size are some examples of metrics.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List QoS Monitor report packs GET /media-analytics/v2/qos-monitor/report-packs
Get a QoS Monitor report pack GET /media-analytics/v2/qos-monitor/report-packs/{reportPackId}
List QoS Monitor data stores GET /media-analytics/v2/qos-monitor/report-packs/{reportPackId}/data-stores
Get a QoS Monitor data store GET /media-analytics/v2/qos-monitor/report-packs/{reportPackId}/data-stores/{dataStoreId}
List QoS Monitor data sources GET /media-analytics/v2/qos-monitor/report-packs/{reportPackId}/data-sources
Get QoS Monitor report data GET /media-analytics/v2/qos-monitor/report-packs/{reportPackId}/data{?dimensions,metrics,startDate,endDate,limit,offset,aggregation,filterParams,sortParams}

List QoS Monitor report packs

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

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

Status 200 application/json

Response Body:

[
    {
        "id": 6833,
        "name": "ReportPack Qos",
        "isActive": true,
        "type": "qos",
        "subType": "QOS Monitor - All",
        "timezone": "GMT"
    },
    {
        "id": 6311,
        "name": "HDS Test",
        "isActive": true,
        "type": "qos",
        "subType": "QOS Monitor - All",
        "timezone": "Asia/Calcutta"
    }
]

Get a QoS Monitor report pack

Retrieves report pack name, data sources, metrics, and dimensions used in the report pack.

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

Sample: /media-analytics/v2/qos-monitor/report-packs/26273

Parameter Type Sample Description
URL parameters
reportPackId Number 26273 Unique identifier for each report pack.

Status 200 application/json

Response Body:

{
    "id": 6311,
    "name": "HDS Test",
    "isActive": true,
    "type": "qos",
    "subType": "QOS Monitor - All",
    "dataSources": [
        {
            "id": 4553,
            "name": "Qos monitor data Source"
        }
    ],
    "dimensions": [
        {
            "id": 975,
            "name": "Future Use #1"
        },
        {
            "id": 934,
            "name": "AS Name",
            "type": "standard"
        },
        {
            "id": 2934,
            "name": "Browser",
            "type": "standard"
        },
        {
            "id": 90,
            "name": "Category",
            "type": "standard"
        },
        {
            "id": 933,
            "name": "City",
            "type": "standard"
        },
        {
            "id": 81,
            "name": "Connection Speed",
            "type": "standard"
        },
        {
            "id": 77,
            "name": "Continent",
            "type": "standard"
        },
        {
            "id": 78,
            "name": "Country",
            "type": "standard"
        },
        {
            "id": 200426,
            "name": "Device",
            "type": "standard"
        },
        {
            "id": 2932,
            "name": "Device Type",
            "type": "standard"
        },
        {
            "id": 84,
            "name": "Error Code",
            "type": "standard"
        },
        {
            "id": 82,
            "name": "Format",
            "type": "standard"
        },
        {
            "id": 976,
            "name": "Future Use #2",
            "type": "standard"
        },
        {
            "id": 977,
            "name": "Future Use #3",
            "type": "standard"
        },
        {
            "id": 978,
            "name": "Future Use #4",
            "type": "standard"
        },
        {
            "id": 979,
            "name": "Future Use #5",
            "type": "standard"
        },
        {
            "id": 200425,
            "name": "Live VoD 24x7",
            "type": "standard"
        },
        {
            "id": 88,
            "name": "Network",
            "type": "standard"
        },
        {
            "id": 95,
            "name": "Notification ID",
            "type": "standard"
        },
        {
            "id": 2933,
            "name": "OS",
            "type": "standard"
        },
        {
            "id": 91,
            "name": "Player ID",
            "type": "standard"
        },
        {
            "id": 79,
            "name": "Region",
            "type": "standard"
        },
        {
            "id": 86,
            "name": "Service Provider",
            "type": "standard"
        },
        {
            "id": 99,
            "name": "Start Up Time Range",
            "type": "standard"
        },
        {
            "id": 87,
            "name": "Stream Name",
            "type": "standard"
        },
        {
            "id": 83,
            "name": "Time",
            "type": "standard"
        },
        {
            "id": 100,
            "name": "Title",
            "type": "standard"
        },
        {
            "id": 94,
            "name": "Title/Event Name",
            "type": "standard"
        }
    ],
    "metrics": [
        {
            "id": 2118,
            "name": "% Mid Play Errors"
        },
        {
            "id": 656,
            "name": "% Rebuffering Plays"
        },
        {
            "id": 598,
            "name": "% Rebuffering Plays(Avg)"
        },
        {
            "id": 125,
            "name": "Aggregate Play Duration"
        },
        {
            "id": 350,
            "name": "Alert Metrics"
        },
        {
            "id": 149,
            "name": "Attempts"
        },
        {
            "id": 148,
            "name": "Audience Size"
        },
        {
            "id": 129,
            "name": "Availability"
        },
        {
            "id": 131,
            "name": "Bandwidth"
        },
        {
            "id": 140,
            "name": "Bitrate"
        },
        {
            "id": 147,
            "name": "Buffer Time"
        },
        {
            "id": 146,
            "name": "Connect Time"
        },
        {
            "id": 349,
            "name": "Diagnostic"
        },
        {
            "id": 136,
            "name": "Downshifts"
        },
        {
            "id": 144,
            "name": "Dropped Frames"
        },
        {
            "id": 128,
            "name": "Errors"
        },
        {
            "id": 714,
            "name": "First Rebuffers"
        },
        {
            "id": 132,
            "name": "Frames per Second"
        },
        {
            "id": 121,
            "name": "HD Play Duration"
        },
        {
            "id": 122,
            "name": "HQ Play Duration"
        },
        {
            "id": 126,
            "name": "Play Duration per Play"
        },
        {
            "id": 127,
            "name": "Plays Ended"
        },
        {
            "id": 138,
            "name": "Plays Started"
        },
        {
            "id": 137,
            "name": "Plays with Rebuffers"
        },
        {
            "id": 2117,
            "name": "Rebuffer Abandons"
        },
        {
            "id": 150,
            "name": "Rebuffer Time per Minute"
        },
        {
            "id": 130,
            "name": "Rebuffer Time per Play"
        },
        {
            "id": 134,
            "name": "Rebuffers per Play"
        },
        {
            "id": 123,
            "name": "SD Play Duration"
        },
        {
            "id": 145,
            "name": "Start Up Errors"
        },
        {
            "id": 133,
            "name": "Start Up Time"
        },
        {
            "id": 135,
            "name": "Upshifts"
        }
    ],
    "dataStores": [
        {
            "id": 132,
            "name": "Console Cube",
            "type": "standard",
            "description": "Provides standard metrics and dimensions at a granularity of one minute."
        },
        {
            "id": 186,
            "name": "Notification Cube",
            "type": "standard",
            "description": "Provides metrics and dimensions for use in obtaining details on triggered notifications."
        },
        {
            "id": 139,
            "name": "Time Cube",
            "type": "standard",
            "description": "Provides standard metrics for a time period at a granularity of one minute."
        }
    ],
    "timezone": "Asia/Calcutta"
}

List QoS Monitor data stores

Retrieves all the data stores available for QoS Monitor.

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

Sample: /media-analytics/v2/qos-monitor/report-packs/26273/data-stores

Parameter Type Sample Description
URL parameters
reportPackId Number 26273 Unique identifier for each report pack.

Status 200 application/json

Response Body:

[
    {
        "id": 132,
        "name": "Console Cube",
        "type": "standard",
        "description": "Provides standard metrics and dimensions at a one-minute granularity.",
        "dimensions": [
            {
                "id": 77,
                "name": "Continent",
                "description": "Viewer location. Available granularities are continent, region, country, and city.",
                "type": "standard"
            },
            {
                "id": 78,
                "name": "Country",
                "description": "Country from which viewer requested media.",
                "type": "standard"
            },
            {
                "id": 975,
                "name": "Future Use #1",
                "description": "reserved_L3_1"
            },
            {
                "id": 79,
                "name": "Region",
                "description": "Region from which viewer requested media.",
                "type": "standard"
            },
            {
                "id": 976,
                "name": "Future Use #2",
                "description": "reserved_L3_2",
                "type": "standard"
            },
            {
                "id": 81,
                "name": "Connection Speed",
                "description": "Internet connection speed of the visitor. Represented as low, mid, high, and very high.",
                "type": "standard"
            },
            {
                "id": 977,
                "name": "Future Use #3",
                "description": "reserved_L3_3",
                "type": "standard"
            },
            {
                "id": 82,
                "name": "Format",
                "description": "Format in which media is encoded. For example, WMS, Flash, Real, or Progressive Downloads.",
                "type": "standard"
            },
            {
                "id": 978,
                "name": "Future Use #4",
                "description": "reserved_L3_4",
                "type": "standard"
            },
            {
                "id": 979,
                "name": "Future Use #5",
                "description": "reserved_L3_5",
                "type": "standard"
            },
            {
                "id": 83,
                "name": "Time",
                "description": "Time as per time zone specified in the report.",
                "type": "standard"
            },
            {
                "id": 84,
                "name": "Error Code",
                "description": "Code representing the encountered error.",
                "type": "standard"
            },
            {
                "id": 86,
                "name": "Service Provider",
                "description": "The CDN or delivery service provider used to stream the content.",
                "type": "standard"
            },
            {
                "id": 87,
                "name": "Stream Name",
                "description": "Set automatically. Indicates the stream URL.",
                "type": "standard"
            },
            {
                "id": 90,
                "name": "Category",
                "description": "Category of the content. For example: channel name, genre, or content type (movies, tv shows, sports events, or other events).",
                "type": "standard"
            },
            {
                "id": 91,
                "name": "Player ID",
                "description": "Name and version of player on which the media was played.",
                "type": "standard"
            },
            {
                "id": 94,
                "name": "Title/Event Name",
                "description": "Name of the title/event.",
                "type": "standard"
            },
            {
                "id": 99,
                "name": "Start Up Time Range",
                "description": "The range of the sum of 'Connect Time' and 'Initial Buffer Time' experienced during a visit.",
                "type": "standard"
            },
            {
                "id": 933,
                "name": "City",
                "description": "City from which viewer requested media.",
                "type": "standard"
            },
            {
                "id": 934,
                "name": "AS Name",
                "description": "Name associated with the autonomous system of the internet service provider.",
                "type": "standard"
            },
            {
                "id": 200426,
                "name": "Device",
                "description": "Device on which the media was played.",
                "type": "standard"
            },
            {
                "id": 200425,
                "name": "Live VoD 24x7",
                "description": "Indicates live, on-demand, or 24x7 content.",
                "type": "standard"
            },
            {
                "id": 2932,
                "name": "Device Type",
                "description": "Type of device on which the media was played. For example, mobile phone, tablet, or desktop.",
                "type": "standard"
            },
            {
                "id": 2933,
                "name": "OS",
                "description": "Operating system of the device on which the media was played.",
                "type": "standard"
            },
            {
                "id": 2934,
                "name": "Browser",
                "description": "Browser on which the media was played.",
                "type": "standard"
            }
        ],
        "metrics": [
            {
                "id": 128,
                "name": "Errors",
                "type": "count",
                "description": "The total count of all errors"
            },
            {
                "id": 129,
                "name": "Availability",
                "unit": "%",
                "type": "percent",
                "description": "Average availability of media during user attempts to access it (excludes user abandons)."
            },
            {
                "id": 130,
                "name": "Rebuffer Time per Play",
                "unit": "secs",
                "type": "time",
                "description": "The average time spent on rebuffering during each play."
            },
            {
                "id": 131,
                "name": "Bandwidth",
                "unit": "bps",
                "type": "bandwidth",
                "description": "The average bandwidth experienced by users viewing streams. The byte rate at which player buffer fills is sampled at regular intervals (~500m). The sum average of all such samples is represented as the average bandwidth (bps)."
            },
            {
                "id": 132,
                "name": "Frames per Second",
                "type": "count",
                "description": "The average number of frames rendered per second per session during playback. The frames per second values are sampled at regular intervals during playback (~500ms)"
            },
            {
                "id": 2117,
                "name": "Rebuffer Abandons",
                "type": "count",
                "description": "Sum of Plays that were abandoned during a rebuffering event"
            },
            {
                "id": 133,
                "name": "Start Up Time",
                "unit": "secs",
                "type": "time",
                "description": "The average startup time per session"
            },
            {
                "id": 2118,
                "name": "% Mid Play Errors",
                "unit": "%",
                "type": "percent",
                "description": "The percentage of errors experienced during the middle of play after successful play start."
            },
            {
                "id": 134,
                "name": "Rebuffers per Play",
                "type": "count",
                "description": "The average number of rebuffers experienced per play"
            },
            {
                "id": 135,
                "name": "Upshifts",
                "type": "count",
                "description": "The average number of times users experienced a bitrate upshift per session"
            },
            {
                "id": 136,
                "name": "Downshifts",
                "type": "count",
                "description": "The average number of times users experienced a bitrate downshift per session"
            },
            {
                "id": 137,
                "name": "Plays with Rebuffers",
                "type": "count",
                "description": "Sum of Plays with at least one rebuffering event"
            },
            {
                "id": 714,
                "name": "First Rebuffers",
                "type": "count",
                "description": "First Rebuffers"
            },
            {
                "id": 138,
                "name": "Plays Started",
                "type": "count",
                "description": "Attempts to playback content that result in successful playback."
            },
            {
                "id": 140,
                "name": "Bitrate",
                "unit": "Kbps",
                "type": "bandwidth",
                "description": "The average bitrate at which stream is being played back (kbps). Samples for calculation are taken at regular time intervals during playback (~500ms)"
            },
            {
                "id": 656,
                "name": "% Rebuffering Plays",
                "unit": "%",
                "type": "percent",
                "description": "Weighted average of the proportion of rebuffering sessions calculated at 1 minute, expressed as a percentage. You can plot this metric with content, ad, and geo dimensions to understand when rebuffering occurs most and the size of audience it affects"
            },
            {
                "id": 144,
                "name": "Dropped Frames",
                "type": "count",
                "description": "The average number of frames dropped per session during playback"
            },
            {
                "id": 145,
                "name": "Start Up Errors",
                "type": "count",
                "description": "The number of startup errors"
            },
            {
                "id": 146,
                "name": "Connect Time",
                "unit": "secs",
                "type": "time",
                "description": "The average time spent over initial connection to the server per session (secs)"
            },
            {
                "id": 147,
                "name": "Buffer Time",
                "unit": "secs",
                "type": "time",
                "description": "The average time spent over initial buffering before the play starts per session (secs)"
            },
            {
                "id": 148,
                "name": "Audience Size",
                "type": "count",
                "description": "Sum of concurrent streams or plays at a particular point in time. Not an aggregated value like Attempts or Plays. When used in any chart other than time chart, Audience Size shows the value at the end of chosen duration"
            },
            {
                "id": 149,
                "name": "Attempts",
                "type": "count",
                "description": "The total number of attempts made to play streams."
            },
            {
                "id": 598,
                "name": "% Rebuffering Plays(Avg)",
                "unit": "%",
                "type": "percent",
                "description": "The percentage of sessions experiencing rebuffers; calculated as the ratio of number of sessions rebuffering atleast once to the total number of active sessions expressed as a percentage"
            },
            {
                "id": 150,
                "name": "Rebuffer Time per Minute",
                "unit": "secs",
                "type": "time",
                "description": "Average amount of time spent rebuffering per minute of playback."
            },
            {
                "id": 121,
                "name": "HD Play Duration",
                "unit": "hours",
                "type": "time",
                "description": "The time over which the stream played in HD quality (>=2.5mpbs, in hours)"
            },
            {
                "id": 122,
                "name": "HQ Play Duration",
                "unit": "hours",
                "type": "time",
                "description": "The time over which the stream played in HQ quality (>=1.5 mpbs and <2.5mbps, in hours)"
            },
            {
                "id": 123,
                "name": "SD Play Duration",
                "unit": "hours",
                "type": "time",
                "description": "The time over which the stream played in SD quality (<1.5 mpbs, in hours)"
            },
            {
                "id": 125,
                "name": "Aggregate Play Duration",
                "unit": "hours",
                "type": "time",
                "description": "The total number of hours that users played streams."
            },
            {
                "id": 126,
                "name": "Play Duration per Play",
                "unit": "mins",
                "type": "time",
                "description": "Play Duration divided by (Sum of) Plays."
            },
            {
                "id": 127,
                "name": "Plays Ended",
                "type": "count",
                "description": "Plays ended include both completed and abandoned plays. Plot this metric with dimensions such as Rebuffer time per Minute, Rebuffers per Minute, etc. Rebuffering metrics and dimensions are calculated at the end of plays and if plotted with metrics like Plays, they show incorrect charts."
            }
        ],
        "aggregationInSeconds": 60,
        "purgeIntervalInDays": 2,
        "maxQueryDurationInMinutes": 120
    },
    {
        "id": 186,
        "name": "Notification Cube",
        "type": "standard",
        "description": "Provides metrics and dimensions for use in obtaining details on triggered notifications.",
        "dimensions": [
            {
                "id": 99,
                "name": "Start Up Time Range",
                "description": "The range of the sum of 'Connect Time' and 'Initial Buffer Time' experienced during a visit.",
                "type": "standard"
            },
            {
                "id": 100,
                "name": "Title",
                "description": "Name of the title/event.",
                "type": "standard"
            },
            {
                "id": 933,
                "name": "City",
                "description": "City from which viewer requested media.",
                "type": "standard"
            },
            {
                "id": 934,
                "name": "AS Name",
                "description": "Name associated with the ASN of the ISP.",
                "type": "standard"
            },
            {
                "id": 77,
                "name": "Continent",
                "description": "Viewer location. Available granularities are Continent, Region, Country & City",
                "type": "standard"
            },
            {
                "id": 78,
                "name": "Country",
                "description": "Country from which viewer requested media",
                "type": "standard"
            },
            {
                "id": 79,
                "name": "Region",
                "description": "Region from which viewer requested media",
                "type": "standard"
            },
            {
                "id": 80,
                "name": "City",
                "description": "City from which viewer requested media",
                "type": "standard"
            },
            {
                "id": 81,
                "name": "Connection Speed",
                "description": "Internet connection speed of the visitor. Represented as Low, Mid, High & Very High.     ",
                "type": "standard"
            },
            {
                "id": 82,
                "name": "Format",
                "description": "Format in which media is encoded. For example, WMS, Flash, Real or Progressive Downloads",
                "type": "standard"
            },
            {
                "id": 83,
                "name": "Time",
                "description": "Time as per time zone specified in the report   ",
                "type": "standard"
            },
            {
                "id": 84,
                "name": "Error Code",
                "description": "Code representing the encountered error ",
                "type": "standard"
            },
            {
                "id": 86,
                "name": "Service Provider",
                "description": "The CDN or delivery Service Provider used to stream the content.",
                "type": "standard"
            },
            {
                "id": 87,
                "name": "Stream Name",
                "description": "Set automatically and indicates the Stream URL.",
                "type": "standard"
            },
            {
                "id": 88,
                "name": "Network",
                "description": "The customer's service provider.",
                "type": "standard"
            },
            {
                "id": 90,
                "name": "Category",
                "description": "Category of the content. For example: channel name, genre, content type (movies, tv shows, sports events, or other events).",
                "type": "standard"
            },
            {
                "id": 91,
                "name": "Player ID",
                "description": "Name and version of player on which the media was played.",
                "type": "standard"
            },
            {
                "id": 94,
                "name": "Title/Event Name",
                "description": "Name of the title/event",
                "type": "standard"
            },
            {
                "id": 95,
                "name": "Notification ID",
                "description": "ID of the notification.",
                "type": "standard"
            }
        ],
        "metrics": [
            {
                "id": 349,
                "name": "Diagnostic",
                "description": "Diagnostics"
            },
            {
                "id": 350,
                "name": "Alert Metrics",
                "description": "Metric values leading to a QoS notification. These help identify how the metrics relate to the thresholds set in notification rules."
            }
        ],
        "aggregationInSeconds": 60,
        "purgeIntervalInDays": 403,
        "maxQueryDurationInMinutes": 1440
    },
    {
        "id": 139,
        "name": "Time Cube",
        "type": "standard",
        "description": "Provides standard metrics for a time period at a granularity of one minute.",
        "dimensions": [
            {
                "id": 83,
                "name": "Time",
                "description": "Time as per time zone specified in the report   ",
                "type": "standard"
            }
        ],
        "metrics": [
            {
                "id": 128,
                "name": "Errors",
                "type": "count",
                "description": "The total count of all errors"
            },
            {
                "id": 129,
                "name": "Availability",
                "unit": "%",
                "type": "percent",
                "description": "Average availability across all attempts (excluding user abandons). Calculated as the number of plays divided by plays+ startup errors."
            },
            {
                "id": 130,
                "name": "Rebuffer Time per Play",
                "unit": "secs",
                "type": "time",
                "description": "The average time spent on rebuffering during each play."
            },
            {
                "id": 131,
                "name": "Bandwidth",
                "unit": "bps",
                "type": "bandwidth",
                "description": "The average bandwidth experienced by users viewing the stream. The bitrate at which player buffer fills is sampled at intervals of 500 milliseconds. The sum average of these samples is represented as the average bandwidth."
            },
            {
                "id": 132,
                "name": "Frames per Second",
                "type": "count",
                "description": "Number of frames rendered during each session of a playback. Frames per second values are sampled at intervals of 500 milliseconds during playback and their sum average is represented as the average frames per second."
            },
            {
                "id": 2117,
                "name": "Rebuffer Abandons",
                "type": "count",
                "description": "Sum of plays abandoned during a rebuffering event."
            },
            {
                "id": 133,
                "name": "Start Up Time",
                "unit": "secs",
                "type": "time",
                "description": "The average startup time per session."
            },
            {
                "id": 2118,
                "name": "% Mid Play Errors",
                "unit": "%",
                "type": "percent",
                "description": "The percentage of errors experienced during the middle of play after a successful play start."
            },
            {
                "id": 134,
                "name": "Rebuffers per Play",
                "type": "count",
                "description": "The average number of rebuffers experienced during a play."
            },
            {
                "id": 135,
                "name": "Upshifts",
                "type": "count",
                "description": "The average number of times users experienced a bit rate upshift during a session."
            },
            {
                "id": 136,
                "name": "Downshifts",
                "type": "count",
                "description": "The average number of times users experienced a bit rate downshift during a session."
            },
            {
                "id": 137,
                "name": "Plays with Rebuffers",
                "type": "count",
                "description": "Sum of plays with at least one rebuffering event."
            },
            {
                "id": 714,
                "name": "First Rebuffers",
                "type": "count",
                "description": "Number of first rebuffers encountered."
            },
            {
                "id": 138,
                "name": "Plays Started",
                "type": "count",
                "description": "Attempts to playback content that result in successful playback."
            },
            {
                "id": 140,
                "name": "Bitrate",
                "unit": "Kbps",
                "type": "bandwidth",
                "description": "The average bit rate at which stream is played back."
            },
            {
                "id": 656,
                "name": "% Rebuffering Plays",
                "unit": "%",
                "type": "percent",
                "description": "Weighted average of rebuffering sessions calculated at a one-minute aggregation. You can plot this metric with content, ad, and geo dimensions to understand when rebuffering occurs most and the size of the audience it affects."
            },
            {
                "id": 144,
                "name": "Dropped Frames",
                "type": "count",
                "description": "The average number of frames dropped per session during playback."
            },
            {
                "id": 145,
                "name": "Start Up Errors",
                "type": "count",
                "description": "The number of startup errors."
            },
            {
                "id": 146,
                "name": "Connect Time",
                "unit": "secs",
                "type": "time",
                "description": "The average time spent over initial connection to the server."
            },
            {
                "id": 147,
                "name": "Buffer Time",
                "unit": "secs",
                "type": "time",
                "description": "The average time per session spent over initial buffering before the start of play."
            },
            {
                "id": 148,
                "name": "Audience Size",
                "type": "count",
                "description": "Sum of concurrent streams or plays at a specific time. It can be used in all charts, except time, to show audience size for a chosen duration."
            },
            {
                "id": 149,
                "name": "Attempts",
                "type": "count",
                "description": "The total number of attempts to play a stream."
            },
            {
                "id": 598,
                "name": "% Rebuffering Plays(Avg)",
                "unit": "%",
                "type": "percent",
                "description": "The percentage of sessions experiencing rebuffers. It is calculated as the ratio of number of sessions rebuffering atleast once to the total number of active sessions."
            },
            {
                "id": 150,
                "name": "Rebuffer Time per Minute",
                "unit": "secs",
                "type": "time",
                "description": "Average amount of time spent rebuffering every minute of playback."
            },
            {
                "id": 121,
                "name": "HD Play Duration",
                "unit": "hours",
                "type": "time",
                "description": "The time during which the stream played in HD quality (>=2.5mpbs)."
            },
            {
                "id": 122,
                "name": "HQ Play Duration",
                "unit": "hours",
                "type": "time",
                "description": "The time during which the stream played in HQ quality (>=1.5 mpbs and <2.5mbps)."
            },
            {
                "id": 123,
                "name": "SD Play Duration",
                "unit": "hours",
                "type": "time",
                "description": "The time during which the stream played in SD quality (<1.5 mpbs)."
            },
            {
                "id": 125,
                "name": "Aggregate Play Duration",
                "unit": "hours",
                "type": "time",
                "description": "The total number of hours that users played streams."
            },
            {
                "id": 126,
                "name": "Play Duration per Play",
                "unit": "mins",
                "type": "time",
                "description": "Play duration divided by sum of plays."
            },
            {
                "id": 127,
                "name": "Plays Ended",
                "type": "count",
                "description": "Plays ended include both completed and abandoned plays. You can plot this metric with the `Rebuffer Time per Minute`, `Rebuffers per Minute` dimensions."
            }
        ],
        "aggregationInSeconds": 60,
        "purgeIntervalInDays": 2,
        "maxQueryDurationInMinutes": 1440
    }
]

Get a QoS Monitor data store

Retrieves dimensions, metrics, aggregation interval, purge interval, maximum allowed query interval, and other data store details.

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

Sample: /media-analytics/v2/qos-monitor/report-packs/26273/data-stores/307

Parameter Type Sample Description
URL parameters
reportPackId Number 26273 Unique identifier for each report pack.
dataStoreId Number 307 The ID of the data store.

Status 200 application/json

Response Body:

{
    "id": 132,
    "name": "Console Cube",
    "type": "standard",
    "description": "Provides standard metrics and dimensions at a one-minute granularity.",
    "dimensions": [
        {
            "id": 77,
            "name": "Continent",
            "description": "Viewer location. Available granularities are continent, region, country, and city.",
            "type": "standard"
        },
        {
            "id": 78,
            "name": "Country",
            "description": "Country from which viewer requested media.",
            "type": "standard"
        },
        {
            "id": 975,
            "name": "appversion",
            "description": "reserved_L3_1"
        },
        {
            "id": 79,
            "name": "Region",
            "description": "Region from which viewer requested media.",
            "type": "standard"
        },
        {
            "id": 976,
            "name": "Future Use #2",
            "description": "reserved_L3_2",
            "type": "standard"
        },
        {
            "id": 81,
            "name": "Connection Speed",
            "description": "Internet connection speed of the visitor. Represented as low, mid, high, and very high.",
            "type": "standard"
        },
        {
            "id": 977,
            "name": "Future Use #3",
            "description": "reserved_L3_3",
            "type": "standard"
        },
        {
            "id": 82,
            "name": "Format",
            "description": "Format in which media is encoded. For example, WMS, Flash, Real, or Progressive Downloads",
            "type": "standard"
        },
        {
            "id": 978,
            "name": "Future Use #4",
            "description": "reserved_L3_4",
            "type": "standard"
        },
        {
            "id": 979,
            "name": "Future Use #5",
            "description": "reserved_L3_5",
            "type": "standard"
        },
        {
            "id": 83,
            "name": "Time",
            "description": "Time as per time zone specified in the report.",
            "type": "standard"
        },
        {
            "id": 84,
            "name": "Error Code",
            "description": "Code representing the encountered error.",
            "type": "standard"
        },
        {
            "id": 86,
            "name": "Service Provider",
            "description": "The CDN or delivery service provider used to stream the content.",
            "type": "standard"
        },
        {
            "id": 87,
            "name": "Stream Name",
            "description": "Set automatically. Indicates the stream URL.",
            "type": "standard"
        },
        {
            "id": 90,
            "name": "Category",
            "description": "Category of the content. For example: channel name, genre, or content type (movies, tv shows, sports events, or other events).",
            "type": "standard"
        },
        {
            "id": 91,
            "name": "Player ID",
            "description": "Name and version of player on which the media was played.",
            "type": "standard"
        },
        {
            "id": 94,
            "name": "Title/Event Name",
            "description": "Name of the title/event",
            "type": "standard"
        },
        {
            "id": 99,
            "name": "Start Up Time Range",
            "description": "The range of the sum of 'Connect Time' and 'Initial Buffer Time' experienced during a visit.",
            "type": "standard"
        },
        {
            "id": 933,
            "name": "City",
            "description": "City from which viewer requested media.",
            "type": "standard"
        },
        {
            "id": 934,
            "name": "AS Name",
            "description": "Name associated with the autonomous system of the internet service provider.",
            "type": "standard"
        },
        {
            "id": 200426,
            "name": "Device",
            "description": "Device on which the media was played.",
            "type": "standard"
        },
        {
            "id": 200425,
            "name": "Live VoD 24x7",
            "description": "Indicates live, on-demand, or 24x7 content.",
            "type": "standard"
        },
        {
            "id": 2932,
            "name": "Device Type",
            "description": "Type of device on which the media was played. For example, mobile phone, tablet, or desktop.",
            "type": "standard"
        },
        {
            "id": 2933,
            "name": "OS",
            "description": "Operating system of the device on which the media was played.",
            "type": "standard"
        },
        {
            "id": 2934,
            "name": "Browser",
            "description": "Browser on which the media was played.",
            "type": "standard"
        }
    ],
    "metrics": [
        {
            "id": 128,
            "name": "Errors",
            "type": "count",
            "description": "The total count of all errors."
        },
        {
            "id": 129,
            "name": "Availability",
            "unit": "%",
            "type": "percent",
            "description": "Average availability of media during user attempts to access it (excludes user abandons)."
        },
        {
            "id": 130,
            "name": "Rebuffer Time per Play",
            "unit": "secs",
            "type": "time",
            "description": "The average time spent on rebuffering during each play."
        },
        {
            "id": 131,
            "name": "Bandwidth",
            "unit": "bps",
            "type": "bandwidth",
            "description": "The average bandwidth experienced by users viewing the stream. The bitrate at which player buffer fills is sampled at regular intervals of 500 milliseconds. The sum average of these samples is represented as the average bandwidth."
        },
        {
            "id": 132,
            "name": "Frames per Second",
            "type": "count",
            "description": "Number of frames rendered during each session of a playback. Frames per second values are sampled at intervals of 500 milliseconds during playback and their sum average is represented as the average frames per second."
        },
        {
            "id": 2117,
            "name": "Rebuffer Abandons",
            "type": "count",
            "description": "Sum of plays abandoned during a rebuffering event"
        },
        {
            "id": 133,
            "name": "Start Up Time",
            "unit": "secs",
            "type": "time",
            "description": "The average startup time per session"
        },
        {
            "id": 2118,
            "name": "% Mid Play Errors",
            "unit": "%",
            "type": "percent",
            "description": "The percentage of errors experienced during the middle of play after a successful start."
        },
        {
            "id": 134,
            "name": "Rebuffers per Play",
            "type": "count",
            "description": "The average number of rebuffers experienced during a play."
        },
        {
            "id": 135,
            "name": "Upshifts",
            "type": "count",
            "description": "The average number of times users experienced a bitrate upshift during a session."
        },
        {
            "id": 136,
            "name": "Downshifts",
            "type": "count",
            "description": "The average number of times users experienced a bitrate downshift during a session."
        },
        {
            "id": 137,
            "name": "Plays with Rebuffers",
            "type": "count",
            "description": "Sum of plays with at least one rebuffering event."
        },
        {
            "id": 714,
            "name": "First Rebuffers",
            "type": "count",
            "description": "Number of first rebuffers encountered."
        },
        {
            "id": 138,
            "name": "Plays Started",
            "type": "count",
            "description": "Attempts to playback content that result in successful playback."
        },
        {
            "id": 140,
            "name": "Bitrate",
            "unit": "Kbps",
            "type": "bandwidth",
            "description": "The average bit rate at which stream is played back."
        },
        {
            "id": 656,
            "name": "% Rebuffering Plays",
            "unit": "%",
            "type": "percent",
            "description": "Weighted average of rebuffering sessions calculated at a one-minute aggregation. You can plot this metric with content, ad, and geo dimensions to understand when rebuffering occurs most and the size of the audience it affects."
        },
        {
            "id": 144,
            "name": "Dropped Frames",
            "type": "count",
            "description": "The average number of frames dropped per session during playback."
        },
        {
            "id": 145,
            "name": "Start Up Errors",
            "type": "count",
            "description": "The number of startup errors."
        },
        {
            "id": 146,
            "name": "Connect Time",
            "unit": "secs",
            "type": "time",
            "description": "The average time spent over initial connection to the server."
        },
        {
            "id": 147,
            "name": "Buffer Time",
            "unit": "secs",
            "type": "time",
            "description": "The average time per session spent over initial buffering before the start of play."
        },
        {
            "id": 148,
            "name": "Audience Size",
            "type": "count",
            "description": "Sum of concurrent streams or plays at a specific time. It can be used in all charts, except time, to show audience size for a chosen duration."
        },
        {
            "id": 149,
            "name": "Attempts",
            "type": "count",
            "description": "The total number of attempts to play a stream."
        },
        {
            "id": 598,
            "name": "% Rebuffering Plays(Avg)",
            "unit": "%",
            "type": "percent",
            "description": "The percentage of sessions experiencing rebuffers. It is calculated as the ratio of number of sessions rebuffering atleast once to the total number of active sessions."
        },
        {
            "id": 150,
            "name": "Rebuffer Time per Minute",
            "unit": "secs",
            "type": "time",
            "description": "Average amount of time spent rebuffering every minute of playback."
        },
        {
            "id": 121,
            "name": "HD Play Duration",
            "unit": "hours",
            "type": "time",
            "description": "The time during which the stream played in HD quality (>=2.5mpbs)."
        },
        {
            "id": 122,
            "name": "HQ Play Duration",
            "unit": "hours",
            "type": "time",
            "description": "The time during which the stream played in HQ quality (>=1.5 mpbs and <2.5mbps)."
        },
        {
            "id": 123,
            "name": "SD Play Duration",
            "unit": "hours",
            "type": "time",
            "description": "The time during which the stream played in SD quality (<1.5 mpbs)."
        },
        {
            "id": 125,
            "name": "Aggregate Play Duration",
            "unit": "hours",
            "type": "time",
            "description": "The total number of hours that users played streams."
        },
        {
            "id": 126,
            "name": "Play Duration per Play",
            "unit": "mins",
            "type": "time",
            "description": "Play duration divided by sum of plays."
        },
        {
            "id": 127,
            "name": "Plays Ended",
            "type": "count",
            "description": "`Plays Ended` includes both completed and abandoned plays. You can plot this metric with the `Rebuffer Time per Minute`, `Rebuffers per Minute` dimensions."
        }
    ],
    "aggregationInSeconds": 60,
    "purgeIntervalInDays": 2,
    "maxQueryDurationInMinutes": 120
}

List QoS Monitor data sources

Retrieves the data sources available for QoS Monitor.

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

Sample: /media-analytics/v2/qos-monitor/report-packs/26273/data-sources

Parameter Type Sample Description
URL parameters
reportPackId Number 26273 Unique identifier for each report pack.

Status 200 application/json

Response Body:

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

Get QoS Monitor report data

Retrieves data for a specific report for the given query parameter. 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/v2/qos-monitor/report-packs/{reportPackId}/data{?dimensions,metrics,startDate,endDate,limit,offset,aggregation,filterParams,sortParams}

Sample: /media-analytics/v2/qos-monitor/report-packs/26273/data?dimensions=83%2C96%2C57&metrics=546%2C544%2C3&startDate=2014-03-22T15%3A30Z&endDate=2014-03-23T15%3A30Z&limit=300&offset=0&aggregation=month&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

Parameter Type Sample Description
URL parameters
reportPackId Number 26273 Unique identifier for each report pack.
Required query parameters
dimensions String 83,96,57 Identifies dimensions with comma-separated IDs.
endDate String 2014-03-23T15:30Z The timestamp string in ISO 8601 format yyyy-MM-ddTHH:mmZ or yyyy-MM-ddTHH:mm+HH:mm.
metrics String 546,544,3 Identifies metrics with comma-separated IDs.
startDate String 2014-03-22T15:30Z The timestamp string in ISO 8601 format yyyy-MM-ddTHH:mmZ or yyyy-MM-ddTHH:mm+HH:mm.
Optional query parameters
aggregation String month The time period you want to group each data record. You can include a numeric value to serve as a total number of seconds, or a key word value to denote day, week, month, or year. (For example 30 for 30 seconds or day for one day).
filterParams String [{"type":"dimension","values":["GB"],"id":4,"condition":"in"},{"type":"metric","values":[16],"id":155,"condition":"gt"}] A UTF–8 URL-encoded JSON object representing filter parameters that limit reported data. See the FilterParams object for details on its structure.
limit Number 300 The number of rows to return, from 1 to 10000. The default value is 300.
offset Number 0 The offset of the row from which reported data must start, used to request progressive batches of data. For example, you can make 10 requests for 1000 records by setting the overall limit to 100, then setting the offset to 0, 100, 200, and so on for each request.
sortParams String [{"type":"metric","order":"asc","id":40}] A UTF–8 URL-encoded JSON object representing sort parameters that rearrange reported data. See the SortParams object for details on its structure. If unspecified, the response sorts either on time for time-based queries, or on the first metric.

Status 200 application/json

Response Body:

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

Data

This section describes Media Analytics API’s various data structures.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.

DataSource

A data source is a collection of raw log data consisting of detailed information for each end-user access attempt made to your digital property.

Download schema: data-source.json

Sample GET:

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

DataSource members

Member Type Required Description
configPath String Represents the beacon configuration path. Available with the beaconID data source type.
dsType Enumeration Type of data source, either Client side or Server side. Client side data source is a beaconID which is a HTTP GET request sent by the player plugin to a pre-configured Akamai domain. Server side data source is a cpcode which is a unique identifier assigned to a customer. TBD: enum values missing from description: beaconId.
id Integer Unique identifier for each data source.
name String Name of the data source.
type String Associated pipeline of data source.
values Array List of values that form the data source.

DataStore

A data store is a collection of dimensions and metrics stored in a data base.

Download schema: data-store.json

Sample GET:

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

DataStore members

Member Type Required Description
aggregation Integer Number of seconds for which data is aggregated.
description String Text describing the data store.
dimensions DataStore.dimensions[] Encapsulates dimensions for the data store. A dimension acts like a key in data exploration. It answers questions such as who, what, where, and which. Each dimension object provides information on the ID, name, type and description of the dimension.
id Integer Unique identifier for each data store.
maxQueryDurationInMinutes Integer Maximum number of minutes for which a user can query a data store. It is a system-imposed limit for better performance.
metrics DataStore.metrics[] Encapsulates 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.
name String The name of the data store.
purgeIntervalInDays Integer Number of days for which the data store keeps data.
type Enumeration The type of data store, either standard or custom.
DataStore.dimensions[]: Encapsulates dimensions for the data store. A dimension acts like a key in data exploration. It answers questions such as who, what, where, and which. Each dimension object provides information on the ID, name, type and description of the dimension.
description String A description of the dimension.
id Integer A unique identifier for each dimension.
name String The name of the dimension.
type Enumeration The type of dimension, either standard or custom.
DataStore.metrics[]: Encapsulates 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.
description String A description of the dimension.
id Integer A unique identifier for each metric.
name String The name of the metric.

Report

Reports encapsulate a set of data sources, data stores, metrics, and dimensions.

Download schema: report-pack.json

Sample GET:

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

Report members

Member Type Required Description
dataSources Report.dataSources[] Encapsulates 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.
dataStores Report.dataStores[] Encapsulates 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.
dimensions Report.dimensions[] Encapsulates 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.
filters Null The filters applied on the data captured in the report pack.
id Integer Unique identifier for each report pack.
isActive Boolean The current activation status of the report pack.
metrics Report.metrics[] Encapsulates 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.
name String The name of the report pack.
subType String The type of the report pack.
timezone String Timezone in which the data is returned.
type String This is an internal member.
Report.dataSources[]: Encapsulates 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.
id Integer The unique identifier for each data source.
name String The name of the data source.
Report.dataStores[]: Encapsulates 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.
description String Text describing the data store.
id Integer Unique identifier for each data store.
name String The name of the data store.
type Enumeration The type of data store, either standard or custom.
Report.dimensions[]: Encapsulates 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.
id Integer Unique identifier for each dimension.
name String The name of the dimension.
type Enumeration The type of dimension, either standard or custom.
Report.metrics[]: Encapsulates 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.
id Integer Unique identifier for each metric.
name String The name of the metric.

FilterParams

Encapsulates filtering parameters that are wrapped in an array, URL-encoded, and passed in with GET requests using the filterParams query parameter.

Download schema: filter-params.json

Sample non-encoded parameter value, expanded:

[
    {
        "condition": "in",
        "id": 78,
        "type": "dimension",
        "values": [
            "IN"
        ]
    },
    {
        "condition": "gt",
        "id": 128,
        "type": "metric",
        "values": [
            100
        ]
    }
]

FilterParams members

Member Type Required Description
condition Enumeration The condition specifier. For dimensions: in, nin (in or not in), contains, ncontains (does or doesn’t contain), starts, nstarts (does or doesn’t start with), ends, nends (does or doesn’t end with). For metrics: eq, neq (equal or not), gt (greater than), gte (greater than or equal), lt (less than), lte (less than or equal).
id Integer Identifies each dimension or metric filtering entity.
type Enumeration Specifies whether the provided id parameter is a dimension or a metric.
values Array List of values used to filter the result. Values represent either inclusions or exclusions, depending on what the condition parameter specifies. Use the two-character country code to filter Media Analytics data by location. To get the list of country codes, go to the Luna Control Center. Download a CSV mapping from Support ⇒ User and Developer Guides ⇒ EdgeScape ⇒ Data Codes ⇒ Country Code.

SortParams

Encapsulates sorting parameters that are wrapped in an array, URL-encoded, and passed in with GET requests using the sortParams query parameter.

Download schema: sort-params.json

Sample non-encoded parameter value, expanded:

[
    {
        "id": 128,
        "order": "desc",
        "type": "metric"
    }
]

SortParams members

Member Type Required Description
id Integer The ID of the sorting entity. The sorting entity should also be part of the query parameter metrics or dimensions.
order Enumeration Either asc for ascending or desc for descending sort order.
type Enumeration Indicates if the id parameter is a dimension or a metric.

Errors

This section provides details on the format of error response objects the Media Analytics API generates. It also lists the range of HTTP response codes for both error and success cases.

Error response codes

API endpoints routinely respond with failure codes to a wide range of problems with the integrity of the data. The API returns HTTP response codes that correspond to the status element in the JSON response eliminating the need to query the header for the response code. For all non–2xx HTTPS status codes, the API responds with a JSON object such as the following:

{
    "type": "bad-request",
    "title": "Bad Request",
    "instance": "3ffab427-d870-4ec0-b049-427cf58743a1",
    "status": 400,
    "detail": "The requested dimension and metric combination is not available in any of the data stores."
}

HTTP status codes

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

Code Description
200 OK. If the report yields an empty data set, the response yields an empty set of rows.
400 Bad input parameter. The error detail should identify the cause.
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 exceeds allowable limit.

Last modified: 8/23/2018