Skip to content
ParOne

GET Viewer Analytics

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

Retrieve viewer analytics for your organization

Section titled “Retrieve viewer analytics for your organization”

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

GEThttps://reports.parone.app/prod/get_viewer_reports

Usage

Section titled “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

Section titled “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

Section titled “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

Section titled “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.