Analytics API (1.0.0)

Download OpenAPI specification:Download

Access analytics about your videos and livestreams programmatically.

Authentication

You'll need both API key and Site/Workspace id in most of the API call. You can find your API key and siteid (workspaceid) under workspace/settings.

In all analytics request both API key and Site/Workspace id must be provided as headers with the name x-flowplayer-site-id and x-flowplayer-api-key.

See sample below:

 x-flowplayer-api-key:<your_api_key>
 x-flowplayer-site-id:<your_site_id>

Requesting the API

Base url for the API is:

 https://api.flowplayer.com/analytics/

Requesting endpoints is done by specifying needed authentication headers and do a get request to wanted endpoint.

 --header: x-flowplayer-site-id:<your_site_id>
 --header: x-flowplayer-api-key:<your_api_key>
 https://api.flowplayer.com/analytics/videos/{video_id}

Content Type

The Analytics API only support Json-format output.

Analytics

Endpoints for fetch analytics on your video and livestreams.

Video summarised

Return summarised analytics for a specific video. The returned video retention is divided into 100 segments and every segment represents 1% for the video duration. The return value of this endpoint includes viewing counts for each of these 100 segments.

path Parameters
id
required
string

ID of the video

query Parameters
start
string

Starting date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

end
string

Ending date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

Responses

Response samples

Content type
application/json
{
  • "displays": 100,
  • "plays": {
    • "total": 0,
    • "device": {
      • "desktop": 0,
      • "mobile": 0,
      • "tablet": 0
      },
    • "mobile_os": {
      • "android": 0,
      • "ios": 0,
      • "windows_phone": 0
      }
    },
  • "engagement": {
    • "duration": 20,
    • "average_seconds_viewed": 32.45,
    • "total_seconds_viewed": 3230,
    • "play_rate": 0.2,
    • "completion_rate": 0.42,
    • "average_completion": 0.5
    },
  • "domains": [
    • {
      • "name": "flowplayer.com",
      • "plays": 150
      }
    ],
  • "countries": [
    • {
      • "name": "Finland",
      • "iso_3166_2": "FI",
      • "plays": 150
      }
    ],
  • "players": [
    • {
      • "id": "66f92465-4bce-4cac-a2e2-dedf802faa14",
      • "name": "Player One",
      • "plays": 150
      }
    ],
  • "time": {
    • "start": 1523570400000,
    • "end": 1524570400000
    }
}

Category summarised

This endpoint is used to query summarised analytics for a specific category. The category retention is divided into 100 segments and every segment represents 1% for the category videos duration. The return value of this endpoint includes viewing counts for each of these 100 segments.

path Parameters
id
required
string

ID of the category

query Parameters
start
string

Starting date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

end
string

Ending date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

Responses

Response samples

Content type
application/json
{
  • "total": {
    • "displays": 100,
    • "plays": {
      • "total": 0,
      • "device": {
        • "desktop": 0,
        • "mobile": 0,
        • "tablet": 0
        },
      • "mobile_os": {
        • "android": 0,
        • "ios": 0,
        • "windows_phone": 0
        }
      },
    • "engagement": {
      • "play_rate": 0.2,
      • "completion_rate": 0.42,
      • "average_completion": 0.5
      },
    • "domains": [
      • {
        • "name": "flowplayer.com",
        • "plays": 150
        }
      ],
    • "countries": [
      • {
        • "name": "Finland",
        • "iso_3166_2": "FI",
        • "plays": 150
        }
      ],
    • "players": [
      • {
        • "id": "66f92465-4bce-4cac-a2e2-dedf802faa14",
        • "name": "Player One",
        • "plays": 150
        }
      ]
    },
  • "video": {
    • "displays": 100,
    • "plays": {
      • "total": 0,
      • "device": {
        • "desktop": 0,
        • "mobile": 0,
        • "tablet": 0
        },
      • "mobile_os": {
        • "android": 0,
        • "ios": 0,
        • "windows_phone": 0
        }
      },
    • "engagement": {
      • "play_rate": 0.2,
      • "completion_rate": 0.42,
      • "average_completion": 0.5
      },
    • "domains": [
      • {
        • "name": "flowplayer.com",
        • "plays": 150
        }
      ],
    • "countries": [
      • {
        • "name": "Finland",
        • "iso_3166_2": "FI",
        • "plays": 150
        }
      ],
    • "players": [
      • {
        • "id": "66f92465-4bce-4cac-a2e2-dedf802faa14",
        • "name": "Player One",
        • "plays": 150
        }
      ]
    },
  • "live": {
    • "displays": 100,
    • "plays": {
      • "total": 0,
      • "device": {
        • "desktop": 0,
        • "mobile": 0,
        • "tablet": 0
        },
      • "mobile_os": {
        • "android": 0,
        • "ios": 0,
        • "windows_phone": 0
        }
      },
    • "engagement": {
      • "play_rate": 0.2,
      • "completion_rate": 0.42,
      • "average_completion": 0.5
      },
    • "domains": [
      • {
        • "name": "flowplayer.com",
        • "plays": 150
        }
      ],
    • "countries": [
      • {
        • "name": "Finland",
        • "iso_3166_2": "FI",
        • "plays": 150
        }
      ],
    • "players": [
      • {
        • "id": "66f92465-4bce-4cac-a2e2-dedf802faa14",
        • "name": "Player One",
        • "plays": 150
        }
      ]
    }
}

