Annotations

Methods for drawing down, editing and creating annotations on documents.

AnnotationClient

class documentcloud.annotations.AnnotationClient

The annotation client gives access to retrieval and creation of notes on a given document. It is accessed as doc_obj.annotations. The annotation client supports iteration, length and indexing so that it can be used directly as a sequence of the existing notes.

>>> for note in doc_obj.annotations:
>>>     print(note)
>>> note_count = len(doc_obj.annotations)
>>> second_note = doc_obj.annotations[1]

all(self, **params): An alias for list().

create(self, title, page_number, content='', access='private', x1=None, y1=None, x2=Non2, y2=Non2): Create a new annotation on this document. You may leave all coordinates blank to specify a full page note, or you must specify all documents in percentage of the page, a number between 0 and 1.

get(id_): Return the annotation with the provided identifier.

list(self, **params): Return a list of all annotations on this document, possibly filtered by the given parameters. Please see the full API documentation for available parameters.

Annotation

class documentcloud.annotations.Annotation

A note left on a document.

put(): Save changes to an annotation back to DocumentCloud. You must be authorized to make these changes. Only the access, content, page_number, title, x1, x2, y1, and y2, attributes may be edited.

delete(): Delete an annotation from DocumentCloud. You must be authorized to make these changes.

save(): An alias for put() that saves changes back to DocumentCloud.

access: The privacy level of the annotation within the DocumentCloud system. It will be public, private, or organization. organization will extend access to the note to any user with edit access to the document the note is attached to, including project collaborators.

content: Space for a lengthy text block that will be published below the highlighted text in the DocumentCloud design.

created_at: The date and time this annotation was created.

description: Alias for content.

edit_access: A boolean indicating whether or not you have the ability to save this annotation.

id: The unique identifer of the annotation in DocumentCloud’s system.

location: Deprecated since version 2.0.0: The location of where the annotation appears on the document’s page. Defined by documentcloud.annotations.Location.

organization: The ID of the organization which owns this note.

page: The page where the annotation appears.

page_number: Alias for page.

title: The name of the annotation, which appears in the table of contents and above the highlighted text when published by DocumentCloud.

updated_at: The date and time of when this annotation was last updated.

user: The ID of the user who created this annotation.

x1

x2

y1

y2: The coordinates for the annotation, in percentage of the page. They will be floats between 0 and 1. x1 corresponds to the left, x2 to the right, y1 to the top, and y2 to the bottom coordinate.

Location

class documentcloud.annotations.Location

The location where an documentcloud.annotations.Annotation is placed within a document. The coordinates are in pixels, normalized for a 700 pixel width page.

Deprecated since version 2.0.0: The new API directly exposes the top level attributes documentcloud.annotations.Annotation.x1, documentcloud.annotations.Annotation.x2, documentcloud.annotations.Annotation.y1, and documentcloud.annotations.Annotation.y2, which are in percentage of page. New code should use those instead of the location object.

bottom: The value of the bottom edge of an annotation.

left: The value of the left edge of an annotation.

right: The value of the right edge of an annotation.

top: The value of the top edge of an annotation.