Analytics Query Tools

🚧

All data availability constraints apply to making requests to the Analytics API.

JW Player provides you with several options to query the data with the Analytics API. Read each approach and click on the link for the applicable steps to get started.

🔑

You can also query the API directly to run a report or run a report query with Custom Reports from your JWP dashboard.

Active Google Sheet

Use the following steps to query your data:

1. Download the JW Analytics Active Sheet upload the sheet to your Google Drive.
2. In the Account Info section, enter your key for the Property Key in cell C6.
3. Enter your Secret cell C7.
4. In the Filters section, select your dimensions and metrics from the drop-down menus. The order of your selections determines the column order in the query results.

   📘

   If you select more filters than are permitted by your JW Player account license, you will receive an error when running the query. For Enterprise license customers, additional dimension information is returned in the query results.

5. In the Date Range section, enter a Start Date and End Date.
6. Enter the Result Limit to increase or decrease the number of results displayed in the Google Sheet.
7. Click Run Query.

After a few moments, the results of the query display in the Google Sheet, starting from column I. The results are sorted in descending order by the value of the selected metrics.

PHP samples

Make a query for standard analytics data

Use the following steps to query your data:

1. Download and unzip the jwdeveloper-platformdemos repo.
2. Open jwdeveloper-platformdemos-master/analytics-api-samples/php-samples/analytics-example.php in a code editor or text editor.
3. Set the $body->start_date to the first date of your query's date range, using the YYYY-MM-DD format.
4. Set the $body->end_date to the last date of your query's date range, using the YYYY-MM-DD format.
5. Set the $body->dimensions to the list of dimensions (dimension_id) to include in the query.
6. Set the $body->metrics to the list of metric indices (metric_id) to include in the query.
7. (Optional) Set the $body->filter to the list of filter indices to include in the query.

   📘

   You can find an explanation of the available options in the filter definition in the /v2/sites/site_id/analytics/queries/ route body params. If you select more filters than are permitted by your JW Player account license, you will receive an error when running the query.

8. (Optional) Change the value of $pageLen to to increase or decrease the number of results returned.
9. (Optional) Update the first argument of $fpCSV = fopen() to change the name of the .csv file that is generated.
10. (Optional - Enterprise or Developer license only) Set $body->include_metadata = 1 to include additional dimension information in the query. The /v2/sites/site_id/analytics/queries/ response parameter information for includes and metadata details the information returned.
11. Save the file.
12. Open a command-line interface (CLI) and navigate to the folder containing analytics-example.php.
13. At the CLI prompt, type: php analytics-example.php [site_id] [secret].

    📘

    Be sure to replace the [site_id] placeholder with the appropriate site_id and the [secret] placeholder with your secret.

After a few moments, status information appears in the CLI which includes the remaining requests that can be made to the Analytics API and a .csv file is created in the same folder as the analytics-example.php file.

The following sample query body returns the total number of plays for each of the top two countries ($pageLen=2 and country_code) within the date range of June 1, 2017 - June 2, 2017. The results are filtered for desktop only.

$pageLen = 2;
$body = new stdClass();
$body->start_date = '2017-06-01';
$body->end_date = '2017-06-02';
$body->page_length = $pageLen;
$body->dimensions = ['country_code'];
$body->filter = [
  ["field" => "device_id", "operator" => "=", "value" => ["Desktop"]],
];     
$body->metrics = [
  ["operation" => "sum", "field" => 'plays'],
];

Make a query for enriched video data

This enriched video report combines metadata and metrics data in a single report. Some of the information included in this report include: completes, media ID, plays, property key, time watched per viewer, unique viewers, video duration, video publish date, and video title.

🚧

In addition to your property key and reporting secret, you will need the property secret. The property secret is needed since this .php script makes an additional call to the Management API.

Use the following steps to query your data:

1. Download and unzip the jwdeveloper-platformdemos repo.
2. Open jwdeveloper-platformdemos-master/analytics-api-samples/php-samples/enriched-videos.php in a code editor or text editor.
3. Replace <yourkey with your property key.
4. Replace yoursecret with your reporting secret.
5. Replace yourtoken with your property secret.
6. Set the $queryStartDate to the first date of your query's date range, using YYYY-MM-DD format.
7. Set the $queryEndDate to the last date of your query's date range, using YYYY-MM-DD format.
8. (Optional) Change the value of $pageLen to increase or decrease the number of results returned.
9. (Optional) Update AMI- in the value for $outputFn to change the name prefix of the .csv file that is generated.
10. Save the file.
11. Open a command-line interface (CLI) and navigate to the folder containing enriched-videos.php.
12. At the CLI prompt, type: php enriched-videos.php.

After a few moments, status information appears in the CLI and a .csv file is created in the same folder as the enriched-videos.php file.

Python sample

Use the following steps to query your data:

1. Download and unzip the jwdeveloper-platformdemos repo.
2. Open jwdeveloper-platformdemos-master/analytics-api-samples/python-samples/analytics-example.py in a code editor or text editor.
3. Update the _REPORT_QUERY object with body params that are applicable for your request.
4. (Optional) Update value assigned to _REPORT_NAME to change the name of the .csv file that is generated.
5. Save the file.
6. Open a command-line interface (CLI) and navigate to the folder containing analytics-example.py.
7. At the CLI prompt, type: python analytics-example.py --site-id [site_id] --authorization [secret].

   📘

   Be sure to replace the [site_id] placeholder with the appropriate site_id and the [secret] placeholder with your secret.

After a few moments, status information appears in the CLI and a .csv file is created in the same folder as the analytics-example.php file.