gkeepapi package

Submodules

gkeepapi.node module

class gkeepapi.API(base_url, auth=None)[source]

Base API wrapper

getAuth()[source]

Get authentication details for this API.

Parameters:auth (APIAuth) – The auth object
send(**req_kwargs)[source]

Send an authenticated request to a Google API. Automatically retries if the access token has expired.

Parameters:

**req_kwargs – Arbitrary keyword arguments to pass to Requests.

Returns:

The parsed JSON response.

Return type:

dict

Raises:
  • APIException – If the server returns an error.
  • LoginException – If login() has not been called.
setAuth(auth)[source]

Set authentication details for this API.

Parameters:auth (APIAuth) – The auth object
class gkeepapi.APIAuth(scopes)[source]

Authentication token manager

getAuthToken()[source]

Gets the auth token.

Returns:The auth token.
Return type:Union[str, None]
getDeviceId()[source]

Gets the device id.

Returns:The device id.
Return type:str
getEmail()[source]

Gets the account email.

Returns:The account email.
Return type:str
getMasterToken()[source]

Gets the master token.

Returns:The account master token.
Return type:str
load(email, master_token, device_id)[source]

Authenticate to Google with the provided master token.

Parameters:
  • email (str) – The account to use.
  • master_token (str) – The master token.
  • device_id (str) – An identifier for this client.
Raises:

LoginException – If there was a problem logging in.

login(email, password, device_id)[source]

Authenticate to Google with the provided credentials.

Parameters:
  • email (str) – The account to use.
  • password (str) – The account password.
  • device_id (str) – An identifier for this client.
Raises:

LoginException – If there was a problem logging in.

logout()[source]

Log out of the account.

refresh()[source]

Refresh the OAuth token.

Returns:The auth token.
Return type:string
Raises:LoginException – If there was a problem refreshing the OAuth token.
setDeviceId(device_id)[source]

Sets the device id.

Parameters:device_id (str) – The device id.
setEmail(email)[source]

Gets the account email.

Parameters:email (str) – The account email.
setMasterToken(master_token)[source]

Sets the master token. This is useful if you’d like to authenticate with the API without providing your username & password. Do note that the master token has full access to your account.

Parameters:master_token (str) – The account master token.
class gkeepapi.Keep[source]

High level Google Keep client.

Stores a local copy of the Keep node tree. To start, first login:

keep.login('...', '...')

Individual Notes can be retrieved by id:

some_note = keep.get('some_id')

New Notes can be created:

new_note = keep.createNote()

These Notes can then be modified:

some_note.text = 'Test'
new_note.text = 'Text'

These changes are automatically detected and synced up with:

keep.sync()
add(node)[source]

Register a top level node (and its children) for syncing up to the server. There’s no need to call this for nodes created by createNote() or createList() as they are automatically added.

LoginException: If login() has not been called.
Parameters:node (gkeepapi.node.Node) – The node to sync.
Raises:Invalid – If the parent node is not found.
all()[source]

Get all Notes.

Returns:Notes
Return type:List[gkeepapi.node.TopLevelNode]
createLabel(name)[source]

Create a new label.

Parameters:name (str) – Label name.
Returns:The new label.
Return type:gkeepapi.node.Label
Raises:LabelException – If the label exists.
createList(title=None, items=None)[source]

Create a new list and populate it. Any changes to the note will be uploaded when sync() is called.

Parameters:
  • title (str) – The title of the list.
  • items (List[(str, bool)]) – A list of tuples. Each tuple represents the text and checked status of the listitem.
Returns:

The new list.

Return type:

gkeepapi.node.List

createNote(title=None, text=None)[source]

Create a new managed note. Any changes to the note will be uploaded when sync() is called.

Parameters:
  • title (str) – The title of the note.
  • text (str) – The text of the note.
Returns:

The new note.

Return type:

gkeepapi.node.List

deleteLabel(label_id)[source]

Deletes a label.

Parameters:label_id (str) – Label id.
dump()[source]

Serialize note data.

Parameters:state (dict) – Serialized state to load.
find(query=None, func=None, labels=None, colors=None, pinned=None, archived=None, trashed=False)[source]

Find Notes based on the specified criteria.

