Package google.cloud.documentai.v1beta3

Endpoint requirement: For the v1beta2 and v1beta3 API versions you must specify a region-specific endpoints when making requests:

• https://us-documentai.googleapis.com/v1beta2/projects/PROJECT_ID/locations/us/documents:method
• https://eu-documentai.googleapis.com/v1beta2/projects/PROJECT_ID/locations/eu/documents:method
• https://us-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/us/processors/PROCESSOR_ID:method
• https://eu-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/eu/processors/PROCESSOR_ID:method

Index

• DocumentProcessorService (interface)
• BatchProcessMetadata (message)
• BatchProcessMetadata.IndividualProcessStatus (message)
• BatchProcessMetadata.State (enum)
• BatchProcessRequest (message)
• BatchProcessRequest.BatchInputConfig (message)
• BatchProcessRequest.BatchOutputConfig (message)
• BatchProcessResponse (message)
• BoundingPoly (message)
• Document (message)
• Document.Entity (message)
• Document.Entity.NormalizedValue (message)
• Document.EntityRelation (message)
• Document.Page (message)
• Document.Page.Block (message)
• Document.Page.DetectedLanguage (message)
• Document.Page.Dimension (message)
• Document.Page.FormField (message)
• Document.Page.Image (message)
• Document.Page.Layout (message)
• Document.Page.Layout.Orientation (enum)
• Document.Page.Line (message)
• Document.Page.Matrix (message)
• Document.Page.Paragraph (message)
• Document.Page.Table (message)
• Document.Page.Table.TableCell (message)
• Document.Page.Table.TableRow (message)
• Document.Page.Token (message)
• Document.Page.Token.DetectedBreak (message)
• Document.Page.Token.DetectedBreak.Type (enum)
• Document.Page.VisualElement (message)
• Document.PageAnchor (message)
• Document.PageAnchor.PageRef (message)
• Document.PageAnchor.PageRef.LayoutType (enum)
• Document.Provenance (message)
• Document.Provenance.OperationType (enum)
• Document.Provenance.Parent (message)
• Document.Revision (message)
• Document.Revision.HumanReview (message)
• Document.ShardInfo (message)
• Document.Style (message)
• Document.Style.FontSize (message)
• Document.TextAnchor (message)
• Document.TextAnchor.TextSegment (message)
• Document.TextChange (message)
• Document.Translation (message)
• NormalizedVertex (message)
• ProcessRequest (message)
• ProcessResponse (message)
• ReviewDocumentOperationMetadata (message)
• ReviewDocumentOperationMetadata.State (enum)
• ReviewDocumentRequest (message)
• ReviewDocumentResponse (message)
• Vertex (message)

DocumentProcessorService

Service to call Cloud DocumentAI to process documents according to the processor's definition. Processors are built using state-of-the-art Google AI such as natural language, computer vision, and translation to extract structured information from unstructured or semi-structured documents.

BatchProcessDocuments
rpc BatchProcessDocuments(BatchProcessRequest) returns (Operation) LRO endpoint to batch process many documents. The output is written to Cloud Storage as JSON in the [Document] format. Authorization Scopes Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform For more information, see the Authentication Overview.

ProcessDocument
rpc ProcessDocument(ProcessRequest) returns (ProcessResponse) Processes a single document. Authorization Scopes Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform For more information, see the Authentication Overview.

ReviewDocument
rpc ReviewDocument(ReviewDocumentRequest) returns (Operation) Send a document for Human Review. The input document should be processed by the specified processor. Authorization Scopes Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform For more information, see the Authentication Overview.

BatchProcessMetadata

The long running operation metadata for batch process method.

Fields
state	State The state of the current batch processing.
state_message	string A message providing more details about the current state of processing. For example, the error message if the operation is failed.
create_time	Timestamp The creation time of the operation.
update_time	Timestamp The last update time of the operation.
individual_process_statuses[]	IndividualProcessStatus The list of response details of each document.

IndividualProcessStatus

The status of a each individual document in the batch process.

Fields
input_gcs_source	string The source of the document, same as the [input_gcs_source] field in the request when the batch process started. The batch process is started by take snapshot of that document, since a user can move or change that document during the process.
status	Status The status of the processing of the document.
output_gcs_destination	string The output_gcs_destination (in the request as 'output_gcs_destination') of the processed document if it was successful, otherwise empty.
human_review_operation	string The name of the operation triggered by the processed document. If the human review process is not triggered, this field will be empty. It has the same response type and metadata as the long running operation returned by ReviewDocument method.

State

Possible states of the batch processing operation.

