API | Beak

API v1.0

With the Beak API comes the ability to programmatically obtain real-time analytics for any tracker that you have created.

To get started with the API, you must create an account and then generate an API Key.

API Usage

View Count

Location

Browser/Device/Platform

PDF Read Percentage

PDF Overall View Time

PDF Per-Page View Time

PDF Event Totals

View Count stats

View Count stats service covers Total, Unique, and Repeat view count datasets for any Tracker in your account. This service supports date-range filtering.

Web Service Example

Query for View Count stats

JSON response for View Count stats

{
    "result": "success",
    "tracker_id": "1a2b3c4d",
    "overall": {
        "view_count_total": 39,
        "view_count_total_daily": 13,
        "view_count_unique": 4,
        "view_count_unique_daily": 1.5,
        "view_count_repeat": 10,
        "view_count_repeat_daily": 3.5,
        "days_since_created": 23,
        "view_day_count": 2,
        "view_last_date": "2021-05-03"
    },
    "series": {
        "date_range_from": "2021-05-19",
        "date_range_to": "2021-05-25",
        "total_entries": 3,
        "total_entries_with_view_count": 3,
        "dates": [
            "2021-05-02",
            "2021-05-03",
            "2021-05-04"
        ],
        "total_count": [
            30,
            8,
            1
        ],
        "unique_count": [
            2,
            1,
            1
        ],
        "repeat_count": [
            6,
            4,
            0
        ]
    },
    "plan_limit_exceeded": 0
}

Parameters

Name	Description
key	(required) API Key.
tracker_id	(required) ID of a Tracker that you created.
from	From date (YYYY-MM-DD). Defaults to past 7 days if blank.
to	To date (YYYY-MM-DD). Defaults to past 7 days if blank.

Response

Field	Description
result	"success" or "error".
tracker_id	Tracker ID that you used while querying.
overall.view_count_total	Total view count overall.
overall.view_count_total_daily	Total view count on average each day overall.
overall.view_count_unique	Unique view count overall.
overall.view_count_unique_daily	Unique view count on on average each day overall.
overall.view_count_repeat	Repeat view count overall.
overall.view_count_repeat_daily	Repeat view count on average each day overall.
overall.days_since_created	Number of days since the tracker was created.
overall.view_day_count	Number of days that views occurred on.
overall.view_last_date	Last date in which a view took place.
series.date_range_from	Beginning date in the filtered date-range series.
series.date_range_to	Ending date in the filtered date-range series.
series.total_entries	Number of entries in the time series
series.total_entries_with_view_count	Number of entries with views in the time series.
series.dates	Series dates, where each value has YYYY-MM-DD format (array).
series.total_count	Total view count for each date in the series (array).
series.unique_count	Unique view count for each date in the series (array).
series.repeat_count	Repeat view count for each day in the series (array).
plan_limit_exceeded	0 (false) or 1 (true). Indicates if plan limit has been exceeded.

Location stats

Location stats service covers the countries and cities and the number of views in each for any Tracker in your account. This service does not support date-range filtering.

Web Service Example

Query for Location stats

JSON response for Location stats

{
    "result": "success",
    "tracker_id": "1a2b3c4d",
    "overall": {
        "days_since_created": 23,
        "view_day_count": 2,
        "view_last_date": "2021-05-03"
    },
    "country_location_counts": [
        {
            "country": "United States",
            "country_code": "US",
            "count": 15
        },
        {
            "country": "Bangladesh",
            "country_code": "BD",
            "count": 7
        },
        {
            "country": "Australia",
            "country_code": "AU",
            "count": 5
        },
        {
            "country": "United Kingdom",
            "country_code": "GB",
            "count": 4
        }
    ],
    "city_location_counts": [
        {
            "city": "Los Angeles, California",
            "country_code": "US",
            "count": 11
        },
        {
            "city": "Dhaka, Dhaka",
            "country_code": "BD",
            "count": 7
        },
        {
            "city": "Sydney, New South Wales",
            "country_code": "AU",
            "count": 5
        },
        {
            "city": "London, England",
            "country_code": "GB",
            "count": 4
        },
        {
            "city": "Washington, Washington, D.C.",
            "country_code": "US",
            "count": 4
        }
    ],
    "plan_limit_exceeded": 0
}

Parameters

Name	Description
key	(required) API Key.
tracker_id	(required) ID of a Tracker that you created.

Response

Field	Description
result	"success" or "error".
tracker_id	Tracker ID that you used while querying.
overall.days_since_created	Number of days since the tracker was created.
overall.view_day_count	Number of days that views occurred on.
overall.view_last_date	Last date in which a view took place.
country_location_counts	List of countries where views occurred, and the view count for each (array).
city_location_counts	List of cities where views occurred, and the view count for each (array).
plan_limit_exceeded	0 (false) or 1 (true). Indicates if plan limit has been exceeded.