Parameters:
  • query (Union[_sre.SRE_Pattern, str, None]) – A str or regular expression to match against the title and text.
  • func (Union[callable, None]) – A filter function.
  • labels (Union[List[str], None]) – A list of label ids or objects to match. An empty list matches notes with no labels.
  • colors (Union[List[str], None]) – A list of colors to match.
  • pinned (Union[bool, None]) – Whether to match pinned notes.
  • archived (Union[bool, None]) – Whether to match archived notes.
  • trashed (Union[bool, None]) – Whether to match trashed notes.
Returns:

Results.

Return type:

Generator[gkeepapi.node.TopLevelNode]

findLabel(query, create=False)[source]

Find a label with the given name.

Parameters:
  • name (Union[_sre.SRE_Pattern, str]) – A str or regular expression to match against the name.
  • create (bool) – Whether to create the label if it doesn’t exist (only if name is a str).
Returns:

The label.

Return type:

Union[gkeepapi.node.Label, None]

get(node_id)[source]

Get a note with the given ID.

Parameters:node_id (str) – The note ID.
Returns:The Note or None if not found.
Return type:gkeepapi.node.TopLevelNode
getLabel(label_id)[source]

Get an existing label.

Parameters:label_id (str) – Label id.
Returns:The label.
Return type:Union[gkeepapi.node.Label, None]
getMasterToken()[source]

Get master token for resuming.

Returns:The master token.
Return type:str

Get the canonical link to media.

Parameters:blob (gkeepapi.node.Blob) – The media resource.
Returns:A link to the media.
Return type:str
labels()[source]

Get all labels.

Returns:Labels
Return type:List[gkeepapi.node.Label]
load(auth, state=None, sync=True)[source]

Authenticate to Google with a prepared authentication object & sync. :param auth: Authentication object. :type auth: APIAuth :param state: Serialized state to load. :type state: dict

Raises:LoginException – If there was a problem logging in.
login(username, password, state=None, sync=True, device_id=None)[source]

Authenticate to Google with the provided credentials & sync.

Parameters:
  • email (str) – The account to use.
  • password (str) – The account password.
  • state (dict) – Serialized state to load.
Raises:

LoginException – If there was a problem logging in.

restore(state)[source]

Unserialize saved note data.

Parameters:state (dict) – Serialized state to load.
resume(email, master_token, state=None, sync=True, device_id=None)[source]

Authenticate to Google with the provided master token & sync.

Parameters:
  • email (str) – The account to use.
  • master_token (str) – The master token.
  • state (dict) – Serialized state to load.
Raises:

LoginException – If there was a problem logging in.

sync(resync=False)[source]

Sync the local Keep tree with the server. If resyncing, local changes will be destroyed. Otherwise, local changes to notes, labels and reminders will be detected and synced up.

Parameters:resync (bool) – Whether to resync data.
Raises:SyncException – If there is a consistency issue.
class gkeepapi.KeepAPI(auth=None)[source]

Low level Google Keep API client. Mimics the Android Google Keep app.

You probably want to use Keep instead.

changes(target_version=None, nodes=None, labels=None)[source]

Sync up (and down) all changes.

Parameters:
  • target_version (str) – The local change version.
  • nodes (List[dict]) – A list of nodes to sync up to the server.
  • labels (List[dict]) – A list of labels to sync up to the server.
Returns:

Description of all changes.

Return type:

dict

Raises:

APIException – If the server returns an error.

getAuth()

Get authentication details for this API.

Parameters:auth (APIAuth) – The auth object
send(**req_kwargs)

Send an authenticated request to a Google API. Automatically retries if the access token has expired.

Parameters:

**req_kwargs – Arbitrary keyword arguments to pass to Requests.

Returns:

The parsed JSON response.

Return type:

dict

Raises:
  • APIException – If the server returns an error.
  • LoginException – If login() has not been called.
setAuth(auth)

Set authentication details for this API.

Parameters:auth (APIAuth) – The auth object
class gkeepapi.MediaAPI(auth=None)[source]

Low level Google Media API client. Mimics the Android Google Keep app.

You probably want to use Keep instead.

get(blob)[source]

Get the canonical link to a media blob.

Parameters:blob (gkeepapi.node.Blob) – The blob.
Returns:A link to the media.
Return type:str
getAuth()

Get authentication details for this API.

Parameters:auth (APIAuth) – The auth object
send(**req_kwargs)

Send an authenticated request to a Google API. Automatically retries if the access token has expired.

Parameters:

**req_kwargs – Arbitrary keyword arguments to pass to Requests.

Returns:

The parsed JSON response.