Workspace summarised

This endpoint is used to query summarised analytics for a specific Workspace. The Workspace retention is divided into 100 segments and every segment represents 1% for the Workspace videos duration. The return value of this endpoint includes viewing counts for each of these 100 segments.

path Parameters
id
required
string

ID of the Workspace/Site

query Parameters
start
string

Starting date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

end
string

Ending date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

Responses

Response samples

Content type
application/json
{
  • "total": {
    • "displays": 100,
    • "plays": {
      • "total": 0,
      • "device": {
        • "desktop": 0,
        • "mobile": 0,
        • "tablet": 0
        },
      • "mobile_os": {
        • "android": 0,
        • "ios": 0,
        • "windows_phone": 0
        }
      },
    • "engagement": {
      • "play_rate": 0.2,
      • "completion_rate": 0.42,
      • "average_completion": 0.5
      },
    • "domains": [
      • {
        • "name": "flowplayer.com",
        • "plays": 150
        }
      ],
    • "countries": [
      • {
        • "name": "Finland",
        • "iso_3166_2": "FI",
        • "plays": 150
        }
      ],
    • "players": [
      • {
        • "id": "66f92465-4bce-4cac-a2e2-dedf802faa14",
        • "name": "Player One",
        • "plays": 150
        }
      ]
    },
  • "video": {
    • "displays": 100,
    • "plays": {
      • "total": 0,
      • "device": {
        • "desktop": 0,
        • "mobile": 0,
        • "tablet": 0
        },
      • "mobile_os": {
        • "android": 0,
        • "ios": 0,
        • "windows_phone": 0
        }
      },
    • "engagement": {
      • "play_rate": 0.2,
      • "completion_rate": 0.42,
      • "average_completion": 0.5
      },
    • "domains": [
      • {
        • "name": "flowplayer.com",
        • "plays": 150
        }
      ],
    • "countries": [
      • {
        • "name": "Finland",
        • "iso_3166_2": "FI",
        • "plays": 150
        }
      ],
    • "players": [
      • {
        • "id": "66f92465-4bce-4cac-a2e2-dedf802faa14",
        • "name": "Player One",
        • "plays": 150
        }
      ]
    },
  • "live": {
    • "displays": 100,
    • "plays": {
      • "total": 0,
      • "device": {
        • "desktop": 0,
        • "mobile": 0,
        • "tablet": 0
        },
      • "mobile_os": {
        • "android": 0,
        • "ios": 0,
        • "windows_phone": 0
        }
      },
    • "engagement": {
      • "play_rate": 0.2,
      • "completion_rate": 0.42,
      • "average_completion": 0.5
      },
    • "domains": [
      • {
        • "name": "flowplayer.com",
        • "plays": 150
        }
      ],
    • "countries": [
      • {
        • "name": "Finland",
        • "iso_3166_2": "FI",
        • "plays": 150
        }
      ],
    • "players": [
      • {
        • "id": "66f92465-4bce-4cac-a2e2-dedf802faa14",
        • "name": "Player One",
        • "plays": 150
        }
      ]
    }
}

Livestream summarised

Return summarised analytics for a specific livestream.

path Parameters
id
required
string

ID of the Livestream

query Parameters
start
string

Starting date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

end
string

Ending date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

Responses

Response samples