Browser/Device/Platform stats

Browser/Device/Platform stats service covers the browsers, devices, and platforms, and the number of views in each for any Tracker in your account. This service does not support date-range filtering.

Web Service Example

Query for Browser/Device/Platform stats

JSON response for Browser/Device/Platform stats

{
    "result": "success",
    "tracker_id": "1a2b3c4d",
    "overall": {
        "days_since_created": 23,
        "view_day_count": 2,
        "view_last_date": "2021-05-03"
    },
    "browser_counts": [
        {
            "browser": "Chrome Browser v90.0 (Blink)",
            "count": 14
        },
        {
            "browser": "Firefox Browser v88.0 (Gecko)",
            "count": 13
        },
        {
            "browser": "Microsoft Edge Browser v90.0 (Blink)",
            "count": 2
        },
        {
            "browser": "Mobile Safari Browser v8.0 (WebKit)",
            "count": 2
        }
    ],
    "device_counts": [
        {
            "device": "Desktop",
            "count": 29
        },
        {
            "device": "Smartphone",
            "count": 2
        }
    ],
    "platform_counts": [
        {
            "platform": "Windows v10 (x64)",
            "count": 25
        },
        {
            "platform": "Mac v10.14",
            "count": 4
        },
        {
            "platform": "iOS v8.4",
            "count": 2
        }
    ],
    "plan_limit_exceeded": 0
}

Parameters

Name	Description
key	(required) API Key.
tracker_id	(required) ID of a Tracker that you created.

Response

Field	Description
result	"success" or "error".
tracker_id	Tracker ID that you used while querying.
overall.days_since_created	Number of days since the tracker was created.
overall.view_day_count	Number of days that views occurred on.
overall.view_last_date	Last date in which a view took place.
browser_counts	List of browser where views occurred, and the view count for each (array).
device_counts	List of devices where views occurred, and the view count for each (array).
platform_counts	List of platform where views occurred, and the view count for each (array).
plan_limit_exceeded	0 (false) or 1 (true). Indicates if plan limit has been exceeded.

PDF Read Percentage stats

PDF Read Percentage stats service covers the percentage of the document that was read by each viewer for each PDF Tracker in your account. This service does not support date-range filtering.

Web Service Example

Query for PDF Read Percentage stats

JSON response for PDF Read Percentage stats

{
    "result": "success",
    "tracker_id": "1a2b3c4d",
    "page_count": 10,
    "percent_read": {
        "twenty": 0,
        "forty": 0,
        "sixty": 0,
        "eighty": 0,
        "one_hundred": 0
    },
    "plan_limit_exceeded": 0
}

Parameters

Name	Description
key	(required) API Key.
tracker_id	(required) ID of a Tracker that you created.

Response

Field	Description
result	"success" or "error".
tracker_id	Tracker ID that you used while querying.
page_count	Total number of pages in the PDF.
percent_read.twenty	Number of viewers that viewed up to 20% of the PDF.
percent_read.forty	Number of viewers that viewed up to 40% of the PDF.
percent_read.sixty	Number of viewers that viewed up to 60% of the PDF.
percent_read.eighty	Number of viewers that viewed up to 80% of the PDF.
percent_read.one_hundred	Number of viewers that viewed 100% of the PDF.
plan_limit_exceeded	0 (false) or 1 (true). Indicates if plan limit has been exceeded.

PDF Overall View Time stats

Overall View Time stats service covers Total and Average view time datasets for each PDF Tracker in your account. This service supports date-range filtering.

Web Service Example

Query for PDF Overall View Time stats

JSON response for PDF Overall View Time stats

{
    "result": "success",
    "tracker_id": "1a2b3c4d",
    "overall": {
        "view_time_total": 39,
        "view_time_average": 4,
        "days_since_created": 23,
        "view_day_count": 2,
        "view_last_date": "2021-05-03"
    },
    "series": {
        "date_range_from": "2021-05-19",
        "date_range_to": "2021-05-25",
        "total_entries": 3,
        "total_entries_with_view_time": 3,
        "dates": [
            "2021-05-02",
            "2021-05-03",
            "2021-05-04"
        ],
        "total_view_time": [
            30,
            8,
            1
        ],
        "average_view_time": [
            2,
            1,
            1
        ]
    },
    "plan_limit_exceeded": 0
}

Parameters

Name	Description
key	(required) API Key.
tracker_id	(required) ID of a Tracker that you created.
from	From date (YYYY-MM-DD). Defaults to past 7 days if blank.
to	To date (YYYY-MM-DD). Defaults to past 7 days if blank.