Enums
STATE_UNSPECIFIED	The default value. This value is used if the state is omitted.
WAITING	Request operation is waiting for scheduling.
RUNNING	Request is being processed.
SUCCEEDED	The batch processing completed successfully.
CANCELLING	The batch processing was being cancelled.
CANCELLED	The batch processing was cancelled.
FAILED	The batch processing has failed.

BatchProcessRequest

Request message for batch process document method.

Fields
name	string Required. The processor resource name. Authorization requires the following IAM permission on the specified resource name: documentai.processors.processBatch
input_configs[]	BatchInputConfig The input config for each single document in the batch process.
output_config	BatchOutputConfig The overall output config for batch process.

BatchInputConfig

The message for input config in batch process.

Fields
gcs_source	string The Cloud Storage location as the source of the document.
mime_type	string Mimetype of the input. If the input is a raw document, the supported mimetypes are application/pdf, image/tiff, and image/gif. If the input is a [Document] proto, the type should be application/json.

BatchOutputConfig

The message for output config in batch process.

Fields
gcs_destination	string The output Cloud Storage directory to put the processed documents.

BatchProcessResponse

Response message for batch process document method.

BoundingPoly

A bounding polygon for the detected image annotation.

Fields
vertices[]	Vertex The bounding polygon vertices.
normalized_vertices[]	NormalizedVertex The bounding polygon normalized vertices.

Document

Document represents the canonical document resource in Document Understanding AI. It is an interchange format that provides insights into documents and allows for collaboration between users and Document Understanding AI to iterate and optimize for quality.

Fields
mime_type	string An IANA published MIME type (also referred to as media type). For more information, see https://www.iana.org/assignments/media-types/media-types.xhtml.
text	string UTF-8 encoded text in reading order from the document.
text_styles[]	Style Styles for the Document.text.
pages[]	Page Visual page layout for the Document.
entities[]	Entity A list of entities detected on Document.text. For document shards, entities in this list may cross shard boundaries.
entity_relations[]	EntityRelation Relationship among Document.entities.
translations[]	Translation A list of translations on Document.text. For document shards, translations in this list may cross shard boundaries.
text_changes[]	TextChange A list of text corrections made to [Document.text]. This is usually used for annotating corrections to OCR mistakes. Text changes for a given revision may not overlap with each other.
shard_info	ShardInfo Information about the sharding if this document is sharded part of a larger document. If the document is not sharded, this message is not specified.
error	Status Any error that occurred while processing this document.
revisions[]	Revision Revision history of this document.
Union field source. Original source document from the user. source can be only one of the following:
uri	string Currently supports Google Cloud Storage URI of the form gs://bucket_name/object_name. Object versioning is not supported. See Google Cloud Storage Request URIs for more info.
content	bytes Inline document content, represented as a stream of bytes. Note: As with all bytes fields, protobuffers use a pure binary representation, whereas JSON representations use base64.

Entity

A phrase in the text that is a known entity type, such as a person, an organization, or location.

Fields
text_anchor	TextAnchor Provenance of the entity. Text anchor indexing into the Document.text.
type	string Entity type from a schema e.g. Address.
mention_text	string Text value in the document e.g. 1600 Amphitheatre Pkwy.
mention_id	string Deprecated. Use id field instead.
confidence	float Optional. Confidence of detected Schema entity. Range [0, 1].
page_anchor	PageAnchor Optional. Represents the provenance of this entity wrt. the location on the page where it was found.
id	string Optional. Canonical id. This will be a unique value in the entity list for this document.
normalized_value	NormalizedValue Optional. Normalized entity value. Absent if the extracted value could not be converted or the type (e.g. address) is not supported for certain parsers. This field is also only populated for certain supported document types.
properties[]	Entity Optional. Entities can be nested to form a hierarchical data structure representing the content in the document.
provenance	Provenance Optional. The history of this annotation.
redacted	bool Optional. Whether the entity will be redacted for de-identification purposes.

NormalizedValue

Parsed and normalized entity value.

Fields
text	string Required. Normalized entity value stored as a string. This field is populated for supported document type (e.g. Invoice). For some entity types, one of respective 'structured_value' fields may also be populated. Money/Currency type (money_value) is in the ISO 4217 text format. Date type (date_value) is in the ISO 8601 text format. Datetime type (datetime_value) is in the ISO 8601 text format.
Union field structured_value. Structured entity value. Must match entity type defined in schema if known. If this field is present, the 'text' field is still populated. structured_value can be only one of the following:
money_value	Money Money value. See also: https: //github.com/googleapis/googleapis/blob/ // master/google/type/money.proto
date_value	Date Date value. Includes year, month, day. See also: https: //github.com/googleapis/googleapis/blob/master/google/type/date.proto
datetime_value	DateTime DateTime value. Includes date, time, and timezone. See also: https: //github.com/googleapis/googleapis/blob/ // master/google/type/datetime.proto
address_value	PostalAddress Postal address. See also: https: //github.com/googleapis/googleapis/blob/ // master/google/type/postal_address.proto

