Skip to content

GET Viewer Analytics API

ParOne allows you to pull statistics about your viewers. Use the following REST API to retrieve that information.

Retrieve viewer analytics for your organization

This GET request retrieves the video analytics. Your organization key will be provided by ParOne.

Usage of this API requires informed consent from the user to maintain GDPR compliance.

GET https://reports.parone.app/prod/get_viewer_reports

Usage

There are multiple ways to query this API.

  • Using start_date and end_date to get a list of the viewers and the content they saw during the time period. This retrieves a list of all the content_keys and viewers during that time period.

  • Using the content_key to get a list of all the viewers who have watched that content_key.

  • Using fingerprint_list to return all the videos watched by those fingerprints during the time period.

  • Using tput, or Third Party User Token, to return all the videos watched by this user.

Parameters

ParameterValueComments
organization_keyThe organization key. Provided by ParOne.This API requires the viewer analytics package
start_dateThe start date. Must be in the format YYYY-MM-DD. This is inclusive of this day.Video statistics are stored by UTC day. A video that plays at 10PM EST on 1-Jan will be counted on 2-Jan.
end_dateThe end date. Must be in the format YYY-MM-DD. This is inclusive.Video statistics are stored by UTC day. A video that plays at 10PM EST on 1-Jan will be counted on 2-Jan.
content_keyThe video for which you’d like viewer informationThe content_key. Optional. Must not be specified if fingerprint_list are specified.
fingerprint_listLIST of fingerprintsThe fingerprints to get statistics for. Optional. Must not have content_key and fingerprint_list together.

Example:
‘123456’,‘234567’
tputthe TPUT for which you’d like viewer information forOptional. the third party user token.

Example: test@parone.com.
If specified, the fingerprint_list should not be specified.

Return Value

This call will return a JSON object that returns ips and fingerprints of viewers who watched a video between two dates.

Terminal window
curl 'https://reports.parone.app/demo/get_viewer_reports?organization_key=XXX&start_date=2022-10-25&end_date=2022-10-27&content_key=2d91Ee68EA84Eb8bED31'
{
"data": [
{
"ad_50": 0,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 0,
"ad_played_unmuted": 0,
"ad_position": "midroll",
"ad_skip": 0,
"ad_unmuted": 0,
"country": "USA",
"date": "2022-10-27T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 0,
"video_paused": 0,
"video_played": 0,
"video_played_muted": 0,
"video_played_unmuted": 0,
"video_resumed": 0,
"video_unmuted": 0
},
{
"ad_50": 0,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 0,
"ad_played_unmuted": 0,
"ad_position": "midroll",
"ad_skip": 0,
"ad_unmuted": 0,
"country": "USA",
"date": "2022-10-27T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 2,
"played_50percent": 0,
"played_75percent": 1,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 1,
"video_muted": 1,
"video_paused": 0,
"video_played": 2,
"video_played_muted": 0,
"video_played_unmuted": 2,
"video_resumed": 0,
"video_unmuted": 2
},
{
"ad_50": 2,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 1,
"ad_muted": 0,
"ad_played_muted": 0,
"ad_played_unmuted": 2,
"ad_position": "preroll",
"ad_skip": 1,
"ad_unmuted": 0,
"country": "USA",
"date": "2022-10-27T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 2,
"video_paused": 0,
"video_played": 0,
"video_played_muted": 0,
"video_played_unmuted": 0,
"video_resumed": 0,
"video_unmuted": 0
},
{
"ad_50": 0,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 0,
"ad_played_unmuted": 0,
"ad_position": "midroll",
"ad_skip": 0,
"ad_unmuted": 0,
"country": "USA",
"date": "2022-10-27T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 1,
"video_paused": 0,
"video_played": 1,
"video_played_muted": 0,
"video_played_unmuted": 1,
"video_resumed": 0,
"video_unmuted": 1
},
{
"ad_50": 0,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 1,
"ad_played_unmuted": 0,
"ad_position": "preroll",
"ad_skip": 1,
"ad_unmuted": 0,
"country": "USA",
"date": "2022-10-27T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 1,
"video_paused": 0,
"video_played": 0,
"video_played_muted": 0,
"video_played_unmuted": 0,
"video_resumed": 0,
"video_unmuted": 0
},
{
"ad_50": 0,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 0,
"ad_played_unmuted": 0,
"ad_position": "midroll",
"ad_skip": 0,
"ad_unmuted": 0,
"country": "USA",
"date": "2022-10-26T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "25381798",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 0,
"video_paused": 0,
"video_played": 0,
"video_played_muted": 0,
"video_played_unmuted": 0,
"video_resumed": 0,
"video_unmuted": 0
}
],
"message": "ok",
"status": "ok"
}

