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 API

The Google Apps Reporting API lets you retrieve usage reports for your domain's hosted accounts. To retrieve a report, you send an HTTP POST request to Google. The body of the request is an XML document that identifies your domain and specifies the report being requested.

This document defines the process for requesting reports from the reporting API. The XML Element Definitions section then defines each of the elements in the XML document that you will post to Google.

The document proceeds to explain the different reports available through the API. The document contains a subsection explaining each of these reports. Each subsection provides a sample XML document for requesting the report, a sample comma-separated report and definitions for each of the fields in the report.

The API applies to Google Apps for Business, Education, Government, Reseller, and ISP accounts.



Submitting Requests to the Reporting API

To retrieve a report from the API, you need to POST an appropriately formatted XML document to the following URL:

https://www.google.com/hosted/services/v1.0/reports/ReportingData

All requests have the following Content-type header:

Content-type: application/atom+xml; charset=UTF-8

The XML document that you will send to Google has the following format:

<?xml version="1.0" encoding="UTF-8"?>
<rest xmlns="google:accounts:rest:protocol"
    xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance ">
        <type>Report</type>
    <domain>example.com</domain>
        <token>DQAAAMABAACAMWe3w_hG9U</token>
    <date>2006-08-01</date>
        <page>1</page>
        <reportType>daily</reportType>
        <reportName>accounts</reportName>
</rest>

The data will then be returned in CSV format in response to your request. The following section, XML Element Definitions, contains complete definitions for all of the XML tags used in the request.

Google Apps Reseller Requests

For a reseller to retrieve a report, send an HTTP POST request to the ReportingData feed's URI. The body of the request is an XML document that identifies your customer's domain and specifies the report being requested.

To retrieve a reseller's report from the API, you need to POST an appropriately formatted XML document to the following URL:

https://www.google.com/hosted/services/v1.0/reports/ReportingData

All requests have the following Content-type header:

Content-type: application/atom+xml; charset=UTF-8

The XML document that you send to Google has the following format. This example is requesting an Accounts report:

<?xml version="1.0" encoding="UTF-8"?>
<rest xmlns="google:accounts:rest:protocol"
        xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance ">
        <type>Report</type>
    <domain>example_customer.com</domain>
        <date>2010-08-01</date>
        <page>1</page>
        <reportType>daily</reportType>
    <reportName>accounts</reportName>
    </rest>

XML Element Definitions

The following tables define the XML tags used in a reporting API request. The tags are listed in the order that they appear in an API request.

rest
Definition The root tag in a reporting API request.
Example xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
Subtags type, token, domain, date, page, reportType, reportName
Content Format Text
type
Definition Identifies the type of request that you are submitting. The only valid value for this tag is Report.
Example Report
Subtag of rest
Content Format Text
token
**Definition Identifies the ClientLogin token used for authentication.
Subtag of rest
Content Format Text
domain
Definition Identifies the Google partner domain for a hosted account, email alias or mailing list.
Example example.com
Subtag of rest
Content Format Text
date
Definition Specifier the dates for which data should be included in a Google Apps report. The tag's value has a different effect on requests for different reports.

Note: As discussed in the Error Handling section – see the ReportNotAvailableForGivenDate(1059) error – reports for a particular day are not available until 12 p.m. Pacific time the following day. For example, reports for June 10, 2006, would not be available until 12 p.m. Pacific time on June 11, 2006.

* If you request an Accounts report, Google will return data for the date specified in the <date> tag.

For these three reports, the value of the <date> tag must fall within the 30-day window that ends the day prior to the day that you request the report. (If your request occurs before 12 p.m. Pacific time, the date must fall within a 29-day window ending two days prior to the day you request the report.)

For example, if you request one of these reports on October 31, 2007 after 12 p.m. Pacific time, you could specify any date between October 1, 2007, and October 30, 2007. However, if your request occurs before 12 p.m. Pacific time, you could specify any date between October 1, 2007, and October 29, 2007. Similarly, if you request the report on December 15, 2007 after 12 p.m. Pacific time, you could specify any date between November 15, 2007, and December 14, 2007. However, if your request occurs before 12 p.m. Pacific time, you could specify dates between November 15, 2007, and December 13, 2007.

