Google APIs Client Library for Python

Getting Started

This document provides all the basic information you need to start using the library. It covers important library concepts, shows examples for various use cases, and gives links to more information.

Contents

  1. Setup
  2. Authentication and authorization
  3. Building and calling a service
  4. Examples
    1. Simple API example
    2. Authorized API for installed application example
    3. Authorized API for web application example
  5. Django support
  6. Google App Engine support
  7. Finding information about the APIs
  8. Library reference documentation

Setup

There are a few setup steps you need to complete before you can use this library:

  1. If you don't already have a Google account, sign up.
  2. If you have never created a Google APIs Console project, read the Managing Projects page and create a project in the Google APIs Console.
  3. Install the library.

Authentication and authorization

It is important to understand the basics of how API authentication and authorization are handled. All API calls must use either simple or authorized access (defined below). Many API methods require authorized access, but some can use either. Some API methods that can use either behave differently, depending on whether you use simple or authorized access. See the API's method documentation to determine the appropriate access type.

1. Simple API access (API keys)

These API calls do not access any private user data. Your application must authenticate itself as an application belonging to your Google APIs Console project. This is needed to measure project usage for accounting purposes.

Important concepts

  • API key: To authenticate your application, use an API key for your Google APIs Console project. Every simple access call your application makes must include this key.

    Warning: Keep your API key private. If someone obtains your key, they could use it to consume your quota or incur charges against your Google APIs Console project.

2. Authorized API access (OAuth 2.0)

These API calls access private user data. Before you can call them, the user that has access to the private data must grant your application access. Therefore, your application must be authenticated, the user must grant access for your application, and the user must be authenticated in order to grant that access. All of this is accomplished with OAuth 2.0 and libraries written for it.

Important concepts

  • Scope: Each API defines one or more scopes that declare a set of operations permitted. For example, an API might have read-only and read-write scopes. When your application requests access to user data, the request must include one or more scopes. The user needs to approve the scope of access your application is requesting.
  • Refresh and access tokens: When a user grants your application access, the OAuth 2.0 authorization server provides your application with refresh and access tokens. These tokens are only valid for the scope requested. Your application uses access tokens to authorize API calls. Access tokens expire, but refresh tokens do not. Your application can use a refresh token to acquire a new access token.

    Warning: Keep refresh and access tokens private. If someone obtains your tokens, they could use them to access private user data.

  • Client ID and client secret: These strings uniquely identify your application and are used to acquire tokens. They are created for your Google APIs Console project on the API Access pane of the Google APIs Console. There are three types of client IDs, so be sure to get the correct type for your application:
    • Web application client IDs
    • Installed application client IDs
    • Service Account client IDs

    Warning: Keep your client secret private. If someone obtains your client secret, they could use it to consume your quota, incur charges against your Google APIs Console project, and request access to user data.

Building and calling a service

This section describes how to build an API-specific service object, make calls to the service, and process the response.

Build the service object

Whether you are using simple or authorized API access, you use the build() function to create a service object. It takes an API name and API version as arguments. You can see the list of all API versions on the Supported APIs page. The service object is constructed with methods specific to the given API. To create it, do the following:

from apiclient.discovery import build
service = build('api_name', 'api_version', ...)

Collections

Each API service provides access to one or more resources. A set of resources of the same type is called a collection. The names of these collections are specific to the API. The service object is constructed with a function for every collection defined by the API. If the given API has a collection named stamps, you create the collection object like this:

collection = service.stamps()

It is also possible for collections to be nested:

nested_collection = service.featured().stamps()

Methods and requests

Every collection has a list of methods defined by the API. Calling a collection's method returns an HttpRequest object. If the given API collection has a method named list that takes an argument called cents, you create a request object for that method like this:

request = collection.list(cents=5)

Execution and response

Creating a request does not actually call the API. To execute the request and get a response, call the execute() function:

response = request.execute()

Alternatively, you can combine previous steps on a single line:

response = service.stamps().list(cents=5).execute()

Working with the response

The response is a Python object built from the JSON response sent by the API server. The JSON structure is specific to the API; for details, see the API's reference documentation. You can also simply print the JSON to see the structure:

import json
...
print json.dumps(response, sort_keys=True, indent=4)

For example, if the printed JSON is the following:

{
    "count": 2,
    "items": [
        {
            "cents": 5,
            "name": "#586 1923-26 5-cent blue Theodore Roosevelt MLH perf 10"
        },
        {
            "cents": 5,
            "name": "#628 1926 5-cent Ericsson Memorial MLH"
        }
    ]
}

You can access the data like this:

print 'Num 5 cent stamps: %d' % response['count']
print 'First stamp name: %s' % response['items'][0]['name']