EntityRelation

Relationship between Entities.

Fields
subject_id	string Subject entity id.
object_id	string Object entity id.
relation	string Relationship description.

Page

A page in a Document.

Fields
page_number	int32 1-based index for current Page in a parent Document. Useful when a page is taken out of a Document for individual processing.
image	Image Rendered image for this page. This image is preprocessed to remove any skew, rotation, and distortions such that the annotation bounding boxes can be upright and axis-aligned.
transforms[]	Matrix Transformation matrices that were applied to the original document image to produce Page.image.
dimension	Dimension Physical dimension of the page.
layout	Layout Layout for the page.
detected_languages[]	DetectedLanguage A list of detected languages together with confidence.
blocks[]	Block A list of visually detected text blocks on the page. A block has a set of lines (collected into paragraphs) that have a common line-spacing and orientation.
paragraphs[]	Paragraph A list of visually detected text paragraphs on the page. A collection of lines that a human would perceive as a paragraph.
lines[]	Line A list of visually detected text lines on the page. A collection of tokens that a human would perceive as a line.
tokens[]	Token A list of visually detected tokens on the page.
visual_elements[]	VisualElement A list of detected non-text visual elements e.g. checkbox, signature etc. on the page.
tables[]	Table A list of visually detected tables on the page.
form_fields[]	FormField A list of visually detected form fields on the page.

Block

A block has a set of lines (collected into paragraphs) that have a common line-spacing and orientation.

Fields
layout	Layout Layout for Block.
detected_languages[]	DetectedLanguage A list of detected languages together with confidence.
provenance	Provenance The history of this annotation.

DetectedLanguage

Detected language for a structural component.

Fields
language_code	string The BCP-47 language code, such as "en-US" or "sr-Latn". For more information, see www.unicode.org/reports/tr35/#Unicode_locale_identifier.
confidence	float Confidence of detected language. Range [0, 1].

Dimension

Dimension for the page.

Fields
width	float Page width.
height	float Page height.
unit	string Dimension unit.

FormField

A form field detected on the page.

Fields
field_name	Layout Layout for the FormField name. e.g. Address, Email, Grand total, Phone number, etc.
field_value	Layout Layout for the FormField value.
name_detected_languages[]	DetectedLanguage A list of detected languages for name together with confidence.
value_detected_languages[]	DetectedLanguage A list of detected languages for value together with confidence.
value_type	string If the value is non-textual, this field represents the type. Current valid values are: - blank (this indicates the field_value is normal text) - "unfilled_checkbox" - "filled_checkbox"

Image

Rendered image contents for this page.

Fields
content	bytes Raw byte content of the image.
mime_type	string Encoding mime type for the image.
width	int32 Width of the image in pixels.
height	int32 Height of the image in pixels.

Layout

Visual element describing a layout unit on a page.

Fields
text_anchor	TextAnchor Text anchor indexing into the Document.text.
confidence	float Confidence of the current Layout within context of the object this layout is for. e.g. confidence can be for a single token, a table, a visual element, etc. depending on context. Range [0, 1].
bounding_poly	BoundingPoly The bounding polygon for the Layout.
orientation	Orientation Detected orientation for the Layout.

Orientation

Detected human reading orientation.

Enums
ORIENTATION_UNSPECIFIED	Unspecified orientation.
PAGE_UP	Orientation is aligned with page up.
PAGE_RIGHT	Orientation is aligned with page right. Turn the head 90 degrees clockwise from upright to read.
PAGE_DOWN	Orientation is aligned with page down. Turn the head 180 degrees from upright to read.
PAGE_LEFT	Orientation is aligned with page left. Turn the head 90 degrees counterclockwise from upright to read.

Line

A collection of tokens that a human would perceive as a line. Does not cross column boundaries, can be horizontal, vertical, etc.

Fields
layout	Layout Layout for Line.
detected_languages[]	DetectedLanguage A list of detected languages together with confidence.
provenance	Provenance The history of this annotation.

Matrix

Representation for transformation matrix, intended to be compatible and used with OpenCV format for image manipulation.

Fields
rows	int32 Number of rows in the matrix.
cols	int32 Number of columns in the matrix.
type	int32 This encodes information about what data type the matrix uses. For example, 0 (CV_8U) is an unsigned 8-bit image. For the full list of OpenCV primitive data types, please refer to https://docs.opencv.org/4.3.0/d1/d1b/group__core__hal__interface.html
data	bytes The matrix data.

