Analytics & data

api.video enables you to collect play event data about your videos and live streams.

You can:

• get the number of plays for a specific video for a period like the current day, current week or the last 30 days
• get the number of plays by country
• get the number of plays for specific devices, browser agents, and operating systems.

Use this data to understand your audience, or integrate the data directly into your own application to display it to your viewers.

Visit the Analytics page on the Dashboard to get started and see your data visualized!

How it works

api.video's solution uses playback data to analyze and segment your viewers.

• Play events are generated when your viewer is engaging in a video or live stream session.
• When using api.video's web player, or a custom-built player with the Video.js analytics plugin integrated, play events are generated immediately. Event updates are sent every 10 seconds, even if the user leaves the page within 10 seconds.
• When using any other player, play events are generated immediately. Event updates are only sent if the user stays on the page for at least 10 seconds.
• Video re-plays using the dedicated re-play button in the player do not generate play events.
• If a user is viewing your content via a browser, refreshes the tab, and plays the content again, a new play event is generated.
• api.video retains play event data for 30 days.

After play events are collected, there is a short delay while the API processes the data. api.video recommends that you retrieve Analytics periodically, for example once every minute. This enables you to keep track of live stream engagement or manage user-generated content without delay.

Requirements

Usage

Api.video offers 2 dedicated API endpoints for analytics:

Request

The endpoints accept GET requests. You must provide 2 required query parameters in your requests: from and dimension. You can also provide 2 optional query parameters: to, and filter.

For example:

curl --request GET \
     --url https://ws.api.video/analytics/videos/plays?dimension=country&from=2023-06-01 \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MDUyNzEuOTEyODMsIm5iZiI6MTY0MjgwNTI3MS45MTI4MywiZXhwIjoxNjQyODA4ODcxLjkxMjgzLCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.jTiB29R_sg5dqCDBU8wrnz7GRJsCzfVeLVTX-XSctS024B9OmGsuY139s2ua1HzrT63sqkBB1QshrjZbkDLVxSrs0-gt-FaM2bgvCC0lqK1HzEUL4vN2OqPPuM8R2pruj0UdGVaifGqmyfehKcHxuNr0ijGmGIMwSXkabECbXCxm7LraRCgmlobHepuXcUPeUKzKxN5LwPSO1onD684S0FtUUYbVMq9Ik7V8UznbpOjmFaknIZowKKlCkTmgKcyLSq7IaPJd7UuDJVXJDiC49oImEInrjx1xuFbyoBz_wkZlwcgk9GjksTeSz4xzBLcyzVgCwGP2hs8_BtdslXXOrA' \

Dimension

This parameter enables you to define a single property that you want analytics for. You can select only one property in your request.

Response

Based on your request the Analytics API returns paginated play event data in an array of objects. Each object contains these analytics fields:

• value: shows a value for the property you have specified for dimension in your request. For example, if you requested dimension=browser, each value field in the response returns a type of browser that was used during the play events.
• plays: shows the number of play events for one specific value.

Structure

{
    "data": [
        {
            "value": "<selected dimension>",
            "plays": 00
        },
        {
            "value": "<selected dimension>",
            "plays": 00
        }...
    ],
    "pagination": {
        "currentPage": 1,
        "currentPageItems": 3,
        "pageSize": 25,
        "pagesTotal": 1,
        "itemsTotal": 3,
        "links": [
            {
                "rel": "self",
                "uri": "/analytics/videos/plays?dimension=<selected dimension>&currentPage=1&pageSize=25"
            },
            {
                "rel": "first",
                "uri": "/analytics/videos/plays?dimension=<selected dimension>&currentPage=1&pageSize=25"
            },
            {
                "rel": "last",
                "uri": "/analytics/videos/plays?dimension=<selected dimension>&currentPage=1&pageSize=25"
            }
        ]
    }
}

Examples

You can find sample responses for some common analytics parameters here:

{
    "data": [
        {
            "value": "vi3q7HxhApxRF1c8F8r6VeaI",
            "plays": 100
        },
        {
            "value": "vi3q7HxhApxRF1c8F8r6VeaF",
            "plays": 10
        },
        {
            "value": "vi3q7HxhApxRF1c8F8r6VeaH",
            "plays": 1
        }
    ],
    "pagination": {
        "currentPage": 1,
        "currentPageItems": 3,
        "pageSize": 25,
        "pagesTotal": 1,
        "itemsTotal": 3,
        "links": [
            {
                "rel": "self",
                "uri": "/analytics/videos/plays?dimension=videoId&currentPage=1&pageSize=25"
            },
            {
                "rel": "first",
                "uri": "/analytics/videos/plays?dimension=videoId&currentPage=1&pageSize=25"
            },
            {
                "rel": "last",
                "uri": "/analytics/videos/plays?dimension=videoId&currentPage=1&pageSize=25"
            }
        ]
    }
}

{
    "data": [
        {
            "value": "france",
            "plays": 100
        },
        {
            "value": "united states",
            "plays": 10
        },
        {
            "value": "spain",
            "plays": 1
        }
    ],
    "pagination": {
        "currentPage": 1,
        "currentPageItems": 2,
        "pageSize": 2,
        "pagesTotal": 2,
        "itemsTotal": 3,
        "links": [
            {
                "rel": "self",
                "uri": "/analytics/videos/plays?dimension=country&currentPage=1&pageSize=2"
            },
            {
                "rel": "first",
                "uri": "/analytics/videos/plays?dimension=country&currentPage=1&pageSize=2"
            },
            {
                "rel": "next",
                "uri": "/analytics/videos/plays?dimension=country&currentPage=2&pageSize=1"
            },
            {
                "rel": "last",
                "uri": "/analytics/videos/plays?dimension=country&currentPage=2&pageSize=1"
            }
        ]
    }
}

Best practices

To ensure that your Analytics implementation runs smoothly, make sure that you:

• use the appropriate endpoints: /videos for video analytics, and /live-streams for live stream analytics.
• set from and to in your requests keeping in mind that data is only retained for 30 days.
• only select one property for dimension in your request.
• use the videoId: or liveStreamId: prefix appropriately when using the filter parameter.

What's next

Check out the API reference for sample responses and errors, and more details about using the Analytics endpoint.

If you have any questions, check out the Help Center article about Analytics.