
- Overview
- Resources
- API summary
- List audience analytics report packs
- Get a audience analytics report pack
- List audience analytics data stores
- Get a audience analytics data store
- List audience analytics data sources
- Get audience analytics report data
- List QoS monitor report packs
- Get a QoS monitor report pack
- List QoS monitor data stores
- Get a QoS monitor data store
- List QoS monitor data sources
- Get QoS monitor report data
- List viewer diagnostics report packs
- Get a viewer diagnostics report pack
- List viewer diagnostics data stores
- Get a viewer diagnostics data store
- List viewer diagnostics data sources
- Get viewer diagnostics report data
- List download analytics report packs
- Get a download analytics report pack
- List download analytics data stores
- Get a download analytics data store
- List download analytics data sources
- Get download analytics report data
- Errors
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 Luna Control Center.
Sample usage: steps to retrieve data
Step 1: retrieve report pack
A report pack is defined by a set of data stores, which are a collection of dimensions and metrics of interest, aggregated over time. For more details, refer to the User Guide. All Media 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 Akamai Luna Control Center.
Usage criterion
Media Analytics API are available for occasional on-demand fetch of data only. Automated/programmed fetches in a “Poll” fashion are not supported & such usage will be scrutinized and could be dropped.
Rate limiting
Media Analytics API endpoints are subject to a rate-limiting constraint, which is currently set at ten requests per minute. When this limit is exceeded, an HTTP 429 error (Too Many Requests) is returned. This should be considered carefully when implementing endpoints that act on single list entries in a loop.
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/ |
Get a Audience Analytics Report Pack | GET | /media-analytics/ |
List Audience Analytics Data Stores | GET | /media-analytics/ |
Get a Audience Analytics Data Store | GET | /media-analytics/ |
List Audience Analytics Data Sources | GET | /media-analytics/ |
Get Audience Analytics Report Data | GET | /media-analytics/ |
QoS Monitor | ||
List QoS Monitor Report Packs | GET | /media-analytics/ |
Get a QoS Monitor Report Pack | GET | /media-analytics/ |
List QoS Monitor Data Stores | GET | /media-analytics/ |
Get a QoS Monitor Data Store | GET | /media-analytics/ |
List QoS Monitor Data Sources | GET | /media-analytics/ |
Get QoS Monitor Report Data | GET | /media-analytics/ |
Viewer Diagnostics | ||
List Viewer Diagnostics Report Packs | GET | /media-analytics/ |
Get a Viewer Diagnostics Report Pack | GET | /media-analytics/ |
List Viewer Diagnostics Data Stores | GET | /media-analytics/ |
Get a Viewer Diagnostics Data Store | GET | /media-analytics/ |
List Viewer Diagnostics Data Sources | GET | /media-analytics/ |
Get Viewer Diagnostics Report Data | GET | /media-analytics/ |
Download Analytics | ||
List Download Analytics Report Packs | GET | /media-analytics/ |
Get a Download Analytics Report Pack | GET | /media-analytics/ |
List Download Analytics Data Stores | GET | /media-analytics/ |
Get a Download Analytics Data Store | GET | /media-analytics/ |
List Download Analytics Data Sources | GET | /media-analytics/ |
Get Download Analytics Report Data | GET | /media-analytics/ |
List audience analytics report packs
Returns name
, id
, and timezone
for all report packs created for
your account.
GET /media-analytics/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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. |
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/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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/
Example: /media-analytics/
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"
}