English | Site Directory

Google Apps APIs

Google Apps Reporting API Reference

Contents

  1. Overview
  2. Submitting Requests to the Reporting API
    1. XML Element Definitions
  3. Reports
    1. Accounts Report
    2. Activity Report
    3. Disk Space Report
    4. Email Clients Report
    5. Quota Limit Accounts Report
    6. Summary Report
    7. Suspended Accounts Report
  4. Error Handling
  5. Appendixes
    1. Authentication
      1. Obtaining an Authentication Token
      2. Sample Code for Obtaining an Authentication Token
    2. Compression
    3. Future Versions

Overview

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. The XML document also specifies an authentication token, which Google uses to confirm that you are authorized to receive the requested data.

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.

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

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>
    <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token>
    <domain>example.com</domain>
    <date>2006-08-01</date>
    <reportType>daily</reportType>
    <reportName>disk_space</reportName>
</rest>

Note: You must set the <domain> tag value to your domain. You must also set the <token> tag value to your authentication token. Finally, you must set the <reportType> and <reportName> tags to specify the report that you wish to retrieve.

Google will use the value of the <token> tag to verify that you are authorized to access the requested data. 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.

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 <rest xmlns="google:accounts:rest:protocol"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
Subtags type, token, domain, date, 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 <type>Report</type>
Subtag of rest
Content Format Text
token
Definition Contains a value that Google uses to authorize access to the requested report data. The Authentication section provides instructions and sample code for obtaining an authentication token.

Note: Your authentication token may be much longer than the value shown in the example.
Example <token>DQAAAGAAAADa7eYOUNcbs9zZxMnLvHdEy...</token>
Subtag of rest
Content Format Text
domain
Definition Identifies the Google partner domain for a hosted account, email alias or mailing list.
Example <domain>example.com</domain>
Subtag of rest
Content Format Text
date
Definition Specifies 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, Quota Limit Accounts or Suspended 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 <date>2006-10-14</date>
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 <reportType>daily</reportType>
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
  • quota_limit_accounts
  • summary
  • suspended_accounts
Example <reportName>disk_space</reportName>
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

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>
    <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token>
    <domain>example.com</domain>
    <date>2006-08-01</date>
    <reportType>daily</reportType>
    <reportName>accounts</reportName>
</rest>

Sample Report Data

Note: The data in this sample report has been reformatted to ensure that this document prints correctly. In this sample, an indented line signifies the continuation of the previous line. In the reports you receive through the API, there will not be carriage returns between indented lines and the lines above them.

date, account_id, account_name, status, quota_in_mb, 
    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

20060808, 000000aaaaa11111, "abuse@example.com", "ACTIVE", 10240, 
    9235, , , 20060802, 19691231, 20060802, , "Abuse", 0, ,

20060808, 000000bbbbb22222, "admin@example.com", "ACTIVE", 2048, 
    2593, , , 20060721, 20060804, 20060807, , "Admin", 0, ,

20060808, 000000ccccc33333, "bart@example.com", "SUSPENDED", 2048, 
    29057823, , , 20060801, 20060808, 20060807, 
    "Simpson", "Bart", , , "Suspended for abuse"

20060808, 000000ddddd4444, "homer@example.com", "SUSPENDED", 2048, 
    3072, , , 20060803, 20060808, 20060807, 
    "Simpson", "Homer", , , "Disabled by operator"

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 user's email address, 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

The quota_in_mb 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.

Note: All dates are recorded using Pacific Time (PT).

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.

Note: All dates are recorded using Pacific Time (PT).
last_web_mail_date

The last_web_mail_date field specifies the most recent date that email for an account was accessed using WebMail.

Note: All dates are recorded using Pacific Time (PT).
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

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.

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>
    <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token>
    <domain>example.com</domain>
    <date>2006-08-01</date>
    <reportType>daily</reportType>
    <reportName>activity</reportName>
</rest>

Sample Report Data

Note: The data in this sample report has been reformatted to ensure that this document prints correctly. In this sample, an indented line signifies the continuation of the previous line. In the reports you receive through the API, there will not be carriage returns between indented lines and the lines above them.

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>
    <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token>
    <domain>example.com</domain>
    <date>2006-08-01</date>
    <reportType>daily</reportType>
    <reportName>disk_space</reportName>
</rest>

Sample Report Data

Note: The data in this sample report has been reformatted to ensure that this document prints correctly. In this sample, an indented line signifies the continuation of the previous line. In the reports you receive through the API, there will not be carriage returns between indented lines and the lines above them.

date,num_accounts,usage_in_bytes,avg_usage_in_mb,quota_in_mb,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

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
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>
    <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token>
    <domain>example.com</domain>
    <date>2006-08-01</date>
    <reportType>daily</reportType>
    <reportName>email_clients</reportName>
</rest>

Sample Report Data

Note: The data in this sample report has been reformatted to ensure that this document prints correctly. In this sample, an indented line signifies the continuation of the previous line. In the reports you receive through the API, there will not be carriage returns between indented lines and the lines above them.

date,num_accounts,web_mail_count

20060801,46,8
20060802,75,39
20060803,78,13
20060804,82,15

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

Quota Limit Accounts Report

The quota_limit_accounts report contains a list of the accounts that are approaching or have exceeded their disk space quota. An account will be included in this report if it has less than 5 percent of its quota remaining. This report does not include suspended accounts.

Sample XML Request