Return type:

dict

Raises:
  • APIException – If the server returns an error.
  • LoginException – If login() has not been called.
setAuth(auth)

Set authentication details for this API.

Parameters:auth (APIAuth) – The auth object
class gkeepapi.RemindersAPI(auth=None)[source]

Low level Google Reminders API client. Mimics the Android Google Keep app.

You probably want to use Keep instead.

create(node_id, node_server_id, dtime)[source]

Create a new reminder.

Parameters:
  • node_id (str) – The note ID.
  • node_server_id (str) – The note server ID.
  • dtime (datetime.datetime) – The due date of this reminder.

Return: ???

Raises:APIException – If the server returns an error.
delete(node_server_id)[source]

Delete an existing reminder.

Parameters:node_server_id (str) – The note server ID.

Return: ???

Raises:APIException – If the server returns an error.
getAuth()

Get authentication details for this API.

Parameters:auth (APIAuth) – The auth object
history(storage_version)[source]

Get reminder changes.

Parameters:storage_version (str) – The local storage version.
Returns:???
Raises:APIException – If the server returns an error.
list(master=True)[source]

List current reminders.

Parameters:master (bool) –

???

Returns:???
Raises:APIException – If the server returns an error.
send(**req_kwargs)

Send an authenticated request to a Google API. Automatically retries if the access token has expired.

Parameters:

**req_kwargs – Arbitrary keyword arguments to pass to Requests.

Returns:

The parsed JSON response.

Return type:

dict

Raises:
  • APIException – If the server returns an error.
  • LoginException – If login() has not been called.
setAuth(auth)

Set authentication details for this API.

Parameters:auth (APIAuth) – The auth object
update()[source]

Sync up changes to reminders.

class gkeepapi.node.Annotation[source]

Bases: gkeepapi.node.Element

Note annotations base class.

save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.Blob(parent_id=None, **kwargs)[source]

Bases: gkeepapi.node.Node

Represents a Google Keep blob.

classmethod from_json(raw)[source]

Helper to construct a blob from a dict.

Parameters:raw (dict) – Raw blob representation.
Returns:A NodeBlob object or None.
Return type:NodeBlob
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.BlobType[source]

Bases: enum.Enum

Valid blob types.

Audio = 'AUDIO'

Audio

Drawing = 'DRAWING'

Drawing

Image = 'IMAGE'

Image

class gkeepapi.node.Category[source]

Bases: gkeepapi.node.Annotation

Represents a category annotation on a TopLevelNode.

category

Get the category.

Returns:The category.
Return type:gkeepapi.node.CategoryValue
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.CategoryValue[source]

Bases: enum.Enum

Valid note categories.

Books = 'BOOKS'

Books

Food = 'FOOD'

Food

Movies = 'MOVIES'

Movies

Music = 'MUSIC'

Music

Places = 'PLACES'

Places

Quotes = 'QUOTES'

Quotes

TV = 'TV'

TV

Travel = 'TRAVEL'

Travel

class gkeepapi.node.CheckedListItemsPolicyValue[source]

Bases: enum.Enum

Movement setting for checked list items.

Default = 'DEFAULT'

Default

Graveyard = 'GRAVEYARD'

Graveyard

class gkeepapi.node.ColorValue[source]

Bases: enum.Enum

Valid note colors.

Blue = 'BLUE'

Blue

Brown = 'BROWN'

Brown

DarkBlue = 'CERULEAN'

Dark blue

Gray = 'GRAY'

Gray

Green = 'GREEN'

Green

Orange = 'ORANGE'

Orange

Pink = 'PINK'

Pink

Purple = 'PURPLE'

Purple

Red = 'RED'

Red

Teal = 'TEAL'

Teal

White = 'DEFAULT'

White

Yellow = 'YELLOW'

Yellow

class gkeepapi.node.Context[source]

Bases: gkeepapi.node.Annotation

Represents a context annotation, which may contain other annotations.

all()[source]

Get all sub annotations.

Returns:Sub Annotations.
Return type:List[gkeepapi.node.Annotation]
dirty
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.Element[source]

Bases: object

Interface for elements that can be serialized and deserialized.

dirty

Get dirty state.

Returns:Whether this element is dirty.
Return type:str
load(raw)[source]

Unserialize from raw representation. (Wrapper)

Parameters:raw (dict) – Raw.
Raises:ParseException – If there was an error parsing data.
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.GraveyardStateValue[source]

