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 Authentication

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 examples in this document assume you are providing the appropriate authentication.

OAuth scope parameter

Use the following scope for read only access to the Reporting API:

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

Getting and using a token credential

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.

  • If your application requires enhanced security using the RSA-SHA1 signature, you must get your security certificate before registering your application with Google. The uploading of this certificate is part of the registration process. For more information, see Generating keys and certificates for use with registered mode.
  • If you use a HMAC-SHA1 signature to sign your requests, no security certificate is required. For the HMAC-SHA1 signature, Google generates an OAuth consumer secret value, which is displayed on your domain's registration page after you have registered.

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:
  1. Get your temporary token (request token). This token is used once. (OAuthGetRequestToken)
  2. Ask the user to authorize the request token (OAuthAuthorizeToken)
  3. Exchange the authorized request token for a token credential (access token). (OAuthGetAccessToken)

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.

  1. Create the signature base string. Note, the actual string is continuous. This example uses line returns for display purposes.
    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
    
  2. Set the 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
  3. The Authorization header is similar to this example. Note, the string is continuous and this example uses line returns for display purposes.
    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"

Additional OAuth reference and resources

Getting started

References

ClientLogin Authentication

Important: ClientLogin has been officially deprecated as of April 20, 2012. We strongly encourage you to migrate to the OAuth protocol as soon as possible.

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.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.