Response

Field	Description
result	"success" or "error".
tracker_id	Tracker ID that you used while querying.
overall.view_time_total	Total view time (in minutes) overall.
overall.view_time_average	Average view time (in minutes) overall.
overall.days_since_created	Number of days since the tracker was created.
overall.view_day_count	Number of days that views occurred on.
overall.view_last_date	Last date in which a view took place.
series.date_range_from	Beginning date in the filtered date-range series.
series.date_range_to	Ending date in the filtered date-range series.
series.total_entries	Number of entries in the time series
series.total_entries_with_view_time	Number of entries with view time in the time series.
series.dates	Series dates, where each value has YYYY-MM-DD format (array).
series.total_view_time	Total view time (in minutes) for each date in the series (array).
series.average_view_time	Average view time (in minutes) for each date in the series (array).
plan_limit_exceeded	0 (false) or 1 (true). Indicates if plan limit has been exceeded.

PDF Per-Page View Time stats

PDF Per-Page View Time stats service covers the per-page viewing time for each page in each PDF Tracker in your account. This service does not support date-range filtering.

Web Service Example

Query for PDF Per-Page View Time stats

JSON response for PDF Per-Page View Time stats

{
    "result": "success",
    "tracker_id": "1a2b3c4d",
    "page_view_time": {
        "page_count": 4,
        "pages": {
            "1": {
                "view_time_total": 480
            },
            "2": {
                "view_time_total": 555
            },
            "3": {
                "view_time_total": 443
            },
            "4": {
                "view_time_total": 738
            }
        }
    },
    "plan_limit_exceeded": 0
}

Parameters

Name	Description
key	(required) API Key.
tracker_id	(required) ID of a Tracker that you created.

Response

Field	Description
result	"success" or "error".
tracker_id	Tracker ID that you used while querying.
page_view_time.page_count	Total number of pages in the PDF.
page_view_time.pages	List of page numbers and the view time total (in seconds) for each page (JSON list).
plan_limit_exceeded	0 (false) or 1 (true). Indicates if plan limit has been exceeded.

PDF Event Totals stats

Event Totals stats service covers the the number of times viewers took various actions while viewing the PDF.

Web Service Example

Query for PDF Event Totals stats

JSON response for PDF Event Totals stats

{
    "result": "success",
    "tracker_id": "1a2b3c4d",
    "event_totals": {
        "page_timeout": 0,
        "failed_access_attempts": 0,
        "page_viewing_stopped": 140,
        "page_viewing_resumed": 139,
        "print_screen_clicked": 20,
        "print_screen_blocked": 9,
        "prints": 6,
        "text_copied": 17,
        "downloads": 3,
        "zoom_in": 0,
        "zoom_out": 1,
        "find_button_clicked": 8,
        "next_page_clicked": 1,
        "previous_page_clicked": 1,
        "toggle_sidebar": 0,
        "rotate_clockwise": 1,
        "rotate_counter_clockwise": 0
    },
    "plan_limit_exceeded": 0
}

Parameters

Name	Description
key	(required) API Key.
tracker_id	(required) ID of a Tracker that you created.

Response

Field	Description
result	"success" or "error".
tracker_id	Tracker ID that you used while querying.
event_totals.page_timeout	Total times the page of which the pdf resides timed out due to owner controls.
event_totals.failed_access_attempts	Total times the page could not be accessed due to bad access credentials due to owner controls.
event_totals.page_viewing_stopped	Total times viewers minimized the page or switched tabs while viewing due to owner controls.
event_totals.page_viewing_resumed	Total times the viewing resumed after the page viewing stopped due to owner controls.
event_totals.print_screen_clicked	Total times viewers clicked on print screen while viewing.
event_totals.print_screen_blocked	Total times viewers had print screen blocked due to owner controls.
event_totals.prints	Total times viewers printed the PDF.
event_totals.text_copied	Total times viewers copied text within the PDF.
event_totals.downloads	Total times viewers downloaded the PDF.
event_totals.zoom_in	Total times viewers zoomed-in.
event_totals.zoom_out	Total times viewers zoomed-out.
event_totals.find_button_clicked	Total times viewers clicked the "find" button.
event_totals.next_page_clicked	Total times viewers clicked "next page".
event_totals.previous_page_clicked	Total times viewers clicked "previous page".
event_totals.toggle_sidebar	Total times viewers toggled the sidebar in the PDF viewer.
event_totals.rotate_clockwise	Total times viewers rotated the page clockwise.
event_totals.rotate_counter_clockwise	Total times viewers rotated the page counterclockwise.
plan_limit_exceeded	0 (false) or 1 (true). Indicates if plan limit has been exceeded.