* If you request an Activity, Disk Space, Email Client or Summary report, Google will return data for all days prior to and including the requested day in the requested month and year. For example, if you request data for October 10, 2006, your report would include data for October 1, 2006, through October 10, 2006.

When requesting these reports, you can specify dates in either the current month or the previous month.

Example |2006-10-14 Subtag of| rest Content Format| Text

page
Definition Retrieves a particular page for account detail reports (i.e. accounts). You should use the page parameter for these reports if your domain has a large number of accounts. For domains with more than 100,000 accounts, these reports will only be available using paging. The Reporting API returns a report consisting of "End-Of-Report" when you've reached the end of the report.
The page parameter is optional and is ignored if used for non-account detail reports (i.e. activity, disk_space, email_clients, and summary).
Example 1
Subtag of rest
Content Format Text
reportType
Definition Combined with the reportName value to identify the report being retrieved.
The only valid value for the <reportType> tag is daily.
Example daily
Subtag of rest
Content Format Text
reportName
Definition Identifies the report being retrieved. This tag may contain any of the following values:
* accounts
* activity
* disk_space
* email_clients
* summary
Example disk_space
Subtag of rest
Content Format Text

Reports

Google Apps reports enable you to monitor the usage of hosted accounts for your domain. The following list identifies the different reports.

Accounts Report

Activity Report

Disk Space Report

Email Clients Report

Summary Report

Accounts Report

The accounts report contains a list of all of the hosted accounts that exist in your domain on a particular day. The report includes both active accounts and suspended accounts. The status column will indicate whether each account is active or suspended.

Sample XML Request

To retrieve this report, set the value of the <reportName> tag to accounts. The following XML shows a sample request for an Accounts report:

<?xml version="1.0" encoding="UTF-8"?>
    <rest xmlns="google:accounts:rest:protocol"
        xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance ">
        <type>Report</type>
        <domain>example_customer.com</domain>
        <date>2010-08-01</date>
        <page>1</page>
        <reportType>daily</reportType>
        <reportName>accounts</reportName>
    </rest>

Sample Report Data

date, account_id, account_name, status, quota_in_mb_deprecated,
        usage_in_bytes, primary_account_id, primary_account_name, creation_date,
        last_login_date, last_web_mail_date, surname, given_name,
        service_tier, channel, suspension_reason, last_pop_date, creation_time,
        last_login_time, last_web_mail_time, last_pop_time<br/>
20060808, 000000aaaaa11111, "abuse@example.com", "ACTIVE", 10240,
        9235, , , 20060802, 19691231, 20060802, , "Abuse", 0, , , 20060802,
        2006-08-02 17:22:15, 1969-12-31 16:00:00, 2006-08-02 17:22:15, 2006-08-02
        16:00:00<br/>
20060808, 000000bbbbb22222, "admin@example.com", "ACTIVE", 2048,
         2593, , , 20060721, 20060804, 20060807, , "Admin", 0, , , 20060807,
    2006-07-21 09:15:22, 2006-08-04 08:30:45, 2006-08-07 12:30:32, 2006-08-07
        16:00:00<br/>
20060808, 000000ccccc33333, "bart@example.com", "SUSPENDED", 2048,
        29057823, , , 20060801, 20060808, 20060807,
        "Simpson", "Bart", , , "Suspended for abuse", 20060807, 2006-08-01 13:15:29,
    2006-08-08, 2006-08-08 15:12:43, 2006-08-07 19:43:12, 2006-08-07 12:29:17<br/>
20060808, 000000ddddd4444, "homer@example.com", "SUSPENDED", 2048,
        3072, , , 20060803, 20060808, 20060807,
    "Simpson", "Homer", , , "Disabled by operator", 20060807, 2006-08-03
        07:14:27, 2006-08-08 12:32:45, 2006-08-07 05:35:25, 2006-08-07 16:00:00

Field Definitions for the Accounts Report

The following table lists the fields in the accounts report.

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

Type: Integer (yyyyMMdd)
account_id The account_id field contains an ID that uniquely identifies a hosted account. Google will assign an account ID to each hosted account that you create, and this ID will not change for the life of the account.

Type: 16-character hexadecimal string
account_name The account_name field contains the email address of the user, including a username and your domain name – e.g. admin@example.com.

