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_dateandend_dateto get a list of the viewers and the content they saw during the time period. This retrieves a list of all thecontent_keysand viewers during that time period. -
Using the
content_keyto get a list of all the viewers who have watched thatcontent_key. -
Using
fingerprint_listto 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. |