Bases: enum.Enum

Visibility setting for the graveyard.

Collapsed = 'COLLAPSED'

Collapsed

Expanded = 'EXPANDED'

Expanded

class gkeepapi.node.Label[source]

Bases: gkeepapi.node.Element, gkeepapi.node.TimestampsMixin

Represents a label.

dirty
merged

Get last merge datetime.

Returns:Datetime.
Return type:datetime
name

Get the label name.

Returns:Label name.
Return type:str
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.List(**kwargs)[source]

Bases: gkeepapi.node.TopLevelNode

Represents a Google Keep list.

SORT_DELTA = 10000
add(text, checked=False, sort=None)[source]

Add a new item to the list.

Parameters:
checked

Get all checked listitems.

Returns:List items.
Return type:list[gkeepapi.node.ListItem]
items

Get all listitems.

Returns:List items.
Return type:list[gkeepapi.node.ListItem]
sort_items(key=<operator.attrgetter object>, reverse=False)[source]

Sort list items in place. By default, the items are alphabetized, but a custom function can be specified.

Parameters:
  • key (callable) – A filter function.
  • reverse (bool) – Whether to reverse the output.
classmethod sorted_items(items)[source]

Generate a list of sorted list items, taking into account parent items.

Parameters:items (list[gkeepapi.node.ListItem]) – Items to sort.
Returns:Sorted items.
Return type:list[gkeepapi.node.ListItem]
text
unchecked

Get all unchecked listitems.

Returns:List items.
Return type:list[gkeepapi.node.ListItem]
class gkeepapi.node.ListItem(parent_id=None, parent_server_id=None, super_list_item_id=None, **kwargs)[source]

Bases: gkeepapi.node.Node

Represents a Google Keep listitem. Interestingly enough, Note`s store their content in a single child :class:`ListItem.

add(text, checked=False, sort=None)[source]

Add a new sub item to the list. This item must already be attached to a list.

Parameters:
  • text (str) – The text.
  • checked (bool) – Whether this item is checked.
  • sort (int) – Item id for sorting.
checked

Get the checked state.

Returns:Whether this item is checked.
Return type:bool
dedent(node, dirty=True)[source]

Dedent an item. Does nothing if the target is not indented under this item.

Parameters:
  • node (gkeepapi.node.ListItem) – Item to dedent.
  • dirty (bool) – Whether this node should be marked dirty.
indent(node, dirty=True)[source]

Indent an item. Does nothing if the target has subitems.

Parameters:
  • node (gkeepapi.node.ListItem) – Item to indent.
  • dirty (bool) – Whether this node should be marked dirty.
indented

Get indentation state.

Returns:Whether this item is indented.
Return type:bool
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
subitems

Get subitems for this item.

Returns:Subitems.
Return type:list[gkeepapi.node.ListItem]
class gkeepapi.node.NewListItemPlacementValue[source]

Bases: enum.Enum

Target location to put new list items.

Bottom = 'BOTTOM'

Bottom

Top = 'TOP'

Top

class gkeepapi.node.Node(id_=None, type_=None, parent_id=None)[source]

Bases: gkeepapi.node.Element, gkeepapi.node.TimestampsMixin

Node base class.

append(node, dirty=True)[source]

Add a new child node.

Parameters:
  • node (gkeepapi.Node) – Node to add.
  • dirty (bool) – Whether this node should be marked dirty.
children

Get all children.

Returns:Children nodes.
Return type:list[gkeepapi.Node]
dirty
get(node_id)[source]

Get child node with the given ID.

Parameters:node_id (str) – The node ID.
Returns:Child node.
Return type:gkeepapi.Node
new

Get whether this node has been persisted to the server.

Returns:True if node is new.
Return type:bool
remove(node, dirty=True)[source]

Remove the given child node.

Parameters:
  • node (gkeepapi.Node) – Node to remove.
  • dirty (bool) – Whether this node should be marked dirty.
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
sort

Get the sort id.

Returns:Sort id.
Return type:int
text

Get the text value.

Returns:Text value.
Return type:str
version

Get the node version.

Returns:Version.
Return type:int
class gkeepapi.node.NodeAnnotations[source]

Bases: gkeepapi.node.Element

Represents the annotation container on a TopLevelNode.

all()[source]

Get all annotations.

Returns:Annotations.
Return type:List[gkeepapi.node.Annotation]
append(annotation)[source]