Type: String
status The status field indicates whether an account is active or suspended. Valid values for this field are ACTIVE, SUSPENDED, SUSPENDED_BY_ADMIN, and SUSPENDED_FOR_ABUSE.

Type: String
quota_in_mb_deprecated The quota_in_mb field has been deprecated. The quota_in_mb_deprecated field is returned instead. The field indicates the total amount of disk space available for all of the hosted accounts in your domain.

Type: Integer
usage_in_bytes The usage_in_bytes field specifies the total amount of disk space, in bytes, used by all accounts, including suspended accounts, active accounts in your domain.

Type: Integer
primary_account_id The primary_account_id field will contain a value if the specified account is a subsidiary account. In that case, this field will contain the account ID that identifies the parent account of the subsidiary account. Otherwise, this field will be left blank.
Currently, all hosted accounts are primary accounts. As such, this field will always be left blank.

Type: Hexadecimal String
primary_account_name The primary_account_name field will contain a value if the specified account is a subsidiary account. In that case, this field will contain the account name for the parent account of the subsidiary account. Otherwise, this field will be left blank.
Currently, all hosted accounts are primary accounts. As such, this field will always be left blank.

Type: String
creation_date The creation_date field specifies the date that the account was created.

Type: Integer (yyyyMMdd)
last_login_date The last_login_date field specifies the most recent date that the account owner logged into the specified account.

Type: Integer (yyyyMMdd)
last_web_mail_date The last_web_mail_date field specifies the most recent date that email for an account was accessed using WebMail.

Type: Integer (yyyyMMdd)
surname The surname field contains the last name of the user who owns the account.

Type: String
given_name The given_name field contains the first name of the user who owns the account.

Type: String
service_tier The service_tier field is reserved for future use. Currently, this field will contain an empty value.

Type: String
channel The channel field is a blank field that is reserved for future use.

Type: String
suspension_reason The suspension_reason field identifies the reason that an account was suspended.

Type: String
last_pop_date The last_pop_date field specifies the most recent date that email for an account was accessed using POP.

Type: Integer (yyyyMMdd)
creation_time The creation_time field specifies the date and time that the account was created.

Type: String (yyyy-MM-dd HH:mm:ss)
last_login_time The last_login_time field specifies the most recent date and time that the account owner logged into the specified account.

Type: String (yyyy-MM-dd HH:mm:ss)
last_web_mail_time The last_web_mail_time field specifies the most recent date and time that email for an account was accessed using WebMail.

Type: String (yyyy-MM-dd HH:mm:ss)
last_pop_time The last_pop_time field specifies the most recent date that and time email for an account was accessed using POP.

Type: String (yyyy-MM-dd HH:mm:ss)

Activity Report

The activity report identifies the total number of accounts in your domain as well as the number of active and idle accounts over several different time periods. In this report, activity encompasses user interaction with his email, such as reading or sending email. The activity statistics includes web mail as well as POP activity.

Sample XML Request

To retrieve this report, set the value of the <reportName> tag to activity. The following XML shows a sample request for an Activity report:

<?xml version="1.0" encoding="UTF-8"?>
    <rest xmlns="google:accounts:rest:protocol"
        xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance ">
        <type>Report</type>
        <domain>example.com</domain>
        <date>2010-08-01</date>
        <reportType>daily</reportType>
        <reportName>activity</reportName>
    </rest>

Sample Report Data

date,num_accounts,count_1_day_actives,count_7_day_actives,count_14_day_actives,
        count_30_day_actives,count_30_day_idle,count_60_day_idle,count_90_day_idle

20060801,46,34,38,41,44,2,1,0
20060802,75,61,64,69,73,2,1,0
20060803,78,65,68,73,76,2,1,1
20060804,82,68,72,77,80,2,1,1

Field Definitions for the Activity Report

The following table lists the fields in the activity report.

Field Name Details
date The date 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.

Disk Space Report

The disk_space report shows the amount of disk space occupied by users' mailboxes. The report identifies the total number of accounts in your domain as well as the number of accounts that fall into several different size groupings. Mailboxes that occupy less than 1GB of disk space are grouped in increments of 100MB, and mailboxes that occupy between 1GB and 10GB of disk space are grouped in increments of 500MB.

