Hide

Management API - Unsampled Reports Developer Guide

This document explains how to use the Management API to manage Unsampled Reports.

Introduction

Unsampled reports are Google Analytics reports that have been generated using unsampled data. Unsampled reports are currently only available to Google Analytics Premium users.

With this API, you can:

  • retrieve configuration information about all your existing unsampled reports.
  • create one-time unsampled reports.
  • check processing status of unsampled reports.
  • get a link to the data file for an unsampled report once processing is complete.

Before You Begin

This guide demonstrates how to access the Google Analytics API using the following programming languages:
  • Java
  • Python
  • PHP

  • Read the client libraries page for a complete list of programming language specific client libraries that work with the Management API.
  • Read the Reference Guide to access the API without a client library

Each client library provides a single Analytics service object to access all Management API data. To create the service object you generally have to go through the following steps:

  1. Register your application in the Google Developers Console.
  2. Authorize access to Google Analytics data.
  3. Create an Analytics service object.

If you haven't completed these steps, please stop and read the Hello Google Analytics API Tutorial. This tutorial will walk you through the initial steps of building a Google Analytics API application. Once complete, you will be able to use this guide to perform real-world tasks.

The following code snippet continues from step 3: Create an Analytics service object and contains a variable to store an authorized service object.

Java

Analytics analytics = // Read Hello Analytics Tutorial for details.

Python

analytics = # Read Hello Analytics Tutorial for details.

PHP

$client = // Read Hello Analytics Tutorial for details.

// Return results as objects.
$client->setUseObjects(true);

$analytics = new apiAnalyticsService($client);

The PHP library will return all the API results as an associative array. To return real objects instead, you can call the client useObject method as demonstrated in the example above.

Once you create an Analytics service object, you are ready to make requests to the Management API.

Note: The same Analytics service object can also be used to access the Core Reporting API.

Retrieving Data for Unsampled Reports

When you create an unsampled report it can take some time before the report is available to download. The status field for an unsampled report indicates whether the processing for that report is complete. Once the status is marked as COMPLETED, you can use the downloadType and the corresponding download details (i.e., cloudStorageDownloadDetails or driveDownloadDetails) field to retrieve the file that contains the report data.

We recommend that you do not use continuous, high-rate, polling to check for the status of these reports, as you are likely to run out of your daily quota fairly quickly. You should have a time delay between requests when checking for the status of unsampled reports.

Using Google Drive / Google Cloud Storage API

Depending on where your files are being delivered (Google Drive or Google Cloud Storage), you will get a corresponding link for that file. You can use Drive API or Cloud Storage API to download the file using this link. For more details on how to retrieve the file, see Google Drive API or Google Cloud Storage API documentation.

Authentication

If you are planning to use Unsampled Report in conjunction with Drive or Cloud Storage APIs for file downloads, you need to include the corresponding auth scope for that API (in addition to the Analytics API auth scope) while requesting an OAuth 2.0 token. This will allow you to use the same auth token for both the APIs.

Restrictions

The following restrictions apply to creating unsampled reports.

  • You can only specify up to 4 dimensions.
  • Some types of reporting data are not supported, E.g., AdWords Data
  • Queries deemed as too expensive are not supported.

If your request is determined to be too expensive, the create operation will return an error with an appropriate message. If this happens you can:

  • Request fewer dimensions.
  • Split the query into multiple queries with smaller date ranges and stitch together the resulting reports.

Use Cases

Unsampled Reports and the Core Reporting API

If you use the Core Reporting API to retrieve report data and it contains sampled data then you could create an unsampled report for the same query.

The workflow for this use case is:

  1. Make a Core Reporting API request.
  2. In the response, check the containsSampledData property to see if the data is sampled.
  3. If this property is set to true, you can use query and profileInfo fields from the same response to create a request for an unsampled report.

Sample query field from Core Reporting API response:

"query": {
 "start-date": "2011-01-01",
 "end-date": "2011-01-31",
 "ids": "ga:1234",
 "dimensions": "ga:browser",
 "metrics": [
  "ga:visits"
 ],
 "filters": "ga:country==US",
 "start-index": 1,
 "max-results": 1000
}

Sample profileInfo field from Core Reporting API response:

Java


"profileInfo": {
 "profileId": "1234",
 "accountId": "12345",
 "webPropertyId": "UA-12345-1",
 "internalWebPropertyId": "11254",
 "profileName": "Name of the profile",
 "tableId": "ga:1234"
}

The following is an example of how to create an unsampled report from a Core Reporting API response:

Java


// Make a Core Reporting API call.
GaData reportingApiData = v3.data().ga().get(...).execute();

// Check if the response is sampled.
if (reportingApiData.getContainsSampledData()) {

  // Use the “query” object to construct an unsampled report object.
  Query query = reportingApiData.getQuery();
  UnsampledReport report = new UnsampledReport()
      .setDimensions(query.getDimensions())
      .setMetrics(Joiner.on(',').join(query.getMetrics()))
      .setStartDate(startDate)
      .setEndDate(endDate)
      .setSegment(query.getSegment())
      .setFilters(query.getFilters())
      .setTitle(“My unsampled report”);

  // Use “profileInfo” to create an InsertRequest for creating an
  // unsampled report.
  ProfileInfo profileInfo = reportingApiData.getProfileInfo();
  Insert insertRequest = analytics.management().unsampledReports()
  .insert(profileInfo.getAccountId(),
          profileInfo.getWebPropertyId(),
          profileInfo.getProfileId(),
          report);
  UnsampledReport createdReport = insertRequest.execute();
}

Stitching Unsampled Data for Multiple Days

You can combine or stitch reports for multiple days to get unsampled data over a particular date range. This is useful when an unsampled data request is too large. In such cases, you can split the request into multiple requests with a shorter date range and then combine the results.

Quota Policies

See the Configuration and Reporting API Limits and Quotas for the complete list of limits and quotas that apply when creating unsampled reports.

Code Examples

The Unsampled Reports resource allows you to list, get, and insert, unsampled reports for an authorized user. To use any of these methods, you first need to create an Analytics service object, as described in the Before You Begin section.

For code examples that show you how to work with the Unsampled Report resource, visit the following method references:

  • list — Lists unsampled reports to which the user has access.
  • get — Gets a unsampled report to which the user has access.
  • insert — Create a new unsampled report.