- online (synchronous)
requests - An online annotation request (
images:annotate
orfiles:annotate
) immediately returns inline annotations to the user. Online annotation requests limit the number of files you can annotate in a single request. With animages:annotate
request you can only specify a small number of images (<=16) to be annotated ; with afiles:annotate
request you can only specify a single file and specify a small number of pages (<=5) in that file to be annotated. - offline (asynchronous)
requests - An offline annotation request
(
images:asyncBatchAnnotate
orfiles:asyncBatchAnnotate
) starts a long-running operation (LRO) and does not immediately return a response to the caller. When the LRO completes, annotations are stored as files in a Cloud Storage bucket you specify. Aimages:asyncBatchAnnotate
request allows you to specify up to 2000 images per request ; afiles:asyncBatchAnnotate
request allows you to specify larger batches of files and can specify more pages (<=2000) per file for annotation at a single time than you are able to with online requests.
The Vision API can provide online (immediate) annotation of multiple pages or frames from PDF, TIFF, or GIF files stored in Cloud Storage.
You can request online feature detection and annotation of 5 frames (GIF; "image/gif") or pages (PDF; "application/pdf", or TIFF; "image/tiff") of your choosing for each file.
The example annotations on this page are for DOCUMENT_TEXT_DETECTION
, but
online small batch annotation is available for all Vision features
.
Page 1

