Overview

The Bitmovin Analytics API allows you to export your raw dataset to a cloud storage bucket of your choice to enable custom Business Intelligence workflows or to do Data Warehousing.

Depending on the amount of data in your account exports can take multiple hours to finish. Thus exports are tracked as Export Tasks similar to Encoding Jobs in our API with corresponding APIs to fetch the status of an ongoing export.

An export task will generate one export file per hour on your target storage. Exporting a whole day will generate 24 files in your storage (each file containing the data of one hour) with a pattern of yyyy-MM-dd-HH-mm.csv.

Output formats supported for exports are either CSV files or Parquet files which can be controlled through the fileFormat parameter when starting an export.

Requirements

Bitmovin Analytics data exports support the following cloud storages as export targets: AWS S3, Google Cloud Storage and Microsoft Azure Blob Storage.

In order to export data to your storage you need to first create an output resource that securely stores the credentials in our system and can then be used as a target for subsequent exports.

• S3 Role-Based Output
• GCS Service Account Output
• Microsoft Azure Blob Storage Output

Create an Export Task

In order to export Analytics Data the following parameters are required at a minimum for the Create Analytics Export Task call to our API.

• name - A descriptive name for the export task
• startTime/endTime - It describes a datetime range that shall be exported
• licenseKey - The Analytics License that holds the data that shall be exported
• output - A configuration that holds the ID of an existing Analytics Output, and an output path the export shall be transferred to

Additional properties that are useful are fileFormat which can be set to PARQUET to cut down on file size through the use of the Apache Parquet file format (although generating parquet files also takes longer than just writing CSV files).

Track the status of an Export Task

Using the GetAnalyticsExportTasksById API allows you to retrieve status information about previously started export tasks and their progress.

An Export Task can have 4 different states:

• QUEUED - Your Export Task was created successfully, and is waiting for a free slot to be processed
• STARTED - Your Export Task is in progress. Please see the progress which indicates the current progress in percent.
• FINISHED - Your Export Task has finished and was transferred successfully
• ERROR - We were probably unable to transfer the export to your storage. Please see the respective setup tutorial of the output for more details. If you come to the conclusion that it should work as expected please reach out to our support team.

Important: Make sure you are running the following commands in the appropriate Organization if you have been invited into a Multi-Tenant Organization. Your personal API Key will by default only operatore within your own user's organization and not in the organization you have been invited to. You can pass the X-Tenant-Org-Id HTTP Header or use the withTenantOrgId() SDK-API to indicate which Organization your API call is targeting (see Using an API SDK with different Organisations).

Examples

Create an Analytics Export Task

curl -X POST \
  https://api.bitmovin.com/v1/analytics/exports/ \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: <YOUR_BITMOVIN_API_KEY>' \
  -d '{
    "startTime": "2019-09-01T12:00:00.000Z",
    "endTime": "2018-09-30T12:00:00.000Z", 
    "name": "Your first Analytics Export Task",
    "licenseKey": "<YOUR_ANALYTICS_LICENSE_KEY>",
    "output": {
        "outputPath": "path/to/your/desired/destination-on-your-bucket/", 
        "outputId": "<YOUR_OUTPUT_ID>" // the output ID you already created
    }
}'

// This example uses our latest Open API client for Java
// which is available on Github at https://github.com/bitmovin/bitmovin-api-sdk-java
bitmovinApi = BitmovinApi.builder().withApiKey("YOUR_BITMOVIN_API_KEY").build();

ZonedDateTime startDateTime = ZonedDateTime.parse("2019-09-01T12:00:00Z");
ZonedDateTime endDateTime = ZonedDateTime.parse("2019-09-30T12:00:00Z");

AnalyticsExportTaskOutputTarget analyticsExportOutputConfiguration =
    new AnalyticsExportTaskOutputTarget();
analyticsExportOutputConfiguration.setOutputId("<YOUR_OUTPUT_ID>");
analyticsExportOutputConfiguration.setOutputPath(
    "path/to/your/desired/destination-on-your-bucket/");

AnalyticsExportTask analyticsExportTask = new AnalyticsExportTask();
analyticsExportTask.setName("Example Analytics Export");
analyticsExportTask.setLicenseKey("<YOUR_ANALYTICS_LICENSE_KEY>");
analyticsExportTask.setOutput(analyticsExportOutputConfiguration);
analyticsExportTask.setStartTime(Date.from(startDateTime.toInstant()));
analyticsExportTask.setEndTime(Date.from(endDateTime.toInstant()));

analyticsExportTask = bitmovinApi.analytics.exports.create(analyticsExportTask);

Get Details of an existing Analytics Export Task

curl https://api.bitmovin.com/v1/analytics/exports/YOUR_ANALYTICS_EXPORT_TASK_ID \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: <YOUR_BITMOVIN_API_KEY>' \

bitmovinApi = BitmovinApi.builder().withApiKey("<YOUR_BITMOVIN_API_KEY>").build();

AnalyticsExportTask analyticsExportTask = bitmovinApi.analytics.exports.get("<YOUR_ANALYTICS_EXPORT_TASK_ID>");

Limiting the amount of Data exported

By default we will export all available data to your storage for you to analyze and process. But depending on the size of your account this can easily range in the hundreds of Gigabytes per day so storage, transfer and processing costs might become prohibitive.

If you are only interested in certain columns to power your analysis you can choose what columns to export during the Create Export Task call (POST /v1/analytics/exports/) via a string-array property called columns

If for example you want to export only the played duration and impression_id columns you can do that by specifying: "columns": ["PLAYED", "IMPRESSION_ID"].

The exact format is documented in our OpenAPI spec and available via our generated OpenAPI Clients.