Paragraph

A collection of lines that a human would perceive as a paragraph.

Fields
layout	Layout Layout for Paragraph.
detected_languages[]	DetectedLanguage A list of detected languages together with confidence.
provenance	Provenance The history of this annotation.

Table

A table representation similar to HTML table structure.

Fields
layout	Layout Layout for Table.
header_rows[]	TableRow Header rows of the table.
body_rows[]	TableRow Body rows of the table.
detected_languages[]	DetectedLanguage A list of detected languages together with confidence.

TableCell

A cell representation inside the table.

Fields
layout	Layout Layout for TableCell.
row_span	int32 How many rows this cell spans.
col_span	int32 How many columns this cell spans.
detected_languages[]	DetectedLanguage A list of detected languages together with confidence.

TableRow

A row of table cells.

Fields
cells[]	TableCell Cells that make up this row.

Token

A detected token.

Fields
layout	Layout Layout for Token.
detected_break	DetectedBreak Detected break at the end of a Token.
detected_languages[]	DetectedLanguage A list of detected languages together with confidence.
provenance	Provenance The history of this annotation.

DetectedBreak

Detected break at the end of a Token.

Fields
type	Type Detected break type.

Type

Enum to denote the type of break found.

Enums
TYPE_UNSPECIFIED	Unspecified break type.
SPACE	A single whitespace.
WIDE_SPACE	A wider whitespace.
HYPHEN	A hyphen that indicates that a token has been split across lines.

VisualElement

Detected non-text visual elements e.g. checkbox, signature etc. on the page.

Fields
layout	Layout Layout for VisualElement.
type	string Type of the VisualElement.
detected_languages[]	DetectedLanguage A list of detected languages together with confidence.

PageAnchor

Referencing the visual context of the entity in the Document.pages. Page anchors can be cross-page, consist of multiple bounding polygons and optionally reference specific layout element types.

Fields
page_refs[]	PageRef One or more references to visual page elements

PageRef

Represents a weak reference to a page element within a document.

Fields
page	int64 Required. Index into the Document.pages element
layout_type	LayoutType Optional. The type of the layout element that is being referenced if any.
layout_id (deprecated)	string This item is deprecated! Optional. Deprecated. Use PageRef.bounding_poly instead.
bounding_poly	BoundingPoly Optional. Identifies the bounding polygon of a layout element on the page.

LayoutType

The type of layout that is being referenced.

Enums
LAYOUT_TYPE_UNSPECIFIED	Layout Unspecified.
BLOCK	References a Page.blocks element.
PARAGRAPH	References a Page.paragraphs element.
LINE	References a Page.lines element.
TOKEN	References a Page.tokens element.
VISUAL_ELEMENT	References a Page.visual_elements element.
TABLE	Refrrences a Page.tables element.
FORM_FIELD	References a Page.form_fields element.

Provenance

Structure to identify provenance relationships between annotations in different revisions.

Fields
revision	int32 The index of the revision that produced this element.
id	int32 The Id of this operation. Needs to be unique within the scope of the revision.
parents[]	Parent References to the original elements that are replaced.
type	OperationType The type of provenance operation.

OperationType

If a processor or agent does an explicit operation on existing elements.

Enums
OPERATION_TYPE_UNSPECIFIED	Operation type unspecified.
ADD	Add an element. Implicit if no parents are set for the provenance.
REMOVE	The element is removed. No parents should be set.
REPLACE	Explicitly replaces the element(s) identified by parents.
EVAL_REQUESTED	Element is requested for human review.
EVAL_APPROVED	Element is review and approved at human review, confidence will be set to 1.0

Parent

Structure for referencing parent provenances. When an element replaces one of more other elements parent references identify the elements that are replaced.

Fields
revision	int32 The index of the [Document.revisions] identifying the parent revision.
id	int32 The id of the parent provenance.

Revision

Contains past or forward revisions of this document.

Fields
id	string Id of the revision. Unique within the context of the document.
parent[]	int32 The revisions that this revision is based on. This can include one or more parent (when documents are merged.) This field represents the index into the revisions field.
create_time	Timestamp The time that the revision was created.
human_review	HumanReview Human Review information of this revision.
Union field source. Who/what made the change source can be only one of the following:
agent	string If the change was made by a person specify the name or id of that person.
processor	string If the annotation was made by processor identify the processor by its resource name.

HumanReview

Human Review information of the document.

Fields
state	string Human review state. e.g. requested, succeeded, rejected.
state_message	string A message providing more details about the current state of processing. For example, the rejection reason when the state is rejected.