This call will return a JSON object that lists the videos that were watched by a certain ip address between multiple dates.

Terminal window
curl "https://reports.parone.app/demo/get_viewer_reports?organization_key=XXX&start_date=2022-10-25&end_date=2022-10-27&'"
{
"data": [
{
"ad_50": 0,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 0,
"ad_played_unmuted": 0,
"ad_position": "midroll",
"ad_skip": 0,
"ad_unmuted": 0,
"content_key": "2d91Ee68EA84Eb8bED31",
"country": "USA",
"date": "2022-10-26T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "25381798",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 0,
"video_paused": 0,
"video_played": 0,
"video_played_muted": 0,
"video_played_unmuted": 0,
"video_resumed": 0,
"video_unmuted": 0
}
],
"message": "ok",
"status": "ok"
}

This call will return a JSON object that lists the videos that were watched by a certain ip address between multiple dates.

Terminal window
curl "https://reports.parone.app/demo/get_viewer_reports?organization_key=XXX&start_date=2022-10-25&end_date=2022-10-27&"
{
"data": [
{
"ad_50": 0,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 0,
"ad_played_unmuted": 0,
"ad_position": "midroll",
"ad_skip": 0,
"ad_unmuted": 0,
"content_key": "2d91Ee68EA84Eb8bED31",
"country": "USA",
"date": "2022-10-27T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 0,
"video_paused": 0,
"video_played": 0,
"video_played_muted": 0,
"video_played_unmuted": 0,
"video_resumed": 0,
"video_unmuted": 0
},
{
"ad_50": 0,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 0,
"ad_played_unmuted": 0,
"ad_position": "midroll",
"ad_skip": 0,
"ad_unmuted": 0,
"content_key": "2d91Ee68EA84Eb8bED31",
"country": "USA",
"date": "2022-10-27T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 2,
"played_50percent": 0,
"played_75percent": 1,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 1,
"video_muted": 1,
"video_paused": 0,
"video_played": 2,
"video_played_muted": 0,
"video_played_unmuted": 2,
"video_resumed": 0,
"video_unmuted": 2
},
{
"ad_50": 2,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 1,
"ad_muted": 0,
"ad_played_muted": 0,
"ad_played_unmuted": 2,
"ad_position": "preroll",
"ad_skip": 1,
"ad_unmuted": 0,
"content_key": "2d91Ee68EA84Eb8bED31",
"country": "USA",
"date": "2022-10-27T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 2,
"video_paused": 0,
"video_played": 0,
"video_played_muted": 0,
"video_played_unmuted": 0,
"video_resumed": 0,
"video_unmuted": 0
},
{
"ad_50": 0,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 0,
"ad_played_unmuted": 0,
"ad_position": "midroll",
"ad_skip": 0,
"ad_unmuted": 0,
"content_key": "2d91Ee68EA84Eb8bED31",
"country": "USA",
"date": "2022-10-27T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 1,
"video_paused": 0,
"video_played": 1,
"video_played_muted": 0,
"video_played_unmuted": 1,
"video_resumed": 0,
"video_unmuted": 1
},
{
"ad_50": 0,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 1,
"ad_played_unmuted": 0,
"ad_position": "preroll",
"ad_skip": 1,
"ad_unmuted": 0,
"content_key": "2d91Ee68EA84Eb8bED31",
"country": "USA",
"date": "2022-10-27T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 1,
"video_paused": 0,
"video_played": 0,
"video_played_muted": 0,
"video_played_unmuted": 0,
"video_resumed": 0,
"video_unmuted": 0
},
{
"ad_50": 0,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 0,
"ad_played_unmuted": 0,
"ad_position": "midroll",
"ad_skip": 0,
"ad_unmuted": 0,
"content_key": "b4A486fde6dDf7Cb6C7c",
"country": "USA",
"date": "2022-10-27T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 5,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 5,
"video_paused": 0,
"video_played": 5,
"video_played_muted": 5,
"video_played_unmuted": 0,
"video_resumed": 0,
"video_unmuted": 0
},
{
"ad_50": 0,
"ad_autoplayed": 5,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 5,
"ad_played_unmuted": 0,
"ad_position": "preroll",
"ad_skip": 0,
"ad_unmuted": 0,
"content_key": "b4A486fde6dDf7Cb6C7c",
"country": "USA",
"date": "2022-10-27T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 0,
"video_paused": 0,
"video_played": 0,
"video_played_muted": 0,
"video_played_unmuted": 0,
"video_resumed": 0,
"video_unmuted": 0
},
{
"ad_50": 0,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 0,
"ad_played_unmuted": 0,
"ad_position": "midroll",
"ad_skip": 0,
"ad_unmuted": 0,
"content_key": "b4A486fde6dDf7Cb6C7c",
"country": "USA",
"date": "2022-10-25T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 9,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 9,
"video_paused": 0,
"video_played": 9,
"video_played_muted": 9,
"video_played_unmuted": 0,
"video_resumed": 0,
"video_unmuted": 0
},
{
"ad_50": 0,
"ad_autoplayed": 10,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 10,
"ad_played_unmuted": 0,
"ad_position": "preroll",
"ad_skip": 0,
"ad_unmuted": 0,
"content_key": "b4A486fde6dDf7Cb6C7c",
"country": "USA",
"date": "2022-10-25T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "194623036",
"played_25percent": 0,
"played_50percent": 0,
"played_75percent": 0,
"video_autoplay": 0,
"video_caption_enabled": 0,
"video_ended": 0,
"video_muted": 0,
"video_paused": 0,
"video_played": 0,
"video_played_muted": 0,
"video_played_unmuted": 0,
"video_resumed": 0,
"video_unmuted": 0
},
{
"ad_50": 0,
"ad_autoplayed": 0,
"ad_clicked": 0,
"ad_done": 0,
"ad_muted": 0,
"ad_played_muted": 0,
"ad_played_unmuted": 0,
"ad_position": "midroll",
"ad_skip": 0,
"ad_unmuted": 0,
"content_key": "jahpCNEo70IE2Bi0aZ16G",
"country": "USA",
"date": "2022-10-25T23:59:59.000Z",
"device_type": "Desktop",
"fingerprint": "3032900081",
"played_25percent": 3201,
"played_50percent": 0,
"played_75percent": 3193,
"video_autoplay": 3230,
"video_caption_enabled": 0,
"video_ended": 3132,
"video_muted": 0,
"video_paused": 0,
"video_played": 3194,
"video_played_muted": 0,
"video_played_unmuted": 0,
"video_resumed": 0,
"video_unmuted": 0
}
],
"message": "ok",
"status": "ok"
}

