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

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

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

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

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,
"poster": "https://example.com/image.jpg"
}
],
"livestreams": [{"asset_type": "string",
"id": "66f92465-4bce-4cac-a2e2-dedf802faa14",
"name": "Media Item",
"plays": 150,
"displays": 150,
"poster": "https://example.com/image.jpg",
"start_time": "2019-10-30T13:18:17+0000"
}
],
"videos": [{"asset_type": "string",
"id": "66f92465-4bce-4cac-a2e2-dedf802faa14",
"name": "Media Item",
"plays": 150,
"displays": 150,
"poster": "https://example.com/image.jpg",
"duration": 15,
"publish_date": "2019-10-30T13: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-01T00:00:00Z",
"date_to": "2020-01-01T00:00:00Z",
"total": {"displays": 0,
"plays": 0
},
"intervals": [{"start": "2020-01-01T00:00:00Z",
"start_timestamp": 1577833200000,
"end": "2020-01-01T00: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

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-29T21:15:00.000Z",
"end": "2019-10-29T21:15:00.000Z"
},
"intervals": [{"timestamp": 1577833200000,
"date": "2020-01-01T00:00:00Z",
"concurrent": 0
}
]
}

Flowplayer Docs

docs

Analytics API (1.0.0)

Authentication

Requesting the API

Analytics

Video summarised

path Parameters

query Parameters

Responses

Response samples

Category summarised

path Parameters

query Parameters

Responses

Response samples

Workspace summarised

path Parameters

query Parameters

Responses

Response samples

Livestream summarised

path Parameters

query Parameters

Responses

Response samples

Media toplists

query Parameters

Responses

Response samples

Time series analytics

query Parameters

Responses

Response samples

Livestream concurrent viewers

path Parameters

query Parameters

Responses

Response samples

On this page

Analytics API (1.0.0)

Authentication

Requesting the API

Analytics

Video summarised

path Parameters

query Parameters

Responses

Response samples

Category summarised

path Parameters

query Parameters

Responses

Response samples

Workspace summarised

path Parameters

query Parameters

Responses

Response samples

Livestream summarised

path Parameters

query Parameters

Responses

Response samples

Media toplists

query Parameters

Responses

Response samples

Time series analytics

query Parameters

Responses

Response samples

Livestream concurrent viewers

path Parameters

query Parameters

Responses

Response samples

()

On this page