Sign up for free

Analytics

Get play events for video

Retrieve filtered analytics about the number of plays for your videos in a project.

get /analytics/videos/plays
from string

required

Use this query parameter to set the start date for the time period that you want analytics for.

  • The API returns analytics data including the day you set in from.
  • The date you set must be within the last 30 days.
  • The value you provide must follow the YYYY-MM-DD format.
Format
date
Example
"2023-06-01"
to string

Use this optional query parameter to set the end date for the time period that you want analytics for.

  • If you do not specify a to date, the API returns analytics data starting from the from date up until today, and excluding today.
  • The date you set must be within the last 30 days.
  • The value you provide must follow the YYYY-MM-DD format.
Format
date
Example
"2023-06-10"
dimension string

required

Use this query parameter to define the dimension that you want analytics for.

  • videoId: Returns analytics based on the public video identifiers.
  • emittedAt: Returns analytics based on the times of the play events. The API returns data in specific interval groups. When the date period you set in from and to is less than or equals to 2 days, the response for this dimension is grouped in hourly intervals. Otherwise, it is grouped in daily intervals.
  • country: Returns analytics based on the viewers' country. The list of supported country names are based on the GeoNames public database.
  • deviceType: Returns analytics based on the type of device used by the viewers during the play event. Possible response values are: computer, phone, tablet, tv, console, wearable, unknown.
  • operatingSystem: Returns analytics based on the operating system used by the viewers during the play event. Response values include windows, mac osx, android, ios, linux.
  • browser: Returns analytics based on the browser used by the viewers during the play event. Response values include chrome, firefox, edge, opera.
Enum
  • videoId
  • emittedAt
  • country
  • deviceType
  • operatingSystem
  • browser
Example
"browser"
filter string

Use this query parameter to filter your results to a specific video in a project that you want analytics for. You must use the videoId: prefix when specifying a video ID.

Example
"videoId:vi3q7HxhApxRF1c8F8r6VeaI"
currentPage int

Choose the number of search results to return per page. Minimum value: 1

Default
1
Example
2
pageSize int

Results per page. Allowed values 1-100, default is 25.

Default
25
Example
30

Requests

package main