Structure of the Returned Results

The viewer statistics object contains the following fields

FieldValueComments
dateThe date of the results.An ISO 8601 Date. As mentioned above, this is the day for which the statistics are gathered in UTC. Statistics for a day start at 12:00:00:000 and end at 23:59:59:999
content_keystringIdentifies the video that the ads are associated with.
countrystringThe country played. This is a three-letter country code.
device_typeStringWhat kind of device played the video. One of: Mobile, Desktop, Tablet, TV, Other
ipstringthe IP address
fingerprintstringthe device fingerprint
tputstringThe third party user token
video_playednumberthe number of times a video was played
played_1snumberThe number of times the video was played for 1 second. This is most often used to define views.
played_3snumberThe number of times the video was played for 3 seconds
played_15snumberThe number of times the video was played for 15 seconds
played_30snumberThe number of times the video was played for 30 seconds
played_25percentnumberThe number of times the video was played to 25% of its length
played_50percentnumberThe number of times the video was played to 50% of its length
played_75percentnumberThe number of times the video was played to 75% of its length
video_endednumberThe number of times the video was played to the end
video_mutednumberThe number of times the video was muted during playback
video_unmutednumberThe number of times the video was unmuted during playback
video_played_mutednumberThe number of times the video was played muted.
video_played_unmutednumberThe number of times the video was played unmuted
video_caption_enablednumberThe number of times captions were enabled for the video (if captions are present)
video_pausednumberThe number of times the video was paused
video_resumednumberThe number of times the video was resumed
video_dockednumberThe number of times the video was docked
video_undockednumberThe number of times the video was undocked
video_entered_fullscreennumberThe number of times the video entered fullscreen
video_exited_fulscreennumberThe number of times the video was exited fullscreen
ad_autoplayednumberthe number of times an ad was shown during an autoplay video
ad_donenumberThe number of times an ad finished
ad_skipnumberThe number of times an ad was skipped
ad_50numberThe number of ads played to 50%
ad_clickednumberThe number of times an ad was clicked
ad_mutednumberThe number of times an ad was muted
ad_unmutednumberThe number of times an ad was unmuted
ad_played_mutednumberThe number of times an ad was played muted.
ad_played_unmutednumberThe number of times an ad was played unmuted.