Add an annotation.

Parameters:annotation (gkeepapi.node.Annotation) – An Annotation object.
Returns:The Annotation.
Return type:gkeepapi.node.Annotation
category

Get the category.

Returns:The category or None.
Return type:Union[gkeepapi.node.CategoryValue, None]
dirty
classmethod from_json(raw)[source]

Helper to construct an annotation from a dict.

Parameters:raw (dict) – Raw annotation representation.
Returns:An Annotation object or None.
Return type:Node

Get all links.

Returns:A list of links.
Return type:list[gkeepapi.node.WebLink]
remove(annotation)[source]

Removes an annotation.

Parameters:annotation (gkeepapi.node.Annotation) – An Annotation object.
Returns:The Annotation.
Return type:gkeepapi.node.Annotation
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.NodeAudio[source]

Bases: gkeepapi.node.NodeBlob

Represents an audio blob.

length

Get length of the audio clip. :returns: Audio length. :rtype: int

save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.NodeBlob(type_=None)[source]

Bases: gkeepapi.node.Element

Represents a blob descriptor.

save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.NodeCollaborators[source]

Bases: gkeepapi.node.Element

Represents the collaborators on a TopLevelNode.

add(email)[source]

Add a collaborator.

Parameters:str – Collaborator email address.
all()[source]

Get all collaborators.

Returns:Collaborators.
Return type:List[str]
load(collaborators_raw, requests_raw)[source]

Unserialize from raw representation. (Wrapper)

Parameters:raw (dict) – Raw.
Raises:ParseException – If there was an error parsing data.
remove(email)[source]

Remove a Collaborator.

Parameters:str – Collaborator email address.
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.NodeDrawing[source]

Bases: gkeepapi.node.NodeBlob

Represents a drawing blob.

extracted_text

Get text extracted from image :returns: Extracted text. :rtype: str

save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.NodeDrawingInfo[source]

Bases: gkeepapi.node.Element

Represents information about a drawing blob.

save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.NodeImage[source]

Bases: gkeepapi.node.NodeBlob

Represents an image blob.

byte_size

Get size of image in bytes. :returns: Image byte size. :rtype: int

extracted_text

Get text extracted from image :returns: Extracted text. :rtype: str

height

Get height of image. :returns: Image height. :rtype: int

save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
url

Get a url to the image. :returns: Image url. :rtype: str

width

Get width of image. :returns: Image width. :rtype: int

class gkeepapi.node.NodeLabels[source]

Bases: gkeepapi.node.Element

Represents the labels on a TopLevelNode.

add(label)[source]

Add a label.

Parameters:label (gkeepapi.node.Label) – The Label object.
all()[source]

Get all labels.

Returns:Labels.
Return type:List[gkeepapi.node.Label]
get(label_id)[source]

Get a label by ID.

Parameters:label_id (str) – The label ID.
remove(label)[source]

Remove a label.

Parameters:label (gkeepapi.node.Label) – The Label object.
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.NodeSettings[source]

Bases: gkeepapi.node.Element

Represents the settings associated with a TopLevelNode.

checked_listitems_policy

Get the policy for checked listitems.

Returns:Policy.
Return type:gkeepapi.node.CheckedListItemsPolicyValue
graveyard_state

Get the visibility state for the list graveyard.

Returns:Visibility.
Return type:gkeepapi.node.GraveyardStateValue
new_listitem_placement

Get the default location to insert new listitems.

Returns:Placement.
Return type:gkeepapi.node.NewListItemPlacementValue
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
class gkeepapi.node.NodeTimestamps(create_time=None)[source]

Bases: gkeepapi.node.Element

Represents the timestamps associated with a TopLevelNode.

TZ_FMT = '%Y-%m-%dT%H:%M:%S.%fZ'
created

Get the creation datetime.

Returns:Datetime.
Return type:datetime.datetime
deleted

Get the deletion datetime.

Returns:Datetime.
Return type:datetime.datetime
classmethod dt_to_str(dt)[source]

Convert a datetime to a str.

Returns:Datetime string.
Return type:str
edited

Get the user edited datetime.

Returns:Datetime.
Return type:datetime.datetime
classmethod int_to_dt(tz)[source]

Convert a unix timestamp into an object.

Params:
ts (int): Unix timestamp.
Returns:Datetime.
Return type:datetime.datetime
classmethod int_to_str(tz)[source]