import (
    "context"
    "fmt"
    "os"
    "time"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_KEY").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_KEY").Build()
    req := apivideosdk.AnalyticsApiGetVideosPlaysRequest{}

    req.From(time.Now()) // string | Use this query parameter to set the start date for the time period that you want analytics for. - The API returns analytics data including the day you set in `from`. - The date you set must be **within the last 30 days**. - The value you provide must follow the `YYYY-MM-DD` format. 
    req.Dimension("browser") // string | Use this query parameter to define the dimension that you want analytics for. - `videoId`: Returns analytics based on the public video identifiers. - `emittedAt`: Returns analytics based on the times of the play events. The API returns data in specific interval groups. When the date period you set in `from` and `to` is less than or equals to 2 days, the response for this dimension is grouped in hourly intervals. Otherwise, it is grouped in daily intervals. - `country`: Returns analytics based on the viewers' country. The list of supported country names are based on the [GeoNames public database](https://www.geonames.org/countries/). - `deviceType`: Returns analytics based on the type of device used by the viewers during the play event. - `operatingSystem`: Returns analytics based on the operating system used by the viewers during the play event. - `browser`: Returns analytics based on the browser used by the viewers during the play event.
    req.To(time.Now()) // string | Use this optional query parameter to set the end date for the time period that you want analytics for. - If you do not specify a `to` date, the API returns analytics data starting from the `from` date up until today, and excluding today. - The date you set must be **within the last 30 days**. - The value you provide must follow the `YYYY-MM-DD` format. 
    req.Filter("videoId:vi3q7HxhApxRF1c8F8r6VeaI") // string | Use this query parameter to filter your results to a specific video in a project that you want analytics for. You must use the `videoId:` prefix when specifying a video ID.
    req.CurrentPage(int32(2)) // int32 | Choose the number of search results to return per page. Minimum value: 1 (default to 1)
    req.PageSize(int32(30)) // int32 | Results per page. Allowed values 1-100, default is 25. (default to 25)

    res, err := client.Analytics.GetVideosPlays(req)


    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `Analytics.GetVideosPlays``: %v\n", err)
    }
    // response from `GetVideosPlays`: AnalyticsPlaysResponse
    fmt.Fprintf(os.Stdout, "Response from `Analytics.GetVideosPlays`: %v\n", res)
}

Responses

ExamplesSchema

Success

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

Breakdown video-plays by videoId for a project.

Get play events for live stream

Retrieve filtered analytics about the number of plays for your live streams in a project.

get /analytics/live-streams/plays
from string

required

Use this query parameter to set the start date for the time period that you want analytics for.

  • The API returns analytics data including the day you set in from.
  • The date you set must be within the last 30 days.
  • The value you provide must follow the YYYY-MM-DD format.
Format
date
Example
"2023-06-01"
to string

Use this optional query parameter to set the end date for the time period that you want analytics for.

  • If you do not specify a to date, the API returns analytics data starting from the from date up until today, and excluding today.
  • The date you set must be within the last 30 days.
  • The value you provide must follow the YYYY-MM-DD format.
Format
date
Example
"2023-06-10"
dimension string

required

Use this query parameter to define the dimension that you want analytics for.

  • liveStreamId: Returns analytics based on the public live stream identifiers.
  • emittedAt: Returns analytics based on the times of the play events. The API returns data in specific interval groups. When the date period you set in from and to is less than or equals to 2 days, the response for this dimension is grouped in hourly intervals. Otherwise, it is grouped in daily intervals.
  • country: Returns analytics based on the viewers' country. The list of supported country names are based on the GeoNames public database.
  • deviceType: Returns analytics based on the type of device used by the viewers during the play event. Possible response values are: computer, phone, tablet, tv, console, wearable, unknown.
  • operatingSystem: Returns analytics based on the operating system used by the viewers during the play event. Response values include windows, mac osx, android, ios, linux.
  • browser: Returns analytics based on the browser used by the viewers during the play event. Response values include chrome, firefox, edge, opera.
Enum
  • liveStreamId
  • emittedAt
  • country
  • deviceType
  • operatingSystem
  • browser
Example
"browser"
filter string

Use this query parameter to filter your results to a specific live stream in a project that you want analytics for. You must use the liveStreamId: prefix when specifying a live stream ID.

Example
"liveStreamId:li3q7HxhApxRF1c8F8r6VeaI"
currentPage int

Choose the number of search results to return per page. Minimum value: 1

Default
1
Example
2
pageSize int

Results per page. Allowed values 1-100, default is 25.

Default
25
Example
30

Requests

package main

import (
    "context"
    "fmt"
    "os"
    "time"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_KEY").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_KEY").Build()
    req := apivideosdk.AnalyticsApiGetLiveStreamsPlaysRequest{}

    req.From(time.Now()) // string | Use this query parameter to set the start date for the time period that you want analytics for. - The API returns analytics data including the day you set in `from`. - The date you set must be **within the last 30 days**. - The value you provide must follow the `YYYY-MM-DD` format. 
    req.Dimension("browser") // string | Use this query parameter to define the dimension that you want analytics for. - `liveStreamId`: Returns analytics based on the public live stream identifiers. - `emittedAt`: Returns analytics based on the times of the play events. The API returns data in specific interval groups. When the date period you set in `from` and `to` is less than or equals to 2 days, the response for this dimension is grouped in hourly intervals. Otherwise, it is grouped in daily intervals. - `country`: Returns analytics based on the viewers' country. The list of supported country names are based on the [GeoNames public database](https://www.geonames.org/countries/). - `deviceType`: Returns analytics based on the type of device used by the viewers during the play event. - `operatingSystem`: Returns analytics based on the operating system used by the viewers during the play event. - `browser`: Returns analytics based on the browser used by the viewers during the play event.
    req.To(time.Now()) // string | Use this optional query parameter to set the end date for the time period that you want analytics for. - If you do not specify a `to` date, the API returns analytics data starting from the `from` date up until today, and excluding today. - The date you set must be **within the last 30 days**. - The value you provide must follow the `YYYY-MM-DD` format. 
    req.Filter("liveStreamId:li3q7HxhApxRF1c8F8r6VeaI") // string | Use this query parameter to filter your results to a specific live stream in a project that you want analytics for. You must use the `liveStreamId:` prefix when specifying a live stream ID.
    req.CurrentPage(int32(2)) // int32 | Choose the number of search results to return per page. Minimum value: 1 (default to 1)
    req.PageSize(int32(30)) // int32 | Results per page. Allowed values 1-100, default is 25. (default to 25)

    res, err := client.Analytics.GetLiveStreamsPlays(req)


    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `Analytics.GetLiveStreamsPlays``: %v\n", err)
    }
    // response from `GetLiveStreamsPlays`: AnalyticsPlaysResponse
    fmt.Fprintf(os.Stdout, "Response from `Analytics.GetLiveStreamsPlays`: %v\n", res)
}

Responses

ExamplesSchema

Success

{
  "data": [
    {
      "value": "li3q7HxhApxRF1c8F8r6VeaI",
      "plays": 100
    },
    {
      "value": "li3q7HxhApxRF1c8F8r6VeaB",
      "plays": 10
    },
    {
      "value": "li3q7HxhApxRF1c8F8r6VeaD",
      "plays": 1
    }
  ],
  "pagination": {
    "currentPage": 1,
    "currentPageItems": 2,
    "pageSize": 2,
    "pagesTotal": 2,
    "itemsTotal": 3,
    "links": [
      {
        "rel": "self",
        "uri": "/analytics/live-streams/plays?dimension=liveStreamId&currentPage=1&pageSize=2"
      },
      {
        "rel": "first",
        "uri": "/analytics/live-streams/plays?dimension=liveStreamId&currentPage=2&pageSize=1"
      },
      {
        "rel": "last",
        "uri": "/analytics/live-streams/plays?dimension=liveStreamId&currentPage=2&pageSize=1"
      }
    ]
  }
}

Breakdown video-plays by liveStreamId for a project.

Was this page helpful?