Sample XML Request

To retrieve this report, set the value of the <reportName> tag to disk_space. The following XML shows a sample request for a Disk Space report:

<?xml version="1.0" encoding="UTF-8"?>
    <rest xmlns="google:accounts:rest:protocol"
        xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance ">
        <type>Report</type>
        <domain>example.com</domain>
        <date>2010-08-01</date>
        <reportType>daily</reportType>
        <reportName>disk_space</reportName>
    </rest>

Sample Report Data

date,num_accounts,usage_in_bytes,avg_usage_in_mb,quota_in_mb_deprecated,avg_quota_in_mb,
    size_0.1gb,size_0.2gb,size_0.3gb,size_0.4gb,size_0.5gb,size_0.6gb,
        size_0.7gb,size_0.8gb,size_0.9gb,size_1.0gb,size_1.5gb,size_2.0gb,
        size_2.5gb,size_3.0gb,size_3.5gb,size_4.0gb,size_4.5gb,size_5.0gb,
        size_5.5gb,size_6.0gb,size_6.5gb,size_7.0gb,size_7.5gb,size_8.0gb,
        size_8.5gb,size_9.0gb,size_9.5gb,size_10.0gb

20060801,46,1,0,274432,5965,46,0,0,0,0,0,0,0,0,
        0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0

20060802,75,1,0,555008,7400,75,0,0,0,0,0,0,0,0,
        0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0

20060803,78,3,0,569344,7299,78,0,0,0,0,0,0,0,0,
        0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0

20060804,82,3,0,585728,7143,82,0,0,0,0,0,0,0,0,
        0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0

Field Definitions for the Disk Space Report

The following table lists the fields in the disk_space report.

Field Name Details
date The date 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.
usage_in_bytes The usage_in_bytes field identifies the total amount of disk space, in bytes, 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_deprecated The quota_in_mb field has been deprecated. The quota_in_mb_deprecated field is returned instead. The 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
size_0.1gb The size_0.1gb field specifies the number of mailboxes using between 0.0 GB and 0.1 GB of disk space.

Type: String
size_0.2gb The size_0.2gb field specifies the number of mailboxes using between 0.1 GB and 0.2 GB of disk space.

Type: String
size_0.3gb The size_0.3gb field specifies the number of mailboxes using between 0.2 GB and 0.3 GB of disk space.

Type: String
size_0.4gb The size_0.4gb field specifies the number of mailboxes using between 0.3 GB and 0.4 GB of disk space.

Type: String
size_0.5gb The size_0.5gb field specifies the number of mailboxes using between 0.4 GB and 0.5 GB of disk space.

Type: String
size_0.6gb The size_0.6gb field specifies the number of mailboxes using between 0.5 GB and 0.6 GB of disk space.

Type: String
size_0.7gb The size_0.7gb field specifies the number of mailboxes using between 0.6 GB and 0.7 GB of disk space.

Type: String
size_0.8gb The size_0.8gb field specifies the number of mailboxes using between 0.7 GB and 0.8 GB of disk space.

Type: String
size_0.9gb The size_0.9gb field specifies the number of mailboxes using between 0.8 GB and 0.9 GB of disk space.

Type: String
size_1.0gb The size_1.0gb field specifies the number of mailboxes using between 0.9 GB and 1 GB of disk space.

Type: String
size_1.5gb The size_1.5gb field specifies the number of mailboxes using between 1 GB and 1.5 GB of disk space.

Type: String
size_2.0gb The size_2.0gb field specifies the number of mailboxes using between 1.5 GB and 2 GB of disk space.

Type: String
size_2.5gb The size_2.5gb field specifies the number of mailboxes using between 2 GB and 2.5 GB of disk space.

Type: String
size_3.0gb The size_3.0gb field specifies the number of mailboxes using between 2.5 GB and 3 GB of disk space.

Type: String
size_3.5gb The size_3.5gb field specifies the number of mailboxes using between 3 GB and 3.5 GB of disk space.

Type: String
size_4.0gb The size_4.0gb field specifies the number of mailboxes using between 3.5 GB and 4 GB of disk space.