Content type
application/json
{
  • "displays": 100,
  • "plays": {
    • "total": 0,
    • "device": {
      • "desktop": 0,
      • "mobile": 0,
      • "tablet": 0
      },
    • "mobile_os": {
      • "android": 0,
      • "ios": 0,
      • "windows_phone": 0
      }
    },
  • "engagement": {
    • "average_seconds_viewed": 32.45,
    • "total_seconds_viewed": 3230,
    • "play_rate": 0.2,
    • "completion_rate": 0.42,
    • "average_completion": 0.5
    },
  • "domains": [
    • {
      • "name": "flowplayer.com",
      • "plays": 150
      }
    ],
  • "countries": [
    • {
      • "name": "Finland",
      • "iso_3166_2": "FI",
      • "plays": 150
      }
    ],
  • "players": [
    • {
      • "id": "66f92465-4bce-4cac-a2e2-dedf802faa14",
      • "name": "Player One",
      • "plays": 150
      }
    ],
  • "retention": [
    • {
      • "seconds": 0,
      • "viewers": 0
      }
    ],
  • "time": {
    • "start": 1523570400000,
    • "end": 1524570400000
    }
}

Media toplists

This endpoint returns media assets, Videos and Livestreams, having the most plays or displays on a Workspace, Player or Category during a specified period of time.

query Parameters
id
required
string

ID of the Workspace, Player or Category that you want to list with.

type
required
string
Example: type=workspace

Type of asset that you what to use to filter your listing. Possible values workspace, category, player.

start
string

Starting date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

end
string

Ending date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

size
number
Example: size=200

Maximum number of media assets to be returned, 10 is returned if size is not specified. The request is limited to return 100 media assets.

sort
string
Example: sort=plays

Sorting used when listing media assets. Possible values displays and plays.

Responses

Response samples

Content type
application/json
{
  • "assets": [
    • {
      • "asset_type": "string",
      • "id": "66f92465-4bce-4cac-a2e2-dedf802faa14",
      • "name": "Media Item",
      • "plays": 150,
      • "displays": 150,
      }
    ],
  • "livestreams": [
    • {
      • "asset_type": "string",
      • "id": "66f92465-4bce-4cac-a2e2-dedf802faa14",
      • "name": "Media Item",
      • "plays": 150,
      • "displays": 150,
      • "start_time": "2019年10月30日T13:18:17+0000"
      }
    ],
  • "videos": [
    • {
      • "asset_type": "string",
      • "id": "66f92465-4bce-4cac-a2e2-dedf802faa14",
      • "name": "Media Item",
      • "plays": 150,
      • "displays": 150,
      • "duration": 15,
      • "publish_date": "2019年10月30日T13:18:17+0000"
      }
    ]
}

Time series analytics

Return time series analytics for either a workspace, category, livestream or video.

query Parameters
id
required
string

ID of the workspace, category, livestream or video.

type
required
string
Example: type=workspace

Type of asset to filter on. Supports workspace, category, livestream or video.

start
string

Starting date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

end
string

Ending date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

asset_type
string
Example: asset_type=livestream

If the response should contain plays and displays for livestream, video or both summarized. Supports livestream, video and total

Responses

Response samples

Content type
application/json
{
  • "series": [
    • {
      • "date_from": "2020年01月01日T00:00:00Z",
      • "date_to": "2020年01月01日T00:00:00Z",
      • "total": {
        • "displays": 0,
        • "plays": 0
        },
      • "intervals": [
        • {
          • "start": "2020年01月01日T00:00:00Z",
          • "start_timestamp": 1577833200000,
          • "end": "2020年01月01日T00:00:00Z",
          • "end_timestamp": 1577833200000,
          • "displays": 0,
          • "plays": 0
          }
        ]
      }
    ]
}

Livestream concurrent viewers

Returns concurrent viewers per minute for the livestream. It will return viewers per minute for every minute in the selected timespan and also return 0 for each minute without viewers. Maximum timespan allowed is 24 hours. If no start and end parameters are provided this endpoint will automatically return the latest hour. It will also return a value that displays the current number of concurrent viewers regardless of the selected timespan.

path Parameters
id
required
string

ID of the livestream

query Parameters
start
string

Starting date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

end
string

Ending date/time of the interval, format YYYY-MM-DDTHH or YYYY-MM-DD

Responses

Response samples

Content type
application/json
{
  • "concurrent_now": 0,
  • "time": {
    • "start": "2019年10月29日T21:15:00.000Z",
    • "end": "2019年10月29日T21:15:00.000Z"
    },
  • "intervals": [
    • {
      • "timestamp": 1577833200000,
      • "date": "2020年01月01日T00:00:00Z",
      • "concurrent": 0
      }
    ]
}
Results
  • [[ crumb.name ]]

On this page

AltStyle によって変換されたページ (->オリジナル) /