Making it simple to call Google APIs

Use the simple and clean library to make calls from Python to an API.

# List my public Google+ activities.
result = service.activities().list(userId='me', collection='public').execute()
tasks = result.get('items', [])
for task in tasks:
  print task['title']

Easy authentication

The easy-to-use authentication library can reduce the amount of code you need to write to handle OAuth 2.0. Sometimes as little as a couple of lines is all you need.

# Authorize server-to-server interactions from Google Compute Engine.
from oauth2client import gce

credentials = gce.AppAssertionCredentials(
  scope='https://www.googleapis.com/auth/devstorage.read_write')
http = credentials.authorize(httplib2.Http())

Runs on Google App Engine

App Engine-specific helpers make quick work of authenticated calls to APIs. No need to worry about exchanging code for tokens; get right down to writing the meat of your application.

# Restrict access to users that have granted access to Calendar information.
decorator = appengine.OAuth2DecoratorFromClientSecrets(
  'client_secrets.json',
  scope='https://www.googleapis.com/auth/calendar')

class MainHandler(webapp.RequestHandler):
  @decorator.oauth_required
  def get(self):
    http = decorator.http()
    request = service.events().list(calendarId='primary')
    ...

Client library installation

Install the library using standard Python tools.

$ pip install --upgrade google-api-python-client

There are also custom installs optimized for Google App Engine.

Use the Quickstart guide to download a starter application for the API and platform you’re interested in:

Check out all the installation options.

Quickstart: Run a Gmail App in Python

Complete the steps described in the rest of this page, and in about five minutes you’ll have a simple app that uses the Gmail API to:

1. Download a page of threads for the current user, and
2. Output the ID for each thread

Contents

To run a quickstart example you’ll need:

• Access to the internet and a web browser, in order to authorize the sample app.
• A Google account for the Gmail address.
• An environment to run programs in your selected language.

Step 1: Enable the Gmail API

To get started using Gmail API, you need to first create or select a project in the Google Developers Console and enable the API. Using this link guides you through the process and activates the Gmail API automatically.

Alternatively, you can activate the Gmail API yourself in the Developers Console by doing the following:

1. Go to the Google Developers Console.
2. Select a project, or create a new one.
3. In the sidebar on the left, expand APIs & auth. Next, click APIs. In the list of APIs, make sure the status is ON for the Gmail API.
4. In the sidebar on the left, select Credentials.

In either case, you end up on the Credentials page and can create your project’s credentials from here.

To find your application’s client ID and client secret, and set a redirect URI, expand the OAuth 2.0 Client ID section.

Click Download JSON to save the client secrets file, then place this file at a location where your app can easily access it.

Step 2: Set up the sample

You’ll need to create a source code file and then modify it to reference your app’s client secret file, as described below.

1. Create a new file quickstart.py, then copy the source code below into it.
2. Edit the source file to specify the correct CLIENT_SECRET_PATH: replace client_secret.json with the actual path to the client secret file that you downloaded in the “Enable the Gmail API” step.

#!/usr/bin/python

import httplib2

from apiclient.discovery import build
from oauth2client.client import flow_from_clientsecrets
from oauth2client.file import Storage
from oauth2client.tools import run


# Path to the client_secret.json file downloaded from the Developer Console
CLIENT_SECRET_FILE = 'client_secret.json'

# Check https://developers.google.com/gmail/api/auth/scopes for all available scopes
OAUTH_SCOPE = 'https://www.googleapis.com/auth/gmail.readonly'

# Location of the credentials storage file
STORAGE = Storage('gmail.storage')

# Start the OAuth flow to retrieve credentials
flow = flow_from_clientsecrets(CLIENT_SECRET_FILE, scope=OAUTH_SCOPE)
http = httplib2.Http()

# Try to retrieve credentials from storage or run the flow to generate them
credentials = STORAGE.get()
if credentials is None or credentials.invalid:
  credentials = run(flow, STORAGE, http=http)

# Authorize the httplib2.Http object with our credentials
http = credentials.authorize(http)

# Build the Gmail service from discovery
gmail_service = build('gmail', 'v1', http=http)

# Retrieve a page of threads
threads = gmail_service.users().threads().list(userId='me').execute()

# Print ID for each thread
if threads['threads']:
  for thread in threads['threads']:
    print 'Thread ID: %s' % (thread['id'])

Step 3: Run the sample

When you run the sample from command line, it provides a link you’ll need to visit in order to authorize.

Run the sample using python quickstart.py.

1. Browse to the provided URL in your web browser.
2. If you are not already logged into your Google account, you will be prompted to log in. If you are logged into multiple Google accounts, you will be asked to select one account to use for the authorization.
3. Copy the code you’re given after browsing to the link, and paste it into the prompt Enter authorization code:. Click Enter.

The application should display a list of thread IDs.

Next steps

If your goal is to expand the quickstart sample into something for your own installed application, consult the API Reference. The API Reference discusses all of the features of the Gmail API, and gives samples in each language on how to use a feature.

All requests to the Gmail API must be authorized by an authenticated user. To examine more authorization code and learn how to authorize requests, see Authorizing Your App with Gmail.