To retrieve this report, set the value of the <reportName> tag to quota_limit_accounts. The following XML shows a sample request for a Quota Limit 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>
    <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token>
    <domain>example.com</domain>
    <date>2006-08-01</date>
    <reportType>daily</reportType>
    <reportName>quota_limit_accounts</reportName>
</rest>

Sample Report Data

date,account_id,account_name,status,disk_space_in_mb,quota_in_mb
20060807,000000ccccc33333,"bart@example.com","QUOTA_LIMIT",2000,2048

Field Definitions for the Quota Limit Accounts Report

The following table lists the fields in the quota_limit_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 user's email address, including a username and your domain name – e.g. admin@example.com.

Type: String
status

The status field indicates that an account has almost reached or has exceeded its disk space quota. Valid values for this field are QUOTA_APPROACHING and QUOTA_EXCEEDED.

Type: String
disk_space_in_mb

The disk_space_in_mb field indicates the amount of disk space, in megabytes, that is being used by a particular account.

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

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>
    <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token>
    <domain>example.com</domain>
    <date>2006-08-01</date>
    <reportType>daily</reportType>
    <reportName>summary</reportName>
</rest>

Sample Report Data

date,num_accounts,usage_in_bytes,quota_in_mb
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

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

Type: Integer

Suspended Accounts Report

The suspended_accounts report lists all of the suspended accounts in your domain on a particular day.

Sample XML Request

To retrieve this report, set the value of the <reportName> tag to suspended_accounts. The following XML shows a sample request for a Suspended 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>
    <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token>
    <domain>example.com</domain>
    <date>2006-08-01</date>
    <reportType>daily</reportType>
    <reportName>suspended_accounts</reportName>
</rest>

Sample Report Data

Note: The data in this sample report has been reformatted to ensure that this document prints correctly. In this sample, an indented line signifies the continuation of the previous line. In the reports you receive through the API, there will not be carriage returns between indented lines and the lines above them.

date,account_id,account_name,status,reason

20060808,000000ccccc33333,"bart@example.com","SUSPENDED_FOR_ABUSE",
    "Suspended for abuse"

20060808,000000ddddd4444,"homer@example.com","SUSPENDED_BY_ADMIN",
    "Disabled by operator on 20060725"

Field Definitions for the Suspended Accounts Report

The following table lists the fields in the suspended_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 user's email address, including a username and your domain name – e.g. admin@example.com.

Type: String
status

The status field provides some information as to why an account has been suspended. The suspension_reason field may contain additional information explaining why an account was suspended.

Valid values for this field are SUSPENDED_FOR_ABUSE, SUSPENDED_BY_ADMIN and OTHER.

Type: String
suspension_reason

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

Type: String

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 <hs:reason> 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 <hs:reason> 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 authentication token specified in your request has expired. Please note that authentication tokens expire after 24 hours. If you feel you have received this response in error, please contact Google support.

  • 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

Authentication

All of your API requests must be sent over HTTPS. In addition, all data sent to the API will be delivered using HTTPS POST to ensure the security of that data.

Each API request that you send needs to contain an authentication token, which Google will use to authorize access to the operation specified in the API request. Authentication tokens are only available to users who have administrative rights in your domain, and those tokens only authorize operations within your domain.

The ClientLogin Interface provides additional information about programmatically logging users into their accounts.

Obtaining an Authentication Token

To obtain an authentication token, submit an HTTP POST request to the following URL:

https://www.google.com/accounts/ClientLogin

The following guidelines apply to the request:

  • The POST body needs to include a string in the following format:

    accountType=HOSTED&Email=email_address&Passwd=password

    You will need to make the following changes to this string:

    • Replace the string email_address with the email address for your hosted admin account.

    • Replace the string password with the password for that account.

  • The email address and password in the POST body must be URL-encoded. For example, the URL-encoded form of the email address apps.test.account@example.com is apps%2etest%2eaccount%10example%2ecom.

  • The POST request must specify the value application/x-www-form-urlencoded for the Content-Type header.

Google will return a response containing your authentication token in response to your POST request. The authentication token will be the SID value on that page. You need to extract the token from the page and then submit that token in API requests.

Note: Authentication tokens expire after 24 hours. As such, you will need to submit a request to the above URL at least once every 24 hours. We recommend that you keep the token in memory rather than writing it to a file.

Sample Code for Obtaining an Authentication Token

The following Perl script demonstrates how to make an HTTP POST request for an authentication token.

#! /usr/bin/perl -w

use strict;
use LWP::UserAgent;

# Create an LWP object to make the HTTP POST request
my $lwp_object = LWP::UserAgent->new;

# Define the URL to submit the request to
my $url = 'https://www.google.com/accounts/ClientLogin';

# Submit the request with values for the accountType, 
# Email and Passwd variables.
my $response = $lwp_object->post( $url,
            [ 'accountType' => 'HOSTED',
              'Email' => 'admin_email@example.com',
              'Passwd' => 'admin_password'
            ]
);

die "$url error: ", $response->status_line unless $response->is_success;

# Extract the authentication token from the response
my $auth_token;
foreach my $line (split/\n/, $response->content) {
    if ($line =~ m/^SID=(.+)$/) {
        $auth_token = $1;
        last;
    }
}

print "authentication token is $auth_token\n";

Note that to use this code, you need to replace the Email and Passwd values with the email address and password for your hosted admin account.

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.