Google Apps Reporting API

Notice
The Google Apps Reporting and Reporting Visualization APIs have been officially deprecated as of May 15, 2013. They have been replaced by the Admin SDK’s Reports API. In addition, the quota_in_mb field in the Reporting API has been deprecated and is now called the quota_in_mb_deprecated field. The Google Apps Reporting and Reporting Visualization APIs will continue to work as per our Deprecation Policy.

Google Apps Reporting Visualization API Guide

The Google Apps Reporting Visualization API lets you retrieve usage reports for your domain's hosted accounts and display them using a large selection of visualizations created by the developer community. Learn more about visualization gadgets and queries.

This document explains the different reports available through the reporting visualization API and defines the process for requesting reports from the API.

Contents

Audience

This document assumes you are already familiar with the Google Visualization API and visualization gadgets.

Add Visualization Gadgets to iGoogle

To include a visualization gadget on iGoogle:

  1. Go to an iGoogle page
  2. Click "Add Stuff"
  3. Click "Add feed or gadget"
  4. Enter the specification for one of the Google Visualization Gadgets eg. http://www.google.com/ig/modules/line-chart.xml
  5. Click "Add"
  6. Enter your data source URL eg. https://www.google.com/a/cpanel/{domain}/ReportGviz?reportKey={reportKey}&reportDate={reportDate}
  7. Click "Save"

You should see a chart of the report data.

Submitting Requests to the Reporting Visualization API

To retrieve a report from the API, set the data source URL on the visualization gadget to the visualization URL for your domain:

https://www.google.com/a/cpanel/{domain}/ReportGviz?reportKey={reportKey}&reportDate={reportDate}

Note: You must set {domain} to the value of your domain. You must also set the {reportKey} parameter to specify the report that you wish to retrieve.

URL Parameter Definitions

The following table defines the URL parameters used in a reporting visualization API request.

Parameter Definition Example
reportKey The key used to access the GViz report. You can get this key by visiting the Usage and Reports page for your domain. asdfa014mm129anpsmdasdas123
reportDate

Specifies the dates for which data should be included in the report. Data will be returned for all days prior to and including the requested day in the requested month and year.

You can specify dates in either the current month or the previous month.

Format: YYYY-MM-DD

This field is optional and if not specified by user, is set to latest available report date.

2008-08-31
tq The optional visualization query to specify data manipulation. select rdate,count_7d_actives where count_7d_actives > 100

Interpreting Responses to the Reporting Visualization API

The report response contains multiple columns that you may use in order to form your visualizations.

Report Field Definitions

Field Name Details
rdate

The rdate field specifies the day, month and year that correspond to the remaining data in a row of a report.


Type: Integer (YYYYMMDD)
num_accounts

The num_accounts field specifies the total number of user-accessible accounts in your domain. An account is considered user-accessible unless you have suspended access to the account or account access has been suspended due to abuse or complaints.

count_1d_actives

The count_1d_actives field identifies the number of hosted accounts in your domain that were active within the previous day.

An account that is counted in the count_1d_actives column will also be counted in the count_7d_actives, count_14d_actives and count_30d_actives columns.


Type: Integer
count_7d_actives

The count_7d_actives field identifies the number of hosted accounts in your domain that were active within the previous seven days.

An account that is counted in the count_7d_actives column will also be counted in the count_14d_actives and count_30d_actives columns and may also be counted in the count_1d_actives column, depending on the date the account was most recently accessed.


Type: Integer
count_14d_actives

The count_14d_actives field identifies the number of hosted accounts in your domain that were active within the previous 14 days.

An account that is counted in the count_14d_actives column will also be counted in the count_30d_actives column and may also be counted in the count_1d_actives and count_7d_actives columns, depending on the date the account was most recently accessed.


Type: Integer
count_30d_actives

The count_30d_actives field identifies the number of hosted accounts in your domain that were active within the previous thirty days.

An account that is counted in the count_30d_actives column may also be counted in the count_1d_actives and count_7d_actives and count_14d_actives columns, depending on the date the account was most recently accessed.


Type: Integer
count_30d_idle

The count_30d_idle field specifies the number of hosted accounts in your domain that have been idle for 30 to 59 days. An account is idle as long as there has been no user activity for the account.

count_60d_idle

The count_60d_idle field specifies the number of hosted accounts in your domain that have been idle for 60 to 89 days. An account is idle as long as there has been no user activity for the account.

count_90d_idle

The count_90d_idle field specifies the number of hosted accounts in your domain that have been idle for 90 days or more. An account is idle as long as there has been no user activity for the account.

usage_in_mb

The usage_in_mb field identifies the total amount of disk space, in megabytes, used by all active accounts in your domain.


Type: Integer
avg_usage_in_mb

The avg_usage_in_mb field contains the average amount of disk space, in megabytes, used by each of your hosted accounts.


Type: Integer
quota_in_mb

The quota_in_mb field indicates the total amount of disk space available for all of the hosted accounts in your domain.


Type: Integer
avg_quota_in_mb

The avg_quota_in_mb field contains the average amount of disk space, in megabytes, available for each of your hosted accounts.


Type: Integer

Error Handling

The reporting visualization API returns the following errors:

Error Error Message Resolution
access_denied Access denied The reporting visualization API has been disabled for your domain, or the reportKey is invalid.
invalid_request Report date is either too new or too old Set the value of the reportDate parameter to a valid report date.
invalid_request Report date is not in the correct format Set the value of the reportDate parameter in the format YYYY-MM-DD.
invalid_request Domain is required Set the value of the domain in the request URL to your domain.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.