Convert a unix timestamp to a str.

Returns:Datetime string.
Return type:str
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
classmethod str_to_dt(tzs)[source]

Convert a datetime string into an object.

Params:
tsz (str): Datetime string.
Returns:Datetime.
Return type:datetime.datetime
trashed

Get the move-to-trash datetime.

Returns:Datetime.
Return type:datetime.datetime
updated

Get the updated datetime.

Returns:Datetime.
Return type:datetime.datetime
class gkeepapi.node.NodeType[source]

Bases: enum.Enum

Valid note types.

Blob = 'BLOB'

A blob (attachment)

List = 'LIST'

A List

ListItem = 'LIST_ITEM'

A List item

Note = 'NOTE'

A Note

class gkeepapi.node.Note(**kwargs)[source]

Bases: gkeepapi.node.TopLevelNode

Represents a Google Keep note.

text
class gkeepapi.node.RoleValue[source]

Bases: enum.Enum

Collaborator role type.

Owner = 'O'

Note owner.

User = 'W'

Note collaborator.

class gkeepapi.node.Root[source]

Bases: gkeepapi.node.Node

Internal root node.

ID = 'root'
dirty
class gkeepapi.node.ShareRequestValue[source]

Bases: enum.Enum

Collaborator change type.

Add = 'WR'

Grant access.

Remove = 'RM'

Remove access.

class gkeepapi.node.SuggestValue[source]

Bases: enum.Enum

Valid task suggestion categories.

GroceryItem = 'GROCERY_ITEM'

Grocery item

class gkeepapi.node.TaskAssist[source]

Bases: gkeepapi.node.Annotation

Unknown.

save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
suggest

Get the suggestion.

Returns:The suggestion.
Return type:str
class gkeepapi.node.TimestampsMixin[source]

Bases: object

A mixin to add methods for updating timestamps.

delete()[source]

Mark the item as deleted.

deleted

Get the deleted state.

Returns:Whether this item is deleted.
Return type:bool
touch(edited=False)[source]

Mark the node as dirty.

Parameters:edited (bool) – Whether to set the edited time.
trash()[source]

Mark the item as trashed.

trashed

Get the trashed state.

Returns:Whether this item is trashed.
Return type:bool
undelete()[source]

Mark the item as undeleted.

untrash()[source]

Mark the item as untrashed.

class gkeepapi.node.TopLevelNode(**kwargs)[source]

Bases: gkeepapi.node.Node

Top level node base class.

archived

Get the archive state.

Returns:Whether this node is archived.
Return type:bool
audio
blobs

Get all media blobs.

Returns:Media blobs.
Return type:list[gkeepapi.node.Blob]
color

Get the node color.

Returns:Color.
Return type:gkeepapi.node.Color
dirty
drawings
images
pinned

Get the pin state.

Returns:Whether this node is pinned.
Return type:bool
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
title

Get the title.

Returns:Title.
Return type:str
url

Get the url for this node.

Returns:Google Keep url.
Return type:str

Bases: gkeepapi.node.Annotation

Represents a link annotation on a TopLevelNode.

description

Get the link description.

Returns:The link description.
Return type:str
image_url

Get the link image url.

Returns:The image url or None.
Return type:str
provenance_url

Get the provenance url.

Returns:The provenance url.
Return type:url
save(clean=True)[source]

Serialize into raw representation. Clears the dirty bit by default.

Parameters:clean (bool) – Whether to clear the dirty bit.
Returns:Raw.
Return type:dict
title

Get the link title.

Returns:The link title.
Return type:str
url

Get the link url.

Returns:The link url.
Return type:str
gkeepapi.node.from_json(raw)[source]

Helper to construct a node from a dict.

Parameters:raw (dict) – Raw node representation.
Returns:A Node object or None.
Return type:Node

Module contents

class gkeepapi.API(base_url, auth=None)[source]

Bases: object

Base API wrapper

RETRY_CNT = 2
getAuth()[source]

Get authentication details for this API.

Parameters:auth (APIAuth) – The auth object
send(**req_kwargs)[source]

Send an authenticated request to a Google API. Automatically retries if the access token has expired.

Parameters:

**req_kwargs – Arbitrary keyword arguments to pass to Requests.

Returns:

The parsed JSON response.

Return type:

dict

Raises:
  • APIException – If the server returns an error.
  • LoginException – If login() has not been called.
setAuth(auth)[source]

