gkeepapi Client for Google Keep

Common errors

• gkeepapi.exception.InvalidUsernameOrPassword: 400 Client Error: Bad Request for url: ...

  cause Incorrect username/app password, or Google blocking login attempts due to security flags (e.g., using a primary password instead of an app password).
  fix Verify your Google username and App Password. Ensure you are using a generated App Password and not your main account password. If the issue persists, check your Google account's security settings for suspicious activity alerts.

• AttributeError: 'Note' object has no attribute 'some_old_attribute'

  cause Attempting to access a node attribute or method that has been renamed or removed in newer `gkeepapi` versions (especially post-0.10.x refactor).
  fix Consult the current `gkeepapi` documentation or source code to understand the updated node object structure and available attributes/methods. Update your code to use the correct names and access patterns.

• requests.exceptions.HTTPError: 429 Client Error: Too Many Requests for url: ...

  cause The Google Keep API has temporarily rate-limited your IP address due to an excessive number of requests in a short period.
  fix Reduce the frequency of your API calls. Add `time.sleep()` delays between requests, particularly in loops or batch operations. For robust applications, implement an exponential backoff strategy for retries.

Warnings

• breaking Major API changes were introduced in versions 0.10.x, affecting authentication methods and the internal structure of node objects (`gkeepapi.node.*`). Code written for versions prior to 0.10.x will likely break.
  Fix: Review the official GitHub README and documentation for your target version. Update `Keep.login()` calls and refactor code that directly accesses `gkeepapi.node` attributes or relies on old node type structures.
• gotcha Directly using your primary Google account password for login is highly discouraged and often fails due to Google's security policies. This can result in 'InvalidUsernameOrPassword' errors or temporary account blocks.
  Fix: Always use a generated Google App Password for programmatic access, or implement OAuth 2.0. App Passwords can be generated at `myaccount.google.com/apppasswords`.
• gotcha Aggressive or frequent API requests can lead to temporary IP bans or rate limiting by Google, resulting in HTTP 429 (Too Many Requests) errors.
  Fix: Implement delays between your API calls, especially for bulk operations. Consider using exponential backoff for retries to mitigate rate limiting.

Install

• pip install gkeepapi Install latest version

Imports

• Keep

  from gkeepapi import Keep

• Note
  wrong:

  from gkeepapi import Note

  correct:

  from gkeepapi.node import Note

  Node types like 'Note' and 'List' reside in the `gkeepapi.node` submodule, not directly under `gkeepapi`.
• InvalidUsernameOrPassword

  from gkeepapi.exception import InvalidUsernameOrPassword

Quickstart

This quickstart demonstrates how to log in to Google Keep using an app password, create a new note, sync changes, and retrieve all notes. Environment variables are used for credentials for security. Remember to replace placeholders or set actual environment variables.

import os
from gkeepapi import Keep
from gkeepapi.exception import InvalidUsernameOrPassword

# Recommended: Use a Google App Password for programmatic access.
# Generate one at: myaccount.google.com/apppasswords
# Store in environment variables or directly replace placeholders.
USERNAME = os.environ.get('GKEEP_USERNAME', 'your_email@example.com')
APP_PASSWORD = os.environ.get('GKEEP_APP_PASSWORD', 'your_app_password')

if not USERNAME or not APP_PASSWORD or APP_PASSWORD == 'your_app_password':
    print("Please set GKEEP_USERNAME and GKEEP_APP_PASSWORD environment variables (or replace placeholders).")
    print("Consider using a Google App Password for better security.")
    exit(1)

keep = Keep()

try:
    # Login using username and app password
    success = keep.login(USERNAME, APP_PASSWORD)

    if success:
        print("Login successful!")

        # Create a new text note
        note = keep.createNote('gkeepapi Quickstart Note', 'This note was created programmatically.')
        print(f"Created note: '{note.title}' (ID: {note.id})")

        # Sync changes to Google Keep
        keep.sync()
        print("Changes synced.")

        # Fetch and print titles of all notes
        print("\nAll notes in Keep:")
        for n in keep.all():
            print(f"- {n.title}")

    else:
        print("Login failed for an unknown reason.")

except InvalidUsernameOrPassword:
    print("Login failed: Invalid username or app password. Double-check your credentials and ensure an App Password is used.")
except Exception as e:
    print(f"An error occurred: {e}")