ShardInfo

For a large document, sharding may be performed to produce several document shards. Each document shard contains this field to detail which shard it is.

Fields
shard_index	int64 The 0-based index of this shard.
shard_count	int64 Total number of shards.
text_offset	int64 The index of the first character in Document.text in the overall document global text.

Style

Annotation for common text style attributes. This adheres to CSS conventions as much as possible.

Fields
text_anchor	TextAnchor Text anchor indexing into the Document.text.
color	Color Text color.
background_color	Color Text background color.
font_weight	string Font weight. Possible values are normal, bold, bolder, and lighter. https://www.w3schools.com/cssref/pr_font_weight.asp
text_style	string Text style. Possible values are normal, italic, and oblique. https://www.w3schools.com/cssref/pr_font_font-style.asp
text_decoration	string Text decoration. Follows CSS standard. https://www.w3schools.com/cssref/pr_text_text-decoration.asp
font_size	FontSize Font size.

FontSize

Font size with unit.

Fields
size	float Font size for the text.
unit	string Unit for the font size. Follows CSS naming (in, px, pt, etc.).

TextAnchor

Text reference indexing into the Document.text.

Fields
text_segments[]	TextSegment The text segments from the Document.text.
content	string Contains the content of the text span so that users do not have to look it up in the text_segments.

TextSegment

A text segment in the Document.text. The indices may be out of bounds which indicate that the text extends into another document shard for large sharded documents. See ShardInfo.text_offset

Fields
start_index	int64 TextSegment start UTF-8 char index in the Document.text.
end_index	int64 TextSegment half open end UTF-8 char index in the Document.text.

TextChange

This message is used for text changes aka. OCR corrections.

Fields
text_anchor	TextAnchor Provenance of the correction. Text anchor indexing into the Document.text. There can only be a single TextAnchor.text_segments element. If the start and end index of the text segment are the same, the text change is inserted before that index.
changed_text	string The text that replaces the text identified in the text_anchor.
provenance[]	Provenance The history of this annotation.

Translation

A translation of the text segment.

Fields
text_anchor	TextAnchor Provenance of the translation. Text anchor indexing into the Document.text. There can only be a single TextAnchor.text_segments element. If the start and end index of the text segment are the same, the text change is inserted before that index.
language_code	string The BCP-47 language code, such as "en-US" or "sr-Latn". For more information, see www.unicode.org/reports/tr35/#Unicode_locale_identifier.
translated_text	string Text translated into the target language.
provenance[]	Provenance The history of this annotation.

NormalizedVertex

A vertex represents a 2D point in the image. NOTE: the normalized vertex coordinates are relative to the original image and range from 0 to 1.

Fields
x	float X coordinate.
y	float Y coordinate.

ProcessRequest

Request message for the process document method.

Fields
name	string Required. The processor resource name. Authorization requires the following IAM permission on the specified resource name: documentai.processors.processOnline
document	Document The document payload, the [content] and [mime_type] fields must be set.
skip_human_review	bool Whether Human Review feature should be skipped for this request. Default to false.

ProcessResponse

Response message for the process document method.

Fields
document	Document The document payload, will populate fields based on the processor's behavior.
human_review_operation	string The name of the operation triggered by the processed document. If the human review process is not triggered, this field will be empty. It has the same response type and metadata as the long running operation returned by ReviewDocument method.

ReviewDocumentOperationMetadata

The long running operation metadata for review document method.

Fields
state	State Used only when Operation.done is false.
state_message	string A message providing more details about the current state of processing. For example, the error message if the operation is failed.
create_time	Timestamp The creation time of the operation.
update_time	Timestamp The last update time of the operation.

State

State of the longrunning operation.

Enums
STATE_UNSPECIFIED	Unspecified state.
RUNNING	Operation is still running.
CANCELLING	Operation is being cancelled.
SUCCEEDED	Operation succeeded.
FAILED	Operation failed.
CANCELLED	Operation is cancelled.

ReviewDocumentRequest

Request message for review document method.

Fields
human_review_config	string Required. The resource name of the HumanReviewConfig that the document will be reviewed with. Authorization requires the following IAM permission on the specified resource humanReviewConfig: documentai.humanReviewConfigs.review
document	Document The document that needs human review.

ReviewDocumentResponse

Response message for review document method.

Fields
gcs_destination	string The Cloud Storage uri for the human reviewed document.

Vertex

A vertex represents a 2D point in the image. NOTE: the vertex coordinates are in the same scale as the original image.

Fields
x	int32 X coordinate.
y	int32 Y coordinate.