Overview
While it's the easiest way to leverage the Bitmovin Analytics API using our API clients, you can also export the raw analytics data to your own cloud storage and process that data in your own custom way.
The export itself is handled as task and takes some time to process, depending on how much data needs to be exported. Therefore, please see below how you can create an export task and how you can track its progress.
Requirements
Bitmovin Analytics data exports support the following cloud storages which have their individual requirements:
Workflow
- Create an Export Task - In order to export Analytics Data the following parameters are required
- 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
- Track the status of your Export Task - 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
property 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
).
(Java) Analytics Export Task Example
This example uses our latest Open API client for Java, which is available on Github.
Create an Analytics Export Task
1bitmovinApi = BitmovinApi.builder().withApiKey("YOUR_BITMOVIN_API_KEY").build();23ZonedDateTime startDateTime = ZonedDateTime.parse("2019-09-01T12:00:00Z");4ZonedDateTime endDateTime = ZonedDateTime.parse("2019-09-30T12:00:00Z");56AnalyticsExportTaskOutputTarget analyticsExportOutputConfiguration =7 new AnalyticsExportTaskOutputTarget();8analyticsExportOutputConfiguration.setOutputId("<YOUR_OUTPUT_ID>");9analyticsExportOutputConfiguration.setOutputPath(10 "path/to/your/desired/destination-on-your-bucket/");1112AnalyticsExportTask analyticsExportTask = new AnalyticsExportTask();13analyticsExportTask.setName("Example Analytics Export");14analyticsExportTask.setLicenseKey("<YOUR_ANALYTICS_LICENSE_KEY>");15analyticsExportTask.setOutput(analyticsExportOutputConfiguration);16analyticsExportTask.setStartTime(Date.from(startDateTime.toInstant()));17analyticsExportTask.setEndTime(Date.from(endDateTime.toInstant()));1819analyticsExportTask = bitmovinApi.analytics.exports.create(analyticsExportTask);
Get Details of an existing Analytics Export Task
1bitmovinApi = BitmovinApi.builder().withApiKey("<YOUR_BITMOVIN_API_KEY>").build();23AnalyticsExportTask analyticsExportTask = bitmovinApi.analytics.exports.get("<YOUR_ANALYTICS_EXPORT_TASK_ID>");
(CURL) Analytics Export Task Example
Create an Analytics Export Task
API Reference: Create Export Task
1curl -X POST \2 https://api.bitmovin.com/v1/analytics/exports/ \3 -H 'Content-Type: application/json' \4 -H 'X-Api-Key: <YOUR_BITMOVIN_API_KEY>' \5 -d '{6 "startTime": "2019-09-01T12:00:00.000Z",7 "endTime": "2018-09-30T12:00:00.000Z",8 "name": "Your first Analytics Export Task",9 "licenseKey": "<YOUR_ANALYTICS_LICENSE_KEY>",10 "output": {11 "outputPath": "path/to/your/desired/destination-on-your-bucket/",12 "outputId": "<YOUR_OUTPUT_ID>" // the output ID you already created13 }14}'
Get Details of an existing Analytics Export Task
API Reference: Get Export Task
1curl https://api.bitmovin.com/v1/analytics/exports/YOUR_ANALYTICS_EXPORT_TASK_ID \2 -H 'Content-Type: application/json' \3 -H 'X-Api-Key: <YOUR_BITMOVIN_API_KEY>' \
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.