Type: String
size_4.5gb The size_4.5gb field specifies the number of mailboxes using between 4 GB and 4.5 GB of disk space.

Type: String
size_5.0gb The size_5.0gb field specifies the number of mailboxes using between 4.5 GB and 5 GB of disk space.

Type: String
size_5.5gb The size_5.5gb field specifies the number of mailboxes using between 5 GB and 5.5 GB of disk space.

Type: String
size_6.0gb The size_6.0gb field specifies the number of mailboxes using between 5.5 GB and 6 GB of disk space.

Type: String
size_6.5gb The size_6.5gb field specifies the number of mailboxes using between 6 GB and 6.5 GB of disk space.

Type: String
size_7.0gb The size_7.0gb field specifies the number of mailboxes using between 6.5 GB and 7 GB of disk space.

Type: String
size_7.5gb The size_7.5gb field specifies the number of mailboxes using between 7 GB and 7.5 GB of disk space.

Type: String
size_8.0gb The size_8.0gb field specifies the number of mailboxes using between 7.5 GB and 8 GB of disk space.

Type: String
size_8.5gb The size_8.5gb field specifies the number of mailboxes using between 8 GB and 8.5 GB of disk space.

Type: String
size_9.0gb The size_9.0gb field specifies the number of mailboxes using between 8.5 GB and 9 GB of disk space.

Type: String
size_9.5gb The size_9.5gb field specifies the number of mailboxes using between 9.5 GB and 10 GB of disk space.

Type: String
size_10.0gb The size_10.0gb field specifies the number of mailboxes using between 9.5 GB and 10 GB of disk space.

Type: String

Email Clients Report

The email_clients report explains how users in your domain access their hosted accounts on a day-by-day basis. For each day, the report lists the total number of accounts in your domain as well as the number and percentage of users who accessed their accounts using WebMail. This report does not include suspended accounts in the account total.

Sample XML Request

To retrieve this report, set the value of the <reportName> tag to email_clients. The following XML shows a sample request for an Email Clients report:

<?xml version="1.0" encoding="UTF-8"?>
    <rest xmlns="google:accounts:rest:protocol"
        xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance ">
        <type>Report</type>
        <domain>example.com</domain>
        <date>2010-08-01</date>
        <reportType>daily</reportType>
        <reportName>email_clients</reportName>
    </rest>

Sample Report Data

date,num_accounts,web_mail_count,num_accounts_accessed,pop_count
20060801,46,8,12,4
20060802,75,39,41,2
20060803,78,13,18,9
20060804,82,15,15,0

Field Definitions for the Email Clients Report

The following table lists the fields in the email_clients report.

Field Name Details
date The date 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.
web_mail_count The web_mail_count field indicates how many users in your domain used WebMail to access their email on a particular day.

Type: Integer
num_accounts_accessed The num_accounts_accessed field indicates how many users accessed their accounts using Webmail or POP on a particular day. An account accessed using both is counted only once.

Type: Integer
pop_count The pop_count field indicates how many users in your domain used POP to access their email on a particular day.

Type: Integer

Summary Report

The summary report contains the total number of accounts, total mailbox usage in bytes and total mailbox quota in megabytes for your domain. Each row in the report contains data for one day. This report does not include information for suspended accounts.

Sample XML Request

To retrieve this report, set the value of the <reportName> tag to summary. The following XML shows a sample request for a Summary report:

<?xml version="1.0" encoding="UTF-8"?>
    <rest xmlns="google:accounts:rest:protocol"
        xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance ">
        <type>Report</type>
        <domain>example.com</domain>
        <date>2010-08-01</date>
        <reportType>daily</reportType>
        <reportName>summary</reportName>
    </rest>

Sample Report Data

date,num_accounts,usage_in_bytes,quota_in_mb_deprecated
20060801,46,1308091,274432
20060802,75,2090993,555008
20060803,78,3425876,569344
20060804,82,3952475,585728

Field Definitions for the Summary Report

The following table lists the fields in the summary report.

Field Name Details
date The date 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.
usage_in_bytes The usage_in_bytes field specifies the total amount of disk space, in bytes, used by all in your domain.

Type: Integer
quota_in_mb_deprecated The quota_in_mb field has been deprecated. The quota_in_mb_deprecated field is returned instead. The field indicates the total amount of disk space available for all of the hosted accounts in your domain.

