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']
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:
- Download a page of threads for the current user, and
- Output the ID for each thread
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:
- Go to the Google Developers Console.
- Select a project, or create a new one.
- 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.
- 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.
- Create a new file
quickstart.py, then copy the source code below into it.
- Edit the source file to specify the correct
client_secret.jsonwith 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
- Browse to the provided URL in your web browser.
- 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.
- 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.
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.