gkeepapi Documentation

To interact with Google Keep, import gkeepapi, authenticate using a Keep object with a master token, and call sync() to push local changes to the server.

Note: The client is mostly complete, but the interface for manipulating labels and blobs is subject to change.

import gkeepapi

# Obtain a master token for your account
master_token = '...'

keep = gkeepapi.Keep()
keep.authenticate('user@gmail.com', master_token)

note = keep.createNote('Todo', 'Eat breakfast')
note.pinned = True
note.color = gkeepapi.node.ColorValue.Red

keep.sync()

print(note.title)
print(note.text)

To enable development debug logs for troubleshooting, set the DEBUG flag in the gkeepapi.node module.

gkeepapi.node.DEBUG = True

To avoid long initial sync times, you can serialize the current state of your notes to a file using Keep.dump(). You can then resume from this state in future runs using Keep.restore(state) or by passing the state directly to Keep.authenticate().

# Store cache
state = keep.dump()
with open('state', 'w') as fh:
    json.dump(state, fh)

# Load cache
with open('state', 'r') as fh:
    state = json.load(fh)
keep.restore(state)

# Alternatively, pass state during authentication
keep.authenticate(username, master_token, state=state)

The client uses the private mobile Google Keep API. Authentication requires a master token for the account, which provides full access. Protect this token like a password.

Use Keep.authenticate(username, master_token) to log in. It is recommended to store the token in a platform secrets store (like keyring) rather than hardcoding it in your script.

import keyring
import gkeepapi

# To save the token
# keyring.set_password('google-keep-token', 'user@gmail.com', master_token)

master_token = keyring.get_password("google-keep-token", "user@gmail.com")
keep = gkeepapi.Keep()
keep.authenticate('user@gmail.com', master_token)

Install the gkeepapi library using the Python package manager pip.

pip install gkeepapi

To use gkeepapi, you must first obtain a master token for your Google account (refer to the project documentation for instructions on obtaining this token). Once obtained, use keep.authenticate(email, master_token) to establish a session. This method returns a boolean indicating whether authentication was successful.

import gkeepapi

# Obtain a master token for your account (see docs)
master_token = '...'

keep = gkeepapi.Keep()
success = keep.authenticate('user@gmail.com', master_token)

You can obtain a master token using the gpsoauth tool. If you have Docker installed, you can use the following command to prompt for the necessary information (Email, OAuth Token, and Android ID) and output the token:

docker run --rm -it --entrypoint /bin/sh python:3 -c 'pip install gpsoauth; python3 -c '\'print(__import__("gpsoauth").exchange_token(input("Email: "), input("OAuth Token: "), input("Android ID: ")))'\''

The Keep class is the recommended way to interact with Google Keep. It manages a local copy of your notes and labels, allowing you to manipulate them locally before syncing changes to the server.

Typical Workflow:

1. Authenticate: Use keep.authenticate(email, master_token) to establish a session.
2. Manipulate: Retrieve notes with keep.get(id), create new ones with keep.createNote(), or create lists with keep.createList().
3. Sync: Call keep.sync() to upload your local changes to Google and download any changes made on other devices.

When Google changes its data format, gkeepapi may raise a gkeepapi.exception.ParseException. To report this error effectively on GitHub, you should include the raw data from the exception object.

try:
    # Code that raises the exception
except gkeepapi.exception.ParseException as e:
    print(e.raw)

If you encounter gkeepapi.exception.LoginException with messages like NeedsBrowser, CaptchaRequired, or BadAuthentication, Google is likely flagging the login as suspicious.

To resolve this:

1. Ensure you are using the latest version of gkeepapi.
2. Cache your authentication token: Instead of logging in with credentials every time, use a master token and cache it for subsequent runs. (Using Keep.authenticate can help avoid these issues).
3. Ensure you are using Python 3.7 or newer.
4. If the issue persists, test with a different IP address or a different user account to isolate the cause.