Analytics API

Using the API

The main way of using the api is by querying it for interesting insights. This is done by using one of two querying endpoints using a GET request.

/v1/dps/customer/{customer_name} for data corresponding to an entire customer. /v1/dps/customer/{customer_name}/business_unit/{business_unit} for data corresponding to a specific business unit.

In order to select the period to view data for the start and end query parameters are provided, these are required in order to make a request and should be provided in ISO 8601 standard. In addition to this one can also specify the following query parameters page (which sets which page to retrieve), page_size (which sets the number of items returned per page) and limit (which sets the total number of items to return for the entire dataset).

The creation of the acutal data request is done as a JSON request body consisting of the following parts:

• Datapoints, what data points that should be retrieved
• Groupings, how the data should be grouped
• Filters, how the data should be filtered
• Sort, how the data should the sorted

Of these building blocks only the required one is datapoints, the rest are optional. In addition to this a SHA1 hash of the complete request body should be provided in the query parameter body_sha1

Putting all of this together a complete request can look as follows:

/v1/dps/customer/FantasticTV/business_unit/FantasticContent/query?start=2021-12-01&end=2022-01-01&body_sha1=498850B427D5480402E1D367C1596DCA6740BFB2
{
    "datapoints": {
        "raw": [
            "playback.sessions.total/cnt"
        ]
    },
    "grouping": [
        "audience.country.name"
    ],
    "filters": {
        "audience.country.name": ["Sweden", "Finland", "Norway", "Denmark", "Iceland"]
    },
    "sort": [
        "-playback.sessions.total/cnt"
    ]
}

The above request would fetch data for the month of December and show the total number of playback sessions for each country. Finally the data returned would be sorted by number of sessions in a descending fashion.

The data returned by the request above would then look something along these lines

{
    "page_number": 1,
    "page_size": 100,
    "limit": 100,
    "results": 2,

    "datapoints": {
        "audience.country.name": [
            "Sweden",
            "Iceland"
        ],
        "playback.sessions.total/cnt": [
            1151.0,
            350.0
        ]
    },
    "grouping": [
        "audience.country.name"
    ],
    "filters": {
        "customer": [
            "FantasticTV"
        ],
        "business_unit": [
            "FantasticContent"
        ]
    },
    "sort": [
        "-playback.sessions.total/cnt"
    ],
    "error_state": {}
}

Where the interesting part would be contained in the datapoints object. Here each object can conceptually be thought of as a column in a table and by stitching the objects together you would get a row of data. So in the above example we would have something along these lines.

Country	Total Sessions
Sweden	1151
Iceland	350

results shows the total number of items in the request, this can be used as an indicator when to stop paging the data.
error_state in the returned response would indicate if there was anything problematic in the request body sent to the API.

Datapoints

At least a datapoint must be present in the request body and they must all be compatible with the chosen groupings.

A complete list of all datapoints can be found at /v1/dps or under Datapoints.

Groupings

Zero or more groupings are allowed and groupings are provided as a string in the data request body. Note that requests can only contain groupings and data points that are compatible.

A complete list of all groupings can also be found at /v1/aspects or under Groupings.

Filters

Filters are provided so that it is possible to filter the data for a certain value on a variable before grouping and aggregating the data. A request can contain several filters.

For example

"filters": {
    "viewing.meta.anonymous": ["true"],
    "audience.country.name": ["Sweden", "Finland", "Norway", "Denmark", "Iceland"]
}

This would only show data for any anonymous sessions originating from one of the Nordic countries.

Sorting

It is possible to select how the response is sorted. Any of the selected grouping or data points can be used for sorting. For descending order put “-” in front of the grouping/datapoint name. Strings are sorted in alphabetical order. Several sorts can be specified and they will be applied from left to right.

For example

"sort": ["-playback.sessions.total/cnt"]

Large requests

When trying make requests to the API that take long time (large amounts of data, big aggregations and so on), use the following polling endpoint:

/v2/dps/customer/{customer_name}/business_unit/{business_unit}/poll

This will start a background job on our servers that will fetch and aggregate the data, and cache it when finished, so users don't have to wait for the request to finish. By sending the same request again to see if the data is ready, the endpoint either returns a message saying it is still crunching the data, an error has occured or, if the data is ready, the requested data.