Video View/Play Time stats

View/Play Time stats service covers Total and Average view and play time datasets for each Video Tracker in your account.

Web Service Example

Query for Video View/Play Time stats

JSON response for Video View/Play Time stats

{
    "result": "success",
    "tracker_id": "1a2b3c4d",
    "overall": {
        "view_time_total": 39,
        "view_time_average": 4,
        "play_time_total": 10,
        "play_time_average": 1.37,
        "days_since_created": 23,
        "view_day_count": 2,
        "view_last_date": "2021-05-03"
    },
    "series": {
        "date_range_from": "2021-05-19",
        "date_range_to": "2021-05-25",
        "total_entries": 3,
        "total_entries_with_view_time": 3,
        "dates": [
            "2021-05-02",
            "2021-05-03",
            "2021-05-04"
        ],
        "total_view_time": [
            30,
            8,
            1
        ],
        "average_view_time": [
            2,
            1,
            1
        ],
        "total_play_time": [
            0.3,
            0.95,
            0
        ],
        "average_play_time": [
            0.29,
            0.95,
            0
        ]
    },
    "plan_limit_exceeded": 0
}

Parameters

Name	Description
key	(required) API Key.
tracker_id	(required) ID of a Tracker that you created.
from	From date (YYYY-MM-DD). Defaults to past 7 days if blank.
to	To date (YYYY-MM-DD). Defaults to past 7 days if blank.

Response

Field	Description
result	"success" or "error".
tracker_id	Tracker ID that you used while querying.
overall.view_time_total	Total view time (in minutes) overall.
overall.view_time_average	Average view time (in minutes) overall.
overall.play_time_total	Total play time (in minutes) overall.
overall.play_time_average	Average play time (in minutes) overall.
overall.days_since_created	Number of days since the tracker was created.
overall.view_day_count	Number of days that views occurred on.
overall.view_last_date	Last date in which a view took place.
series.date_range_from	Beginning date in the filtered date-range series.
series.date_range_to	Ending date in the filtered date-range series.
series.total_entries	Number of entries in the time series
series.total_entries_with_view_time	Number of entries with view time in the time series.
series.dates	Series dates, where each value has YYYY-MM-DD format (array).
series.total_view_time	Total view time (in minutes) for each date in the series (array).
series.average_view_time	Average view time (in minutes) for each date in the series (array).
series.total_play_time	Total play time (in minutes) for each date in the series (array).
series.average_play_time	Average play time (in minutes) for each date in the series (array).
plan_limit_exceeded	0 (false) or 1 (true). Indicates if plan limit has been exceeded.

Video Event Totals stats

Event Totals stats service covers the the number of times viewers took various actions while viewing the Vidoe.

Web Service Example

Query for Video Event Totals stats

JSON response for Video Event Totals stats

{
    "result": "success",
    "tracker_id": "1a2b3c4d",
    "event_totals": {
        "started": 66,
        "paused": 17,
        "continued": 17,
        "skipped_back": 70,
        "skipped_forward": 128,
        "finished": 48,
        "started_over": 25,
        "page_timeout": 0,
        "failed_access_attempts": 0,
        "page_viewing_stopped": 140,
        "page_viewing_resumed": 139,
        "print_screen_clicked": 20,
        "print_screen_blocked": 9
    },
    "plan_limit_exceeded": 0
}

Parameters

Name	Description
key	(required) API Key.
tracker_id	(required) ID of a Tracker that you created.

Response

Field	Description
result	"success" or "error".
tracker_id	Tracker ID that you used while querying.
event_totals.started	Total times viewers started the video.
event_totals.paused	Total times viewers paused the video.
event_totals.continued	Total times viewers continued watching the video after it was paused.
event_totals.skipped_back	Total times viewers skipped back to an earlier section of the video.
event_totals.skipped_forward	Total times viewers skipped forward to a later section of the video.
event_totals.finished	Total times viewers watched the video to the end.
event_totals.started_over	Total times viewers started the video over from the beginning.
event_totals.page_timeout	Total times the page of which the video resides timed out due to owner controls.
event_totals.failed_access_attempts	Total times the page could not be accessed due to bad access credentials due to owner controls.
event_totals.page_viewing_stopped	Total times viewers minimized the page or switched tabs while viewing due to owner controls.
event_totals.page_viewing_resumed	Total times the viewing resumed after the page viewing stopped due to owner controls.
event_totals.print_screen_clicked	Total times viewers clicked on print screen while viewing.
event_totals.print_screen_blocked	Total times viewers had print screen blocked due to owner controls.
plan_limit_exceeded	0 (false) or 1 (true). Indicates if plan limit has been exceeded.