GET Viewer Analytics API

Requires ParOne Enterprise Player

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

Parameter	Value	Comments
organization_key	The organization key. Provided by ParOne.	This API requires the viewer analytics package
start_date	The 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_date	The 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_key	The video for which you’d like viewer information	The content_key. Optional. Must not be specified if fingerprint_list are specified.
fingerprint_list	LIST of fingerprints	The fingerprints to get statistics for. Optional. Must not have content_key and fingerprint_list together. Example: ‘123456’,‘234567’
tput	the TPUT for which you’d like viewer information for	Optional. 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.

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.

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.

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

Field	Value	Comments
date	The 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_key	string	Identifies the video that the ads are associated with.
country	string	The country played. This is a three-letter country code.
device_type	String	What kind of device played the video. One of: Mobile, Desktop, Tablet, TV, Other
ip	string	the IP address
fingerprint	string	the device fingerprint
tput	string	The third party user token
video_played	number	the number of times a video was played
played_1s	number	The number of times the video was played for 1 second. This is most often used to define views.
played_3s	number	The number of times the video was played for 3 seconds
played_15s	number	The number of times the video was played for 15 seconds
played_30s	number	The number of times the video was played for 30 seconds
played_25percent	number	The number of times the video was played to 25% of its length
played_50percent	number	The number of times the video was played to 50% of its length
played_75percent	number	The number of times the video was played to 75% of its length
video_ended	number	The number of times the video was played to the end
video_muted	number	The number of times the video was muted during playback
video_unmuted	number	The number of times the video was unmuted during playback
video_played_muted	number	The number of times the video was played muted.
video_played_unmuted	number	The number of times the video was played unmuted
video_caption_enabled	number	The number of times captions were enabled for the video (if captions are present)
video_paused	number	The number of times the video was paused
video_resumed	number	The number of times the video was resumed
video_docked	number	The number of times the video was docked
video_undocked	number	The number of times the video was undocked
video_entered_fullscreen	number	The number of times the video entered fullscreen
video_exited_fulscreen	number	The number of times the video was exited fullscreen
ad_autoplayed	number	the number of times an ad was shown during an autoplay video
ad_done	number	The number of times an ad finished
ad_skip	number	The number of times an ad was skipped
ad_50	number	The number of ads played to 50%
ad_clicked	number	The number of times an ad was clicked
ad_muted	number	The number of times an ad was muted
ad_unmuted	number	The number of times an ad was unmuted
ad_played_muted	number	The number of times an ad was played muted.
ad_played_unmuted	number	The number of times an ad was played unmuted.