Set authentication details for this API.

Parameters:auth (APIAuth) – The auth object
class gkeepapi.APIAuth(scopes)[source]

Bases: object

Authentication token manager

getAuthToken()[source]

Gets the auth token.

Returns:The auth token.
Return type:Union[str, None]
getDeviceId()[source]

Gets the device id.

Returns:The device id.
Return type:str
getEmail()[source]

Gets the account email.

Returns:The account email.
Return type:str
getMasterToken()[source]

Gets the master token.

Returns:The account master token.
Return type:str
load(email, master_token, device_id)[source]

Authenticate to Google with the provided master token.

Parameters:
  • email (str) – The account to use.
  • master_token (str) – The master token.
  • device_id (str) – An identifier for this client.
Raises:

LoginException – If there was a problem logging in.

login(email, password, device_id)[source]

Authenticate to Google with the provided credentials.

Parameters:
  • email (str) – The account to use.
  • password (str) – The account password.
  • device_id (str) – An identifier for this client.
Raises:

LoginException – If there was a problem logging in.

logout()[source]

Log out of the account.

refresh()[source]

Refresh the OAuth token.

Returns:The auth token.
Return type:string
Raises:LoginException – If there was a problem refreshing the OAuth token.
setDeviceId(device_id)[source]

Sets the device id.

Parameters:device_id (str) – The device id.
setEmail(email)[source]

Gets the account email.

Parameters:email (str) – The account email.
setMasterToken(master_token)[source]

Sets the master token. This is useful if you’d like to authenticate with the API without providing your username & password. Do note that the master token has full access to your account.

Parameters:master_token (str) – The account master token.
class gkeepapi.Keep[source]

Bases: object

High level Google Keep client.

Stores a local copy of the Keep node tree. To start, first login:

keep.login('...', '...')

Individual Notes can be retrieved by id:

some_note = keep.get('some_id')

New Notes can be created:

new_note = keep.createNote()

These Notes can then be modified:

some_note.text = 'Test'
new_note.text = 'Text'

These changes are automatically detected and synced up with:

keep.sync()
OAUTH_SCOPES = 'oauth2:https://www.googleapis.com/auth/memento https://www.googleapis.com/auth/reminders'
add(node)[source]

Register a top level node (and its children) for syncing up to the server. There’s no need to call this for nodes created by createNote() or createList() as they are automatically added.

LoginException: If login() has not been called.
Parameters:node (gkeepapi.node.Node) – The node to sync.
Raises:Invalid – If the parent node is not found.
all()[source]

Get all Notes.

Returns:Notes
Return type:List[gkeepapi.node.TopLevelNode]
createLabel(name)[source]

Create a new label.

Parameters:name (str) – Label name.
Returns:The new label.
Return type:gkeepapi.node.Label
Raises:LabelException – If the label exists.
createList(title=None, items=None)[source]

Create a new list and populate it. Any changes to the note will be uploaded when sync() is called.

Parameters:
  • title (str) – The title of the list.
  • items (List[(str, bool)]) – A list of tuples. Each tuple represents the text and checked status of the listitem.
Returns:

The new list.

Return type:

gkeepapi.node.List

createNote(title=None, text=None)[source]

Create a new managed note. Any changes to the note will be uploaded when sync() is called.

Parameters:
  • title (str) – The title of the note.
  • text (str) – The text of the note.
Returns:

The new note.

Return type:

gkeepapi.node.List

deleteLabel(label_id)[source]

Deletes a label.

Parameters:label_id (str) – Label id.
dump()[source]

Serialize note data.

Parameters:state (dict) – Serialized state to load.
find(query=None, func=None, labels=None, colors=None, pinned=None, archived=None, trashed=False)[source]

Find Notes based on the specified criteria.

Parameters:
  • query (Union[_sre.SRE_Pattern, str, None]) – A str or regular expression to match against the title and text.
  • func (Union[callable, None]) – A filter function.
  • labels (Union[List[str], None]) – A list of label ids or objects to match. An empty list matches notes with no labels.
  • colors (Union[List[str], None]) – A list of colors to match.
  • pinned (Union[bool, None]) – Whether to match pinned notes.
  • archived (Union[bool, None]) – Whether to match archived notes.
  • trashed (Union[bool, None]) – Whether to match trashed notes.
Returns:

Results.

Return type:

Generator[gkeepapi.node.TopLevelNode]

findLabel(query, create=False)[source]

