Conviva Metrics V3 API: Getting Started
Learn about the Metrics V3 APIs and how to use them.
Retrive historical and real-time metric data:
-
Step 1 and 2: Construct a simple API request.
-
Step 3 and 4: Interpret data in the response format.
-
Step 5, 6, and 7: Specify additional inputs, such as dimensional filtering and custom time range.
API request paths for historical and real-time metrics:
-
Historical Metrics
insights/3.0/metrics/...
Example:
GET https://api.conviva.com/insights/3.0/metrics/attempts?days=5 -
Real-Time Metrics
insights/3.0/real-time-metrics/...
Example:
GET https://api.conviva.com/insights/3.0/real-time-metrics/attempts
This topic considered historical metrics for all the API sample requests. To retrieve the corresponding real-time metrics, simply replace .../metrics/... with .../real-time-metrics/....
API Access
To access the API, please contact the account representative to get the API authentication information, including CLIENT_ID and CLIENT_SECRET. For more details, refer to API Authentication.
Note: Do not use Pulse user-based credentials for any API request.
1. Select Time-series Metric
Metrics V3 is designed to fetch time-series metric data. Conviva supports over 70+ metrics, so the first step is to decide which metric data to retrieve.
The examples on this page use Ended Plays as the selected metric.
2. GET Metric Data
All Metrics v3 API endpoints are based on HTTPS GET method. Send a GET request using the /3.0/metrics/{metric_name} URL path format to retrieve the metric data.
Use the ended-plays endpoint to retrieve time-series data of Ended Plays.
The request looks like:
GET https://api.conviva.com/insights/3.0/metrics/ended-plays?days=5Each time-series retrieval must have a time range and a granularity (for slicing the time range into multiple intervals).
However, these are optional and if not specified, the system assumes default:
-
time range: Last 1 day(24 hours)
-
granularity: PT1H (per 1-hour interval)
In this case, the request fetches data of the last 24 hours (because both time range and granularity are omitted), and divides the data into intervals of every hour.
3. Intepret time-series Response
{
// sliced interval data based on granularity
"time_series": [
// first interval
{
// label based on the interval's start time
"timestamp": {
"epoch_ms": 1663794000000,
"iso_date": "2022-09-21T21:00:00.000Z"
},
// metric data of this interval
"ended_plays": {
"count": 11830,
"per_unique_device": 0.9971704297869723
}
},
// next interval
{
"timestamp": {
"epoch_ms": 1663797600000,
"iso_date": "2022-09-21T22:00:00.000Z"
},
"ended_plays": {
"count": 9401,
"per_unique_device": 1.0222112814944153
}
},
// more intervals (truncated)
],
// aggregated metric data calculated based on the entire time range
"total": {
"ended_plays": {
"count": 141072,
"per_unique_device": 1.0290414019832144
}
}
}
The response consists of a time_series array of interval data and an optional total object.
-
Each interval item in the time_series array has a timestamp label, which is the start time of the interval.
-
The total object contains the aggregated metric data, calculated using the entire requested time range.
4. Group Data by a Dimension
Conviva data has many dimensions (a dimension is like a set of enum values). Slice metric data with finer-grained details by grouping the data by a dimension.
To group by a dimension, simply append /group-by/{dimension_name} to the URL path. For example, retrieve the Ended Plays metric per country, group by the geo-country-code dimension.
Sample Request:
GET https://api.conviva.com/insights/3.0/metrics/ended-plays/group-by/geo-country-code?days=5Sample Response (group-by):
"time_series": [
// first interval
{
// label based on the interval's start time
"timestamp": {
"epoch_ms": 1663794000000,
"iso_date": "2022-09-21T21:00:00.000Z"
},
"dimensional_data": [
// interval data grouped by a dimension value
{
// dimension labeled data
"dimension": {
"key": "geo_country_code",
"value": "us", // dimension label value
"description": "United States"
},
// metric data of the dimension of this interval
"metrics": {
"ended_plays": {
"count": 4471,
"per_unique_device": 1.0053743257340173
}
}
},
{
// another dimension labeled data
"dimension": {
"key": "geo_country_code",
"value": "in", // dimension label value
"description": "India"
},
"metrics": {
"ended_plays": {
"count": 4518,
"per_unique_device": 1.0303546447571328
}
}
},
// more dimension values
]
},
// more intervals (truncated)
],
"total": {
"ended_plays": {
"count": 141072,
"per_unique_device": 1.0290414019832144
}
}
}
The group-by response also has the attributes of time_series and total. The only difference is that each interval has a dimensional_data array that further slices the data by dimension values.
Each dimensional_data item has a dimension label object and a metrics object, which contains the fine-grained metric data (sliced by both granularity and dimension).
Conceptualize the response as a 3D-cube, where:
-
one axis is the time series.
-
another axis is the metric data values.
-
last axis is the dimension enum values.
5. Filter Metric Data by Dimensions
In addition to group-by, filter the data by dimensions.
Continuing with the above examples, to get data from Android devices and the Verizon ISP. Use filter by device_os and isp dimensions and append them as query string parameters.
Naming Conventions of Dimensions
Use dimensions for both grouping and filtering data. Conviva supports group-by using only one dimension, and filtering by multiple dimensions.
To differentiate between grouping and filtering, use different naming conventions:
-
group-by uses kebab-case names in the URL path segment (for example, /group-by/geo-country-code).
-
filtering uses snake_case names in the query string parameter keys (for example, ?device_os=Android&isp=Verizon).
Requests with Dimension Filters
Example 1:
GET https://api.conviva.com/insights/3.0/metrics/ended-plays?days=5&device_os=Android&isp=Verizon
Example 2:
GET https://api.conviva.com/insights/3.0/metrics/ended-plays/group-by/geo-country-code?days=5&device_os=Android&isp=Verizon6. Specifying Time Range and Granularity
In step 2, we mentioned that if the time range and granularity are omitted, the system will use the default values. However, to query a specify time range and/or granularity, specify them in the querystring.
There are multiple ways to specify time range:
-
by last number of days.
-
by date, epoch or epoch_ms values (in conjunction with start_/end_ prefixes).
And, granularity value must be in ISO 8601 duration format. We only support a subset of granularity options.
Note: To retrieve historical metric data, the maximum length of an input time range is 90 days within the last 13 months. For more details, refer to Time Range Options.
7. KPI-based Metrics
Finally, some of our metrics (such as, Improvement Opportunities) are calculated based on a set of thresholds known as KPI. To know how KPI thresholds work, see Overview Dashboards.
Use the GET /kpis endpoint to retrieve a list of available KPIs (kpi_id and kpi_name).
When retrieving metric data, use the kpi_id query parameter to specify the set of KPI thresholds to use for calculation.
If no KPI option is specified in a request, the system assumes Conviva Good as the default threshold set.