Last updated December 15, 2011 (see recent changes)
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 free, Business, Education, Government, Reseller, and ISP accounts.
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>
Note: You must set the <domain> tag value to your domain. Finally, you must set the <reportType> and <reportName> tags to specify the report that you wish to retrieve. The <token> element is required only in case of ClientLogin and must match the SID token of the ClientLogin response.
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.
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.
Note: When requesting reports for accounts with multiple domains, the reports return all of the domains, the primary domain and any additional domains.
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>
Note: If you are not contractually obligated to provide full support for your customers, your access to your customer's account is granted by the customer. If you have not been granted access or do not manage this customer, the Reporting API does not return reports for this domain. The system returns an AuthenticationFailure(1600) error in the HTTP status code. For more information about access to a customer's control panel, see the help center. For additional details, see the Authorized Resellers information.
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, 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 | <type>Report</type> |
| 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 | <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.
|
| Example | <date>2006-10-14</date> |
| 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 | <page>1</page> |
| 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:
|
| Example | <reportName>disk_space</reportName> |
| Subtag of | rest |
| Content Format | Text |
Google Apps reports enable you to monitor the usage of hosted accounts for your domain. The following list identifies the different reports.
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.
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.com</domain> <date>2006-08-01</date> <page>1</page> <reportType>daily</reportType> <reportName>accounts</reportName> </rest>
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, last_pop_date, creation_time,
last_login_time, last_web_mail_time, last_pop_time
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
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
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
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
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. 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) |
| Note: All dates and times are recorded using Pacific Time (PT). | |
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.
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>2006-08-01</date> <reportType>daily</reportType> <reportName>activity</reportName> </rest>
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
The following table lists the fields in the activity 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.
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>2006-08-01</date> <reportType>daily</reportType> <reportName>disk_space</reportName> </rest>
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
The following table lists the fields in the disk_space 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.
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>2006-08-01</date> <reportType>daily</reportType> <reportName>email_clients</reportName> </rest>
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,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
The following table lists the fields in the email_clients 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.
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>2006-08-01</date> <reportType>daily</reportType> <reportName>summary</reportName> </rest>
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
The following table lists the fields in the summary report.
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 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.
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.
The Reporting API is designed for multi-user web applications. The API uses HTTPS POST and the OAuth 1.0 standard protocol to securely authenticate each request and authorize the scope of each API report.
The OAuth 1.0 protocol is a secure authentication and authorization service. This allows your web application to be given permission to access specific areas of your user's GoogleApps data without revealing the users' names and passwords. The authentication examples in this document use the OAuth 1.0 delegated access 3-legged work flow which lets your web application access a GoogleApps user's data hosted on the Google servers.
The OAuth protocol is the recommended secure authentication service for this API. The ClientLogin authentication protocol is deprecated and is for standalone single-user installed clients. Moving forward, we recommend not using the ClientLogin protocol with the API.
The examples in this document assume you are providing the appropriate authentication.
Use the following scope for read only access to the Reporting API:
https://www.google.com/hosted/services/v1.0/reports/ReportingData
When setting up your OAuth credentials, determine your development environment, signature type and application registration. Then create your token credentials, and the OAuth signature.
For detailed OAuth information, see the OAuth reference and resources section of this document. And, if you are new to OAuth, we recommend the Beginner's Guide for OAuth.
Your development environment
We recommend using a Google API client library. For Java clients, see the Java OAuth client library Overview for detailed instructions for getting and using an OAuth token credential.
The OAuth examples in this document use the generic XML.
Determine your OAuth signature and register your application
Before building up your OAuth 1.0 configuration, determine the type of OAuth signature used by your client application, and register your web application with Google.
For more information on the registration process, see Registration for Web Applications. For more information about registering, see 'Deciding whether to register your web application'. This gives you your client credential (consumer key and secret).
Note: Do not use the OAuth non-registered option where the consumer key and consumer secret properties have 'anonymous' values. The API feeds are available to Google registered applications only. And all of your application's OAuth interactions must be digitally signed.
Get a token credential
Follow these general steps to obtain an a token credential. For more information, see OAuth Authentication for Web Applications:Create your OAuth signature
Once you have a valid token credential, your client application can send requests with an OAuth_signature, and Authorization header. These examples use the RSA-SHA1 signature method.
POST&https://www.google.com/hosted/services/v1.0/reports/ReportingData &oauth_consumer_key=example.com&oauth_nonce=38863f48...28dd9fd2c &oauth_signature_method=RSA-SHA1&oauth_timestamp=1249972977 &oauth_token=1%2Fz1...LMzNBrKhElA&oauth_version=1.0
oauth_signature to the result of signing the base string with the
algorithm you specify in the oauth_signature_method. This requires URL-encoding
the signature base string. Note, the string is continuous and this example uses line returns
for display purposes.
POST&https%3A%2%2Fwww.google.com%2Fhosted%2Fservices%2Fv1.0%2Freports %2FReportingData%2F&oauth_consumer_key%3Dexample.com %26oauth_nonce%3D38863f48...28dd9fd2c%26oauth_signature_method%3DRSA-SHA1 %26oauth_timestamp%3D1249972977%26oauth_token%3D1%252Fz1...LMzNBrKhElA %26oauth_version%3D1.0
POST https://www.google.com/hosted/services/v1.0/reports/ReportingData ...
Authorization: OAuth oauth_version="1.0", oauth_nonce="38863f48...28dd9fd2c", >oauth_timestamp="1249972977", oauth_consumer_key="example.com", oauth_token="1%2Fz1...LMzNBrKhElA", oauth_signature_method="RSA-SHA1", oauth_signature="kH%2BjQd%2Ba8...odMeUnsU%2FxANOw%3D"
Getting started
References
The ClientLogin authentication protocol is deprecated and is for standalone single-user installed clients. Moving forward, we recommend not using the ClientLogin protocol with the API.
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 a ClientLogin 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 or two-step access code
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 or the two-step verification access code.
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%40example%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.
Limits and quotas protect the Google infrastructure from an automated process that uses the Reporting API in an inappropriate way. Excessive requests from an API might result from a harmless typo, or may result from an inefficiently designed system that makes needless API calls. Regardless of the cause, blocking traffic from a specific source once it reaches a certain level is necessary for the overall health of the Google Apps system. It ensures that one developer's actions cannot negatively impact the larger community.
In the unlikely event that your API request fails, you'll receive an HTTP status code response. A status code of 403 has error information about incorrect input and an HTTP status code of 503 has error information indicating which API quotas have been exceeded. These responses allow your custom application to detect these errors and take appropriate action.
If your requests need to be completed in a fixed period of time, send your requests in parallel or use multiple threads in your Java or C# application. An example of parallel requests is requesting parallel operations across different groups, rather than adding or removing lots of members from one group simultaneously. In the case of threads, try starting with 10 threads. Note, the thread recommendation has trade-offs and is not useful for all API situations. If the number of requests gets too high, quota errors will occur. Another trade-off example is the Email Migration API's quota for the maximum overall message upload rate. The upload rate is one message - per second - per user, no matter how many threads are making upload requests.
For all errors that are time based (maximum of N things for N seconds per thread), especially the 503 status code errors, we recommend your code catch the exception and, using an exponential backoff algorithm, wait for a small delay before retrying the failed call. A Reporting API example for one thread is to wait 5 seconds and retry the failed call. If the request is successful, repeat this pattern for the other threads. If the second request is not successful, your application should scale back on the frequency of the request until a call is successful. For example, increase the initial 5 second delay to 10 seconds and retry your failed call again. Also, decide on a retry limit. For example retry a request 5 to 7 times with different delay times before your application returns an error to the user.
| API Quota Categories | Quotas |
|---|---|
| Account ID | The Account report's account_id tag is a 16-character hexadecimal string. |
| ClientLogin authentication tokens | Valid for 24 hours. If the token is expired, the system returns the AuthenticationFailure(1006) error |
| Disk space | In the disk space report, 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. |
| Pagination | If set for pagination (set page=1), the API returns a maximum of 10 entries per page using a |
| Quota limit | The Account report returns any account with less than 5 percent of its quota remaining. This information does not include suspended accounts. |
| Other Types of Limits | Limitations and Guidelines |
|---|---|
| Date availability | The Account report's dates are not available until 12 p.m. Pacific Time (PT) 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 requesting a report before this time, a ReportNotAvailableForGivenDate(1059) error is returned |
| Dates of reports |
For the Accounts report, 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 the Activity, Disk Space, Email Client or Summary reports, Google returns 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. |
| Suspended accounts | The Accounts report returns suspended account information except for a suspended account's quota limit information.
The Summary, Email Clients reports do not include information for suspended accounts. The Accounts report does not return quota limit information for suspended accounts. |
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 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.