... "text" : "á\n7.1.15\nOIL, GAS AND MINERAL LEASE \nNORVEL J. CHITTIM, ET AL\n.\n. \nTO\nW. L. SCHEIG\n" }, "context" : { "pageNumber" : 1 } ...
Page 2
![]() ... "text" : "...\n.\n*\n.\n.\n.\nA\nNY\nALA...\n7 \n| THE STATE OF TEXAS \nOIL, GAS AND MINERAL LEASE \nCOUNTY OF MAVERICK ] \nTHIS AGREEMENT made this 14 day of_June \n1954, between Norvel J. Chittim and his wife, Lieschen G. Chittim; \nMary Anne Chittim Parker, joined herein pro forma by her husband, \nJoseph Bright Parker; Dorothea Chittim Oppenheimer, joined herein \npro forma by her husband, Fred J. Oppenheimer; Tuleta Chittim \nWright, joined herein pro forma by her husband, Gilbert G. Wright, \nJr.; Gilbert G. Wright, III; Dela Wright White, joined herein pro \nforma by her husband, John H. White; Anne Wright Basse, joined \nherein pro forma by her husband, E. A. Basse, Jr.; Norvel J. \nChittim, Independent Executor and Trustee for Estate of Marstella \nChittim, Deceased; Mary Louise Roswell, joined herein pro forma by \nher husband, Charles M. 'Roswell; and James M. Chittim and his wife, \nThelma Neal Chittim; as LESSORS, and W. L. Scheig of San Antonio, \nTexas, as LESSEE, |
---|
![]() \ n W I T N E s s E T H : \ n 1. Lessors , i n co ns idera t io n o f $ 10.00 , cash i n ha n d paid , \ n o f t he royal t ies herei n provided , a n d o f t he agreeme nt o f Lessee \ n herei n co nta i ne d , hereby gra nt , lease a n d le t exclusively u nt o \ n Lessee t he tra c ts o f la n d herei nafter described f or t he purpose o f \ ntest i n g f or mi neral i n dica t io ns , a n d i n such tests use t he Seismo - \ n graph , Torsio n Bala n ce , Core Drill , or a n y o t her t ools , machi ner y , \ ne quipme nt or explosive ne cessary a n d proper; a n d also prospec t i n g , \ n drilli n g a n d mi n i n g f or a n d produci n g oil , gas a n d o t her mi nerals \ n (excep t me tall ic mi nerals ) , layi n g pipe li nes , buildi n g tan ks , \ n power s tat io ns , tele pho ne li nes a n d o t her s tru c tures t hereo n t o \ n produce , save , ta ke care o f , treat , trans por t a n d ow n said pro - \ n duc ts a n d housi n g i ts employees (Lessee t o co n duc t i ts geophysical \ n work i n such ma nner as n o t t o damage t he buildi n gs , wa ter tan ks \ n or wells o f Lessors , or t he lives t ock o f Lessors or Lessors' ten - ! \ nants , )said la n ds bei n g si tuate d i n Maverick , Zavalla a n d Dimmi t \ n Cou nt ies , Texas , t o - wi t : \ n 3-1. \ n " }, " co nte x t ": {" pageNumber": 2} ... |
Page 3
![]() ... "text" : "Being a tract consisting of 140,769.86 acres, more or \nless, out of what is known as the \"Chittim Ranch\" in said counties, \nas designated and described in Exhibit \"A\" hereto attached and \nmade a part hereof as if fully written herein. It being under- \nstood that the acreage intended to be included in this lease aggre- \ngates approximately 140,769.86 acres whether it actually comprises \nmore or less, but for the purpose of calculating the payments \nhereinafter provided for, it is agreed that the land included with- \nin the terms of this lease is One hundred forty thousand seven \nhundred sixty-nine and eighty-six one hundredths (140,769.86) acres, \nand that each survey listed above contains the acreage stated above. \nIt is understood that tract designated \"TRACT II\" in \nExhibit \"A\" is subject to a one-sixteenth (1/16) royalty reserved. \nto the State of Texas, and the rights of the State of Texas must \nbe respected in the development of the said property. |
---|
![]() \ n 2. Subjec t t o t he o t her provisio ns hereo f , t his lease shall \ n be f or a ter m o f ten ( 10 ) years fr om da te hereo f (called \ "Primary \nTerm\"), and as long thereafter as oil, gas or other minerals \n(except metallic minerals) are produced from said land hereunder \nin paying quantities, subject, however, to all of the terms and \nprovisions of this lease. After expiration of the primary term, \nthis lease shall terminate as to all lands included herein, save \nand except as to those tracts which lessee maintains in force and \neffect according to the requirements hereof. \n3. The royalties to be paid by Lessee are (a) on oil, one- \neighth (1/8) of that produced and saved from said land, the same to \nbe delivered at the well or to the credit of Lessors into the pipe i \nline to which the well may be connected; (b) on gas, including \ni casinghead gas or other gaseous or vaporous substance, produced \nfrom the leased premises and sold or used by Lessee off the leased \npremises or in the manufacture of gasoline or other products, the \nmarket value, at the mouth of the well, of one-eighth (1/8) of \n.\n3-2-\n?\n" }, "context" : { "pageNumber" : 3 } ... |
Page 4
![]() ... "text" : "•\n:\n.\nthe gas or casinghead gas so used or sold. On all gas or casing- \nhead gas sold at the well, the royalty shall be one-eighth (1/8) \nof the amounts realized from such sales. While gas from any well \nproducing gas only is being used or sold by. Lessee, Lessor may have \nenough of said gas for all stoves and inside lights in the prin- \ncipal dwelling house on the leased premises by making Lessors' own \nconnections with the well and by assuming all risk and paying all \nexpenses. And (c) on all other minerals (except metallic minerals) \nmined and marketed, one tenth (1/10). either in kind or value at the \nwell or mine at Lessee's election. \nFor the purpose of royalty payments under 3 (b) hereof, \nall liquid hydrocarbons (including distillate) recovered and saved n| by Lessee in separators or traps on the leased premises shall be \nconsidered as oil. Should such a plant be constructed by another \nthan Lessee to whom Lessee should sell or deliver the gas or cas- \ninghead gas produced from the leased premises for processing, then \nthe royalty thereon shall be one-eighth (1/8) of the amounts \nrealized by Lessee from such sales or deliveries. |
---|
![]() \ n Or i f such pla nt is ow ne d or co nstru c te d or opera te d by \ n Lessee , t he n t he royal t y shall be o n t he basis o f o ne -e igh t h ( 1 / 8 ) | \ n o f t he prevaili n g price i n t he area f or such produc ts .. \ n The provisio ns o f t his paragraph shall co ntr ol as t o a n y \ n co nfl ic t wi t h Paragraph 3 (b). Lessors shall also be e nt i tle d t o \ nsa id royal t y i nterest i n all residue gas .ob ta i ne d , saved a n d mar - \ n ke te d fr om said premises , or used o ff t he premises , or t ha t may be \ nre placed i n t he reservoir by 'a n y recycli n g process , se ttle me nt \ nt here f or t o be made t o Lessors whe n such gas is marke te d or used \ n o ff t he premises. ! \ n I f a t t he expira t io n o f t he primary ter m o f t his lease \ n Lessee has n o t f ou n d a n d produced oil or gas i n payi n g qua nt i t ies \ n i n a n y f orma t io n lyi n g f i ft y ( 50 ) feet below t he base o f wha t is \ n k n ow n as t he Rhodessa sec t io n a t t he par t icular poi nt where t he \ n well is drilled , t he n , subjec t t o t he furt her provisio ns hereo f , \ nt his lease shall ter mi nate as t o all horizo ns below f i ft y ( 50 ) \ n I feet below t he Rhodessa sec t io n . A n d i f a t t he expira t io n o f t he \ n 3 -3- \ n " }, " co nte x t ": {" pageNumber": 4} ... |
Page 5
![]() ... "text" : ".\n.\n:\nI\n.\n.\n.:250:-....\n.\n...\n.\n....\n....\n..\n..\n. .. \n.\n..\n.\n...\n...\n.-\n.\n.\n..\n..\n17\n.\n:\n-\n-\n-\n.\n..\n. \nprimary term production of oil or gas in paying quantities is not \nfound in the Jurassic, then this lease shall terminate as to the \nJurassic and lower formations unless Lessee shall have completed \nat least two (2) tests in the Jurassic. And after the primary \nterm Lessee shall complete at least one (1) Jurassic test each \nthree years on said property as to which this lease is still in \neffect, until paying production is obtained in or below the \nJurassic, or upon failure so to do Lessee shall release this \nlease as to all formations below the top of the Jurassic. Upon \ncompliance with the above provisions as to Jurassic tests, and \nif production is found in the Jurassic, then, subject to the \nother provisions hereof, this lease shall be effective as to all \nhorizons, including the Jurassic.. \n5. It is understood and expressly agreed that the consider- \niation first recited in this lease, the down cash payment, receipt \nof which is hereby acknowledged by Lessors, is full and adequate \nconsideration to maintain this lease in full force and effect for \na period of one year from the date hereof, and does not impose \nany obligation on the part of Lessee to drill and develop this \nlease during the said term of one year from date of this lease. |
---|
![]() \ n 6. This lease shall ter mi nate as t o bo t h par t ies u nless \ n o n or be f ore o ne year fr om t his da te , Lessee shall pay t o or ten - ! \ n der t o Lessors or t o t he credi t o f Lessors , i n t he Na t io nal Ba n k \ n o f Commerce , a t Sa n A nt o n io , Texas , (which ba n k a n d i ts successors \ nare Lessors' age nt , a n d shall co nt i nue as t he deposi t ory f or all \ " \nrental payable hereunder regardless of changes in ownership of \nsaid land or the rental), the sum of One Dollar ($1.00) per acre \nas to all acreage then covered by this lease, and not surrendered, \nor maintained by production of oil, gas or other minerals, or by \ndrilling-reworking operations, all as hereinafter fully set out, : \nwhich shall maintain this lease in full force and effect for \nanother twelve-month period, without imposing any obligation on \nthe part of Lessee to drill and develop this lease. In like \nmanner, and upon like payment or tender annually, Lessee may \nmaintain this lease .in full force and effect for successive \ntwelve-month periods during the primary term, without imposing \n.\n--.\n.\n.\n.\n-\n::\n--- \n-\n3\n.\n..-\n-\n-\n:.\n.\n::\n. \n3-4-\n" }, "context" : { "pageNumber" : 5 } ... |
Limitations
At most 5 pages will be annotated. Users can specify the specific 5 pages to be annotated.
Authentication
Set up your Google Cloud project and authentication
Currently supported feature types
Feature type | |
---|---|
CROP_HINTS
|
Determine suggested vertices for a crop region on an image. |
DOCUMENT_TEXT_DETECTION
|
Perform OCR on dense text images, such as documents (PDF/TIFF), and images with
handwriting. TEXT_DETECTION
can be used for sparse text images.
Takes precedence when both DOCUMENT_TEXT_DETECTION
and TEXT_DETECTION
are present. |
FACE_DETECTION
|
Detect faces within the image. |
IMAGE_PROPERTIES
|
Compute a set of image properties, such as the image's dominant colors. |
LABEL_DETECTION
|
Add labels based on image content. |
LANDMARK_DETECTION
|
Detect geographic landmarks within the image. |
LOGO_DETECTION
|
Detect company logos within the image. |
OBJECT_LOCALIZATION
|
Detect and extract multiple objects in an image. |
SAFE_SEARCH_DETECTION
|
Run SafeSearch to detect potentially unsafe or undesirable content. |
TEXT_DETECTION
|
Perform Optical Character Recognition (OCR) on text within the image.
Text detection is optimized for areas of sparse text within a larger image.
If the image is a document (PDF/TIFF), has dense text, or contains handwriting,
use DOCUMENT_TEXT_DETECTION
instead. |
WEB_DETECTION
|
Detect topical entities such as news, events, or celebrities within the image, and find similar images on the web using the power of Google Image Search. |
Sample code
You can either send an annotation request with a locally stored file , or use a file that is stored on Cloud Storage .
Using a locally stored file
Use the following code samples to get any feature annotation for a locally stored file.
REST
To perform online PDF/TIFF/GIF feature detection for a small batch of files, make a POST request and provide the appropriate request body:
Before using any of the request data, make the following replacements:
- BASE64_ENCODED_FILE
: The base64
representation (ASCII string) of your binary file data. This string should look similar to the
following string:
-
JVBERi0xLjUNCiW1tbW1...ydHhyZWYNCjk5NzM2OQ0KJSVFT0Y=
-
- PROJECT_ID : Your Google Cloud project ID.
Field-specific considerations:
-
inputConfig.mimeType
- One of the following: "application/pdf", "image/tiff" or "image/gif". -
pages
- specifies the specific pages of the file to perform feature detection.
HTTP method and URL:
POST https://vision.googleapis.com/v1/files:annotate
Request JSON body:
{ "requests": [ { "inputConfig": { "content": " BASE64_ENCODED_FILE ", "mimeType": "application/pdf" }, "features": [ { "type": "DOCUMENT_TEXT_DETECTION" } ], "pages": [ 1,2,3,4,5 ] } ] }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID " \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://vision.googleapis.com/v1/files:annotate"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = " PROJECT_ID " }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/files:annotate" | Select-Object -Expand Content
A successful annotate
request immediately returns a JSON response.
For this feature ( DOCUMENT_TEXT_DETECTION
), the JSON response is similar to that of
an image's document text detection request
. The
response contains bounding boxes for blocks broken down by paragraphs, words, and individual
symbols. The full text is also detected. The response also contains a context
field showing the location of the PDF or TIFF that was specified and the result's page number in
the file.
The following response JSON is only for a single page (page 2) and has been shortened for clarity.
Java
Before trying this sample, follow the Java setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Java reference documentation .
Node.js
Before trying this sample, follow the Node.js setup instructions in the Vision quickstart using client libraries . For more information, see the Vision Node.js API reference documentation .
To authenticate to Vision, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .
Python
Before trying this sample, follow the Python setup instructions in the Vision quickstart using client libraries . For more information, see the Vision Python API reference documentation .
To authenticate to Vision, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .
Using a file on Cloud Storage
Use the following code samples to get any feature annotation for a file on Cloud Storage.
REST
To perform online PDF/TIFF/GIF feature detection for a small batch of
files, make a POST
request and provide the appropriate request body:
Before using any of the request data, make the following replacements:
- CLOUD_STORAGE_FILE_URI
: the path to a valid
file (PDF/TIFF) in a Cloud Storage bucket. You must at least have read privileges to
the file.
Example:
-
gs://cloud-samples-data/vision/document_understanding/custom_0773375000.pdf
-
- PROJECT_ID : Your Google Cloud project ID.
Field-specific considerations:
-
inputConfig.mimeType
- One of the following: "application/pdf", "image/tiff" or "image/gif". -
pages
- specifies the specific pages of the file to perform feature detection.
HTTP method and URL:
POST https://vision.googleapis.com/v1/files:annotate
Request JSON body:
{ "requests": [ { "inputConfig": { "gcsSource": { "uri": " CLOUD_STORAGE_FILE_URI " }, "mimeType": "application/pdf" }, "features": [ { "type": "DOCUMENT_TEXT_DETECTION" } ], "pages": [ 1,2,3,4,5 ] } ] }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID " \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://vision.googleapis.com/v1/files:annotate"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = " PROJECT_ID " }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/files:annotate" | Select-Object -Expand Content
A successful annotate
request immediately returns a JSON response.
For this feature ( DOCUMENT_TEXT_DETECTION
), the JSON response is similar to that of
an image's document text detection request
. The
response contains bounding boxes for blocks broken down by paragraphs, words, and individual
symbols. The full text is also detected. The response also contains a context
field showing the location of the PDF or TIFF that was specified and the result's page number in
the file.
The following response JSON is only for a single page (page 2) and has been shortened for clarity.
Java
Before trying this sample, follow the Java setup instructions in the Vision API Quickstart Using Client Libraries . For more information, see the Vision API Java reference documentation .
Node.js
Before trying this sample, follow the Node.js setup instructions in the Vision quickstart using client libraries . For more information, see the Vision Node.js API reference documentation .
To authenticate to Vision, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .
Python
Before trying this sample, follow the Python setup instructions in the Vision quickstart using client libraries . For more information, see the Vision Python API reference documentation .
To authenticate to Vision, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .
Try it
Try small batch online feature detection below.
You can use the PDF file specified already or specify your own file in its place.
There are three feature types specified for this request:
-
DOCUMENT_TEXT_DETECTION
-
LABEL_DETECTION
-
CROP_HINTS
You can add or remove other feature types
by changing the
appropriate object in the request ( {"type": "FEATURE_NAME"}
).
Send the request by selecting Execute.
Request body:
{ "requests": [ { "inputConfig": { "gcsSource": { "uri": "gs://cloud-samples-data/vision/document_understanding/custom_0773375000.pdf" }, "mimeType": "application/pdf" }, "features": [ { "type": "DOCUMENT_TEXT_DETECTION" }, { "type": "LABEL_DETECTION" }, { "type": "CROP_HINTS" } ], "pages": [ 1, 2, 3, 4, 5 ] } ] }