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:
- Go to an iGoogle page
- Click "Add Stuff"
- Click "Add feed or gadget"
- Enter the specification for one of the Google Visualization Gadgets eg. http://www.google.com/ig/modules/line-chart.xml
- Click "Add"
- Enter your data source URL eg. https://www.google.com/a/cpanel/{domain}/ReportGviz?reportKey={reportKey}&reportDate={reportDate}
- 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_7_day_actives where count_7_day_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_1_day_actives |
The count_1_day_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_1_day_actives column will also be counted in the count_7_day_actives, count_14_day_actives and count_30_day_actives columns.
Type: Integer
|
| count_7_day_actives |
The count_7_day_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_7_day_actives column will also be counted in the count_14_day_actives and count_30_day_actives columns and may also be counted in the count_1_day_actives column, depending on the date the account was most recently accessed.
Type: Integer
|
| count_14_day_actives |
The count_14_day_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_14_day_actives column will also be counted in the count_30_day_actives column and may also be counted in the count_1_day_actives and count_7_day_actives columns, depending on the date the account was most recently accessed.
Type: Integer
|
| count_30_day_actives |
The count_30_day_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_30_day_actives column may also be counted in the count_1_day_actives and count_7_day_actives and count_14_day_actives columns, depending on the date the account was most recently accessed.
Type: Integer
|
| count_30_day_idle |
The count_30_day_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_60_day_idle |
The count_60_day_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_90_day_idle |
The count_90_day_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 requested is not supported with visualization API |
Set the value of the reportName parameter to one of the available reports. |
| invalid_request |
Report requested does not exist |
Set the value of the reportName parameter to one of the available reports. |
| 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. |
|
