Unsampled Reports Developer Guide

The Google Analytics Management API allows you to programmatically create 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 360 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.
  • Delete unsampled reports.

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 field to retrieve the file that contains the report data. For example:

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.

For example if your unsampled report is stored in Google Drive, you can make an authorized HTTP GET request to the file's resource URL and include the query parameter alt=media.

GET /drive/v2/files/XXXXXX?alt=media
Host: www.googleapis.com
Content-length: 0
Authorization: Bearer ya29.AHESVbXTUv5mHMo3RYfmS1YJonjzzdTOFZwvyOAUVhrs

Where XXXXXX is the unsampled report driveDownloadDetails.documentId

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.

Deleting Unsampled Reports

You can delete scheduled or completed unsampled reports, however calling delete during the brief period while the report is being generated will result in an error. Deleting unsampled reports only removes the resource from your GA view (profile), the exported data in Google Drive or Google Cloud Storage will remain.

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, for example, Google Ads Data.
  • Queries deemed as too expensive are not supported.
  • If you've created too many unsampled reports and reach the limit, you can safely delete the unsampled report resources, leaving the generated report data in Google Drive or Google Cloud intact.

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 as follows:

  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:

"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 Policy

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