Type: Integer

Error Handling

The reporting API returns a report containing comma-separated values in response to a valid API request. However, the API returns an XML response in return to an invalid API request. The example below demonstrates the XML error response's format:

<?xml version="1.0" encoding="UTF-8"?>
<hs:rest xmlns:hs="google:accounts:rest:protocol">
        <hs:status>Failure(2001)</hs:status>
        <hs:reason>ReportNotAvailableForGivenDate(1059)</hs:reason>
        <hs:extendedMessage></hs:extendedMessage>
        <hs:result></hs:result>
    <hs:type></hs:type>
</hs:rest>

The tag in the XML response identifies the type of error that caused the HTTP request to fail. The following list identifies the possible values for the tag and explains the associated error.

  • Unknown(1000) - This error indicates that the HTTP request failed for an unknown reason. If you receive this error, please reissue your request. If the error occurs again, please contact Google support.

  • TypeUnsupported(1001) - This error indicates that the HTTP request failed because the value of the <type> tag in your HTTP request was invalid. The value of the <type> tag must be Report for a reporting API request.

  • MalformedRequest(1004) - This error indicates that the HTTP request did not contain properly formed XML or that the HTTP request specified an invalid date. (For example, you would receive this error if you specified a date like February 29 in a non-leap year.)

  • RequiredFieldsMissing(1005) - This error indicates that the HTTP request does not contain a required data field. This error will occur if you request a daily report but do not specify a date in the HTTP request. Similarly, this error will occur if another required field is missing in the HTTP request.

  • AuthenticationFailure(1006) - This error indicates that Google is unable to verify that you are authorized to receive the requested data. You will receive this error if the ClientLogin authentication token specified in your request has expired. Please note that ClientLogin authentication tokens expire after 24 hours. If you feel you have received this response in error, please contact Google support. Note:The ClientLogin authentication has been officially deprecated. For OAuth information, see Authorize Requests.

  • DomainDoesNotExist(1007) - This error indicates that the domain specified in the HTTP request is not registered to use Google Apps. Please confirm that your domain is registered and that you have entered the correct domain in your HTTP request .

  • InternalError(1011) - This error indicates that the HTTP request failed due to an internal Google error. If you receive this error, please reissue your request. If the error occurs again, please contact Google support.

  • DomainSuspended(1027) - This error indicates that Google has suspended the domain specified in the HTTP request from using Google Apps. If you receive this error, please reissue your request. If the error occurs again, please contact Google support.

  • ReportNotFound(1045) - This error indicates that the requested report is not available even though the date and report name specified in the request both appear to be valid. If you receive this error, please reissue your request. If the error occurs again, please contact Google support.

  • ReportNotAvailableForGivenDate(1059) - This error indicates that there is no report available for the date specified in the API request. This error will occur if you request a daily report for the current day since daily reports for a particular day are not available until 12 p.m. Pacific time the following day. For example, reports for June 10, 2006, would not be available until 12 p.m. Pacific time on June 11, 2006. This error would also occur if you requested a report for a date in the future.

  • ReportNotAvailableWithGivenName(1060) - This error indicates that you specified either an invalid reportName or a valid reportName and an invalid reportType. For example, you will receive this error if you request a report named accounts1 (instead of accounts).

  • ServerBusy(1070) - This error indicates that the server handling the HTTP request is too busy to fulfill your report request. If you receive this error, please resend your request. If the error occurs again, please contact Google support.

Appendixes

Compression

To conserve bandwidth, you should enable gzip compression on the report response by specifying the following headers on the HTTP request:

User-Agent: gzip
Accept-Encoding: gzip

If the response is encoded with gzip compression, then it contains the following header on the HTTP response:

Content-Encoding: gzip

Other user-agent strings enabling gzip compression on the report response include the user-agent strings for Internet Explorer, Opera, and Mozilla browsers.

If the client does not support transparent gzip decompression but sets the HTTP request headers above, the result will be a compressed stream or file that the user will have to manually gunzip.

Future Versions

Future versions of the Reporting API may introduce new reports or add fields to existing reports. When programming against the Reporting API, it is best to determine the fields and field order by examining the first line of the report data.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.