Find a label with the given name.

Parameters:
  • name (Union[_sre.SRE_Pattern, str]) – A str or regular expression to match against the name.
  • create (bool) – Whether to create the label if it doesn’t exist (only if name is a str).
Returns:

The label.

Return type:

Union[gkeepapi.node.Label, None]

get(node_id)[source]

Get a note with the given ID.

Parameters:node_id (str) – The note ID.
Returns:The Note or None if not found.
Return type:gkeepapi.node.TopLevelNode
getLabel(label_id)[source]

Get an existing label.

Parameters:label_id (str) – Label id.
Returns:The label.
Return type:Union[gkeepapi.node.Label, None]
getMasterToken()[source]

Get master token for resuming.

Returns:The master token.
Return type:str
getMediaLink(blob)[source]

Get the canonical link to media.

Parameters:blob (gkeepapi.node.Blob) – The media resource.
Returns:A link to the media.
Return type:str
labels()[source]

Get all labels.

Returns:Labels
Return type:List[gkeepapi.node.Label]
load(auth, state=None, sync=True)[source]

Authenticate to Google with a prepared authentication object & sync. :param auth: Authentication object. :type auth: APIAuth :param state: Serialized state to load. :type state: dict

Raises:LoginException – If there was a problem logging in.
login(username, password, state=None, sync=True, device_id=None)[source]

Authenticate to Google with the provided credentials & sync.

Parameters:
  • email (str) – The account to use.
  • password (str) – The account password.
  • state (dict) – Serialized state to load.
Raises:

LoginException – If there was a problem logging in.

restore(state)[source]

Unserialize saved note data.

Parameters:state (dict) – Serialized state to load.
resume(email, master_token, state=None, sync=True, device_id=None)[source]

Authenticate to Google with the provided master token & sync.

Parameters:
  • email (str) – The account to use.
  • master_token (str) – The master token.
  • state (dict) – Serialized state to load.
Raises:

LoginException – If there was a problem logging in.

sync(resync=False)[source]

Sync the local Keep tree with the server. If resyncing, local changes will be destroyed. Otherwise, local changes to notes, labels and reminders will be detected and synced up.

Parameters:resync (bool) – Whether to resync data.
Raises:SyncException – If there is a consistency issue.
class gkeepapi.KeepAPI(auth=None)[source]

Bases: gkeepapi.API

Low level Google Keep API client. Mimics the Android Google Keep app.

You probably want to use Keep instead.

API_URL = 'https://www.googleapis.com/notes/v1/'
changes(target_version=None, nodes=None, labels=None)[source]

Sync up (and down) all changes.

Parameters:
  • target_version (str) – The local change version.
  • nodes (List[dict]) – A list of nodes to sync up to the server.
  • labels (List[dict]) – A list of labels to sync up to the server.
Returns:

Description of all changes.

Return type:

dict

Raises:

APIException – If the server returns an error.

class gkeepapi.MediaAPI(auth=None)[source]

Bases: gkeepapi.API

Low level Google Media API client. Mimics the Android Google Keep app.

You probably want to use Keep instead.

API_URL = 'https://keep.google.com/media/v2/'
get(blob)[source]

Get the canonical link to a media blob.

Parameters:blob (gkeepapi.node.Blob) – The blob.
Returns:A link to the media.
Return type:str
class gkeepapi.RemindersAPI(auth=None)[source]

Bases: gkeepapi.API

Low level Google Reminders API client. Mimics the Android Google Keep app.

You probably want to use Keep instead.

API_URL = 'https://www.googleapis.com/reminders/v1internal/reminders/'
create(node_id, node_server_id, dtime)[source]

Create a new reminder.

Parameters:
  • node_id (str) – The note ID.
  • node_server_id (str) – The note server ID.
  • dtime (datetime.datetime) – The due date of this reminder.

Return: ???

Raises:APIException – If the server returns an error.
delete(node_server_id)[source]

Delete an existing reminder.

Parameters:node_server_id (str) – The note server ID.

Return: ???

Raises:APIException – If the server returns an error.
history(storage_version)[source]

Get reminder changes.

Parameters:storage_version (str) – The local storage version.
Returns:???
Raises:APIException – If the server returns an error.
list(master=True)[source]

List current reminders.

Parameters:master (bool) –

???

Returns:???
Raises:APIException – If the server returns an error.
update()[source]

Sync up changes to reminders.