Examples

In this section, we provide examples of each access type and application type.

Simple API example

For this example, we use simple API access for a command-line application. It calls the Google Books API to list all books about Android.

Setup for example

  1. Activate the Books API: Read about API activation and activate the Books API on the API Services pane.
  2. Get your Simple API key: You can get this key on the API Access pane. Get more information about this process in the API keys documentation.

Code for example

Download or expand the code below. This script is well commented to explain each step.


Note that the build() function is used to create an API-specific service object. You will always use this function for this purpose. In this case, the API key is passed to the build() function; however, API keys are only relevant to simple API calls like this. The authorization examples below require more code.

Run the example

Copy the script to some directory on your computer, open a terminal, go to the directory, and execute the following command:

$ python simple_api_cmd_line_books.py your_api_key

The command outputs a list of Android books.

Authorized API for installed application example

For this example, we use authorized API access for a command-line application. It calls the Google Calendar API to list a user's calendar events.

Setup for example

  1. Activate the Calendar API: Read about API activation and activate the Calendar API on the API Services pane.
  2. Get your client ID and client secret: Get a client ID and secret for installed applications on the API Access pane.
  3. Create calendar events: In this example, you will read a user's calendar events. You can use any Google user account that you own, including the account associated with the application's Google APIs Console project. For the target user, create a few calendar events if none exist already.

Code for example

Download or expand the code below. This script is well commented to explain each step.


Note how the Storage object is used to to retrieve and store credentials. When no credentials are found, the run() function is used to get user acceptance and credentials. Once credentials are obtained, they are used to authorize an Http object. The authorized Http object is then passed to the build() function to create the service. The calendar API request and response handling shows how to loop through paginated results from a collection. For more information about pagination, see the pagination page in the Developer's Guide.

Run the example

  1. Copy the script to an empty directory on your computer.
  2. Open a terminal and go to the directory.
  3. Execute the following command:
    $ python authorized_api_cmd_line_calendar.py your_client_id your_client_secret
  4. The script will open an authorization sever page in your default web browser.
  5. Follow instructions to authorize the application's access to your calendar data.
  6. Calendar events are sent to stdout by the command.

Subsequent runs of this script will not require the browser because credentials are saved in a file. As mentioned above, these credential files should be kept private.

Authorized API for web application example

For this example, we use authorized API access for a simple web server. It calls the Google Calendar API to list a user's calendar events. Python's built-in BaseHTTPServer is used to create the server. Actual production code would normally use a more sophisticated web server framework, but the simplicity of BaseHTTPServer allows the example to focus on using this library.

Setup for example

  1. Activate the Calendar API: Read about API activation and activate the Calendar API on the API Services pane.
  2. Get your client ID and client secret: Get a client ID and secret for web applications on the API Access pane. Use http://localhost as your domain. After creating the client ID, edit the Redirect URIs field to contain only http://localhost:8080.
  3. Create calendar events: In this example, user calendar events will be read. You can use any Google account you own, including the account associated with the application's Google APIs Console project. For the target user, create a few calendar events if none exist already.

Code for example

Download or expand the code below. This script is well commented to explain each step.


Note how the Storage object is used to to retrieve and store credentials. If no credentials are found, the flow.step1_get_authorize_url() function is used to redirect the user to the authorization server. Once the user has granted access, the authorization server redirects back to the local server with a code query parameter. This code is passed to the flow.step2_exchange() function, which returns credentials. From that point forward, this script is very similar to the command-line access example above.

Run the example

  1. Copy the script to an empty directory on your computer.
  2. Open a terminal and go to the directory.
  3. Execute the following command to run the local server:
    $ python authorized_api_web_server_calendar.py your_client_id your_client_secret
  4. Open a web browser and log in to your Google account as the target user.
  5. Go to this URL: http://localhost:8080/?fake_user=target_user_name replacing target_user_name with the user name for the target user.
  6. If this is the first time the target user has accessed this local server, the target user is redirected to the authorization server. The authorization server asks the target user to grant the application access to calendar data. Click the button that allows access.
  7. The authorization server redirects the browser back to the local server.
  8. Calendar events for the target user are listed on the page.

Django support

This library includes helper classes that simplify use in a Django application. See the Using Django page for details.

Google App Engine support

This library includes helper classes that simplify use in a Google App Engine application. See the Using Google App Engine page for details.

Finding information about the APIs

The Supported APIs page lists all APIs that can be accessed using this library as well as links to documentation.

You can also use the APIs Explorer to browse APIs, list available methods, and even try API calls from your browser.

Library reference documentation

PyDoc generated documentation is available for all modules in this library.

You can get interactive help on library classes and functions using an interactive Python shell.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.