Small batch file annotation online

  • online (synchronous) requests - An online annotation request ( images:annotate or files:annotate ) immediately returns inline annotations to the user. Online annotation requests limit the number of files you can annotate in a single request. With an images:annotate request you can only specify a small number of images (<=16) to be annotated ; with a files: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 or files: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. A images:asyncBatchAnnotate request allows you to specify up to 2000 images per request ; a files: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 .

first five pages of a pdf file
gs://cloud-samples-data/vision/document_understanding/custom_0773375000.pdf

Page 1

page 1 of example pdf
 ... 
 "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

page 2 (top) of example pdf
 ... 
 "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, 
page 2 (bottom) of example pdf
 \ 
 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

page 3 (top) of example pdf
 ... 
 "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. 
page 3 (bottom) of example pdf
 \ 
 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

page 4 (top) of example pdf
 ... 
 "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. 
page 4 (bottom) of example pdf
 \ 
 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

page 5 (top) of example pdf
 ... 
 "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. 
page 5 (bottom) of example pdf
 \ 
 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=
    Visit the base64 encode topic for more information.
  • 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
Response:

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 .

  import 
  
 com.google.cloud.vision.v1. AnnotateFileRequest 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. AnnotateImageResponse 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. BatchAnnotateFilesRequest 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. BatchAnnotateFilesResponse 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. Block 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. Feature 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. ImageAnnotatorClient 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. InputConfig 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. Page 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. Paragraph 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. Symbol 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. Word 
 
 ; 
 import 
  
 com.google.protobuf. ByteString 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 import 
  
 java.nio.file.Files 
 ; 
 import 
  
 java.nio.file.Path 
 ; 
 import 
  
 java.nio.file.Paths 
 ; 
 public 
  
 class 
 BatchAnnotateFiles 
  
 { 
  
 public 
  
 static 
  
 void 
  
 batchAnnotateFiles 
 () 
  
 throws 
  
 IOException 
  
 { 
  
 String 
  
 filePath 
  
 = 
  
 "path/to/your/file.pdf" 
 ; 
  
 batchAnnotateFiles 
 ( 
 filePath 
 ); 
  
 } 
  
 public 
  
 static 
  
 void 
  
 batchAnnotateFiles 
 ( 
 String 
  
 filePath 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // Initialize client that will be used to send requests. This client only needs to be created 
  
 // once, and can be reused for multiple requests. After completing all of your requests, call 
  
 // the "close" method on the client to safely clean up any remaining background resources. 
  
 try 
  
 ( 
  ImageAnnotatorClient 
 
  
 imageAnnotatorClient 
  
 = 
  
  ImageAnnotatorClient 
 
 . 
 create 
 ()) 
  
 { 
  
 // You can send multiple files to be annotated, this sample demonstrates how to do this with 
  
 // one file. If you want to use multiple files, you have to create a `AnnotateImageRequest` 
  
 // object for each file that you want annotated. 
  
 // First read the files contents 
  
 Path 
  
 path 
  
 = 
  
 Paths 
 . 
 get 
 ( 
 filePath 
 ); 
  
 byte 
 [] 
  
 data 
  
 = 
  
 Files 
 . 
 readAllBytes 
 ( 
 path 
 ); 
  
  ByteString 
 
  
 content 
  
 = 
  
  ByteString 
 
 . 
  copyFrom 
 
 ( 
 data 
 ); 
  
 // Specify the input config with the file's contents and its type. 
  
 // Supported mime_type: application/pdf, image/tiff, image/gif 
  
 // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#inputconfig 
  
  InputConfig 
 
  
 inputConfig 
  
 = 
  
  InputConfig 
 
 . 
 newBuilder 
 (). 
  setMimeType 
 
 ( 
 "application/pdf" 
 ). 
 setContent 
 ( 
 content 
 ). 
 build 
 (); 
  
 // Set the type of annotation you want to perform on the file 
  
 // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#google.cloud.vision.v1.Feature.Type 
  
  Feature 
 
  
 feature 
  
 = 
  
  Feature 
 
 . 
 newBuilder 
 (). 
 setType 
 ( 
  Feature 
 
 . 
 Type 
 . 
 DOCUMENT_TEXT_DETECTION 
 ). 
 build 
 (); 
  
 // Build the request object for that one file. Note: for additional file you have to create 
  
 // additional `AnnotateFileRequest` objects and store them in a list to be used below. 
  
 // Since we are sending a file of type `application/pdf`, we can use the `pages` field to 
  
 // specify which pages to process. The service can process up to 5 pages per document file. 
  
 // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#google.cloud.vision.v1.AnnotateFileRequest 
  
  AnnotateFileRequest 
 
  
 fileRequest 
  
 = 
  
  AnnotateFileRequest 
 
 . 
 newBuilder 
 () 
  
 . 
 setInputConfig 
 ( 
 inputConfig 
 ) 
  
 . 
 addFeatures 
 ( 
 feature 
 ) 
  
 . 
 addPages 
 ( 
 1 
 ) 
  
 // Process the first page 
  
 . 
 addPages 
 ( 
 2 
 ) 
  
 // Process the second page 
  
 . 
 addPages 
 ( 
 - 
 1 
 ) 
  
 // Process the last page 
  
 . 
 build 
 (); 
  
 // Add each `AnnotateFileRequest` object to the batch request. 
  
  BatchAnnotateFilesRequest 
 
  
 request 
  
 = 
  
  BatchAnnotateFilesRequest 
 
 . 
 newBuilder 
 (). 
 addRequests 
 ( 
 fileRequest 
 ). 
 build 
 (); 
  
 // Make the synchronous batch request. 
  
  BatchAnnotateFilesResponse 
 
  
 response 
  
 = 
  
 imageAnnotatorClient 
 . 
 batchAnnotateFiles 
 ( 
 request 
 ); 
  
 // Process the results, just get the first result, since only one file was sent in this 
  
 // sample. 
  
 for 
  
 ( 
  AnnotateImageResponse 
 
  
 imageResponse 
  
 : 
  
 response 
 . 
  getResponsesList 
 
 (). 
 get 
 ( 
 0 
 ). 
 getResponsesList 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 format 
 ( 
 "Full text: %s%n" 
 , 
  
 imageResponse 
 . 
 getFullTextAnnotation 
 (). 
 getText 
 ()); 
  
 for 
  
 ( 
  Page 
 
  
 page 
  
 : 
  
 imageResponse 
 . 
 getFullTextAnnotation 
 (). 
 getPagesList 
 ()) 
  
 { 
  
 for 
  
 ( 
  Block 
 
  
 block 
  
 : 
  
 page 
 . 
 getBlocksList 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 format 
 ( 
 "%nBlock confidence: %s%n" 
 , 
  
 block 
 . 
 getConfidence 
 ()); 
  
 for 
  
 ( 
  Paragraph 
 
  
 par 
  
 : 
  
 block 
 . 
 getParagraphsList 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 format 
 ( 
 "\tParagraph confidence: %s%n" 
 , 
  
 par 
 . 
 getConfidence 
 ()); 
  
 for 
  
 ( 
  Word 
 
  
 word 
  
 : 
  
 par 
 . 
 getWordsList 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 format 
 ( 
 "\t\tWord confidence: %s%n" 
 , 
  
 word 
 . 
 getConfidence 
 ()); 
  
 for 
  
 ( 
  Symbol 
 
  
 symbol 
  
 : 
  
 word 
 . 
 getSymbolsList 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 format 
 ( 
  
 "\t\t\tSymbol: %s, (confidence: %s)%n" 
 , 
  
 symbol 
 . 
 getText 
 (), 
  
 symbol 
 . 
 getConfidence 
 ()); 
  
 } 
  
 } 
  
 } 
  
 } 
  
 } 
  
 } 
  
 } 
  
 } 
 } 
 

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 .

  /** 
 * TODO(developer): Uncomment these variables before running the sample. 
 */ 
 // const fileName = 'path/to/your/file.pdf'; 
 // Imports the Google Cloud client libraries 
 const 
  
 { 
 ImageAnnotatorClient 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/vision 
' 
 ). 
 v1 
 ; 
 const 
  
 fs 
  
 = 
  
 require 
 ( 
 'fs' 
 ). 
 promises 
 ; 
 // Instantiates a client 
 const 
  
 client 
  
 = 
  
 new 
  
  ImageAnnotatorClient 
 
 (); 
 // You can send multiple files to be annotated, this sample demonstrates how to do this with 
 // one file. If you want to use multiple files, you have to create a request object for each file that you want annotated. 
 async 
  
 function 
  
 batchAnnotateFiles 
 () 
  
 { 
  
 // First Specify the input config with the file's path and its type. 
  
 // Supported mime_type: application/pdf, image/tiff, image/gif 
  
 // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#inputconfig 
  
 const 
  
 inputConfig 
  
 = 
  
 { 
  
 mimeType 
 : 
  
 'application/pdf' 
 , 
  
 content 
 : 
  
 await 
  
 fs 
 . 
 readFile 
 ( 
 fileName 
 ), 
  
 }; 
  
 // Set the type of annotation you want to perform on the file 
  
 // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#google.cloud.vision.v1.Feature.Type 
  
 const 
  
 features 
  
 = 
  
 [{ 
 type 
 : 
  
 'DOCUMENT_TEXT_DETECTION' 
 }]; 
  
 // Build the request object for that one file. Note: for additional files you have to create 
  
 // additional file request objects and store them in a list to be used below. 
  
 // Since we are sending a file of type `application/pdf`, we can use the `pages` field to 
  
 // specify which pages to process. The service can process up to 5 pages per document file. 
  
 // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#google.cloud.vision.v1.AnnotateFileRequest 
  
 const 
  
 fileRequest 
  
 = 
  
 { 
  
 inputConfig 
 : 
  
 inputConfig 
 , 
  
 features 
 : 
  
 features 
 , 
  
 // Annotate the first two pages and the last one (max 5 pages) 
  
 // First page starts at 1, and not 0. Last page is -1. 
  
 pages 
 : 
  
 [ 
 1 
 , 
  
 2 
 , 
  
 - 
 1 
 ], 
  
 }; 
  
 // Add each `AnnotateFileRequest` object to the batch request. 
  
 const 
  
 request 
  
 = 
  
 { 
  
 requests 
 : 
  
 [ 
 fileRequest 
 ], 
  
 }; 
  
 // Make the synchronous batch request. 
  
 const 
  
 [ 
 result 
 ] 
  
 = 
  
 await 
  
 client 
 . 
 batchAnnotateFiles 
 ( 
 request 
 ); 
  
 // Process the results, just get the first result, since only one file was sent in this 
  
 // sample. 
  
 const 
  
 responses 
  
 = 
  
  result 
 
 . 
 responses 
 [ 
 0 
 ]. 
 responses 
 ; 
  
 for 
  
 ( 
 const 
  
 response 
  
 of 
  
 responses 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
 `Full text: 
 ${ 
 response 
 . 
 fullTextAnnotation 
 . 
 text 
 } 
 ` 
 ); 
  
 for 
  
 ( 
 const 
  
 page 
  
 of 
  
 response 
 . 
 fullTextAnnotation 
 . 
 pages 
 ) 
  
 { 
  
 for 
  
 ( 
 const 
  
 block 
  
 of 
  
 page 
 . 
 blocks 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
 `Block confidence: 
 ${ 
 block 
 . 
 confidence 
 } 
 ` 
 ); 
  
 for 
  
 ( 
 const 
  
 paragraph 
  
 of 
  
 block 
 . 
 paragraphs 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
 ` Paragraph confidence: 
 ${ 
 paragraph 
 . 
 confidence 
 } 
 ` 
 ); 
  
 for 
  
 ( 
 const 
  
 word 
  
 of 
  
 paragraph 
 . 
 words 
 ) 
  
 { 
  
 const 
  
 symbol_texts 
  
 = 
  
 word 
 . 
 symbols 
 . 
 map 
 ( 
 symbol 
  
 = 
>  
 symbol 
 . 
 text 
 ); 
  
 const 
  
 word_text 
  
 = 
  
 symbol_texts 
 . 
 join 
 ( 
 '' 
 ); 
  
 console 
 . 
 log 
 ( 
  
 `  Word text: 
 ${ 
 word_text 
 } 
 (confidence: 
 ${ 
 word 
 . 
 confidence 
 } 
 )` 
  
 ); 
  
 for 
  
 ( 
 const 
  
 symbol 
  
 of 
  
 word 
 . 
 symbols 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
  
 `   Symbol: 
 ${ 
 symbol 
 . 
 text 
 } 
 (confidence: 
 ${ 
 symbol 
 . 
 confidence 
 } 
 )` 
  
 ); 
  
 } 
  
 } 
  
 } 
  
 } 
  
 } 
  
 } 
 } 
 batchAnnotateFiles 
 (); 
 

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 .

  from 
  
 google.cloud 
  
 import 
  vision_v1 
 
 def 
  
 sample_batch_annotate_files 
 ( 
 file_path 
 = 
 "path/to/your/document.pdf" 
 ): 
  
 """Perform batch file annotation.""" 
 client 
 = 
  vision_v1 
 
 . 
  ImageAnnotatorClient 
 
 () 
 # Supported mime_type: application/pdf, image/tiff, image/gif 
 mime_type 
 = 
 "application/pdf" 
 with 
 open 
 ( 
 file_path 
 , 
 "rb" 
 ) 
 as 
 f 
 : 
 content 
 = 
 f 
 . 
 read 
 () 
 input_config 
 = 
 { 
 "mime_type" 
 : 
 mime_type 
 , 
 "content" 
 : 
 content 
 } 
 features 
 = 
 [{ 
 "type_" 
 : 
  vision_v1 
 
 . 
  Feature 
 
 . 
 Type 
 . 
 DOCUMENT_TEXT_DETECTION 
 }] 
 # The service can process up to 5 pages per document file. Here we specify 
 # the first, second, and last page of the document to be processed. 
 pages 
 = 
 [ 
 1 
 , 
 2 
 , 
 - 
 1 
 ] 
 requests 
 = 
 [{ 
 "input_config" 
 : 
 input_config 
 , 
 "features" 
 : 
 features 
 , 
 "pages" 
 : 
 pages 
 }] 
 response 
 = 
 client 
 . 
  batch_annotate_files 
 
 ( 
 requests 
 = 
 requests 
 ) 
 for 
 image_response 
 in 
 response 
 . 
 responses 
 [ 
 0 
 ] 
 . 
 responses 
 : 
 print 
 ( 
 f 
 "Full text: 
 { 
 image_response 
 . 
 full_text_annotation 
 . 
 text 
 } 
 " 
 ) 
 for 
 page 
 in 
 image_response 
 . 
 full_text_annotation 
 . 
 pages 
 : 
 for 
 block 
 in 
 page 
 . 
 blocks 
 : 
 print 
 ( 
 f 
 " 
 \n 
 Block confidence: 
 { 
 block 
 . 
 confidence 
 } 
 " 
 ) 
 for 
 par 
 in 
 block 
 . 
 paragraphs 
 : 
 print 
 ( 
 f 
 " 
 \t 
 Paragraph confidence: 
 { 
 par 
 . 
 confidence 
 } 
 " 
 ) 
 for 
 word 
 in 
 par 
 . 
 words 
 : 
 print 
 ( 
 f 
 " 
 \t\t 
 Word confidence: 
 { 
 word 
 . 
 confidence 
 } 
 " 
 ) 
 for 
 symbol 
 in 
 word 
 . 
 symbols 
 : 
 print 
 ( 
 " 
 \t\t\t 
 Symbol: 
 {} 
 , (confidence: 
 {} 
 )" 
 . 
 format 
 ( 
 symbol 
 . 
 text 
 , 
 symbol 
 . 
 confidence 
 ) 
 ) 
 

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
Response:

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 .

  import 
  
 com.google.cloud.vision.v1. AnnotateFileRequest 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. AnnotateImageResponse 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. BatchAnnotateFilesRequest 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. BatchAnnotateFilesResponse 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. Block 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. Feature 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. GcsSource 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. ImageAnnotatorClient 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. InputConfig 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. Page 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. Paragraph 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. Symbol 
 
 ; 
 import 
  
 com.google.cloud.vision.v1. Word 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 public 
  
 class 
 BatchAnnotateFilesGcs 
  
 { 
  
 public 
  
 static 
  
 void 
  
 batchAnnotateFilesGcs 
 () 
  
 throws 
  
 IOException 
  
 { 
  
 String 
  
 gcsUri 
  
 = 
  
 "gs://cloud-samples-data/vision/document_understanding/kafka.pdf" 
 ; 
  
 batchAnnotateFilesGcs 
 ( 
 gcsUri 
 ); 
  
 } 
  
 public 
  
 static 
  
 void 
  
 batchAnnotateFilesGcs 
 ( 
 String 
  
 gcsUri 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // Initialize client that will be used to send requests. This client only needs to be created 
  
 // once, and can be reused for multiple requests. After completing all of your requests, call 
  
 // the "close" method on the client to safely clean up any remaining background resources. 
  
 try 
  
 ( 
  ImageAnnotatorClient 
 
  
 imageAnnotatorClient 
  
 = 
  
  ImageAnnotatorClient 
 
 . 
 create 
 ()) 
  
 { 
  
 // You can send multiple files to be annotated, this sample demonstrates how to do this with 
  
 // one file. If you want to use multiple files, you have to create a `AnnotateImageRequest` 
  
 // object for each file that you want annotated. 
  
 // First specify where the vision api can find the image 
  
  GcsSource 
 
  
 gcsSource 
  
 = 
  
  GcsSource 
 
 . 
 newBuilder 
 (). 
 setUri 
 ( 
 gcsUri 
 ). 
 build 
 (); 
  
 // Specify the input config with the file's uri and its type. 
  
 // Supported mime_type: application/pdf, image/tiff, image/gif 
  
 // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#inputconfig 
  
  InputConfig 
 
  
 inputConfig 
  
 = 
  
  InputConfig 
 
 . 
 newBuilder 
 (). 
  setMimeType 
 
 ( 
 "application/pdf" 
 ). 
 setGcsSource 
 ( 
 gcsSource 
 ). 
 build 
 (); 
  
 // Set the type of annotation you want to perform on the file 
  
 // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#google.cloud.vision.v1.Feature.Type 
  
  Feature 
 
  
 feature 
  
 = 
  
  Feature 
 
 . 
 newBuilder 
 (). 
 setType 
 ( 
  Feature 
 
 . 
 Type 
 . 
 DOCUMENT_TEXT_DETECTION 
 ). 
 build 
 (); 
  
 // Build the request object for that one file. Note: for additional file you have to create 
  
 // additional `AnnotateFileRequest` objects and store them in a list to be used below. 
  
 // Since we are sending a file of type `application/pdf`, we can use the `pages` field to 
  
 // specify which pages to process. The service can process up to 5 pages per document file. 
  
 // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#google.cloud.vision.v1.AnnotateFileRequest 
  
  AnnotateFileRequest 
 
  
 fileRequest 
  
 = 
  
  AnnotateFileRequest 
 
 . 
 newBuilder 
 () 
  
 . 
 setInputConfig 
 ( 
 inputConfig 
 ) 
  
 . 
 addFeatures 
 ( 
 feature 
 ) 
  
 . 
 addPages 
 ( 
 1 
 ) 
  
 // Process the first page 
  
 . 
 addPages 
 ( 
 2 
 ) 
  
 // Process the second page 
  
 . 
 addPages 
 ( 
 - 
 1 
 ) 
  
 // Process the last page 
  
 . 
 build 
 (); 
  
 // Add each `AnnotateFileRequest` object to the batch request. 
  
  BatchAnnotateFilesRequest 
 
  
 request 
  
 = 
  
  BatchAnnotateFilesRequest 
 
 . 
 newBuilder 
 (). 
 addRequests 
 ( 
 fileRequest 
 ). 
 build 
 (); 
  
 // Make the synchronous batch request. 
  
  BatchAnnotateFilesResponse 
 
  
 response 
  
 = 
  
 imageAnnotatorClient 
 . 
 batchAnnotateFiles 
 ( 
 request 
 ); 
  
 // Process the results, just get the first result, since only one file was sent in this 
  
 // sample. 
  
 for 
  
 ( 
  AnnotateImageResponse 
 
  
 imageResponse 
  
 : 
  
 response 
 . 
  getResponsesList 
 
 (). 
 get 
 ( 
 0 
 ). 
 getResponsesList 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 format 
 ( 
 "Full text: %s%n" 
 , 
  
 imageResponse 
 . 
 getFullTextAnnotation 
 (). 
 getText 
 ()); 
  
 for 
  
 ( 
  Page 
 
  
 page 
  
 : 
  
 imageResponse 
 . 
 getFullTextAnnotation 
 (). 
 getPagesList 
 ()) 
  
 { 
  
 for 
  
 ( 
  Block 
 
  
 block 
  
 : 
  
 page 
 . 
 getBlocksList 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 format 
 ( 
 "%nBlock confidence: %s%n" 
 , 
  
 block 
 . 
 getConfidence 
 ()); 
  
 for 
  
 ( 
  Paragraph 
 
  
 par 
  
 : 
  
 block 
 . 
 getParagraphsList 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 format 
 ( 
 "\tParagraph confidence: %s%n" 
 , 
  
 par 
 . 
 getConfidence 
 ()); 
  
 for 
  
 ( 
  Word 
 
  
 word 
  
 : 
  
 par 
 . 
 getWordsList 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 format 
 ( 
 "\t\tWord confidence: %s%n" 
 , 
  
 word 
 . 
 getConfidence 
 ()); 
  
 for 
  
 ( 
  Symbol 
 
  
 symbol 
  
 : 
  
 word 
 . 
 getSymbolsList 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 format 
 ( 
  
 "\t\t\tSymbol: %s, (confidence: %s)%n" 
 , 
  
 symbol 
 . 
 getText 
 (), 
  
 symbol 
 . 
 getConfidence 
 ()); 
  
 } 
  
 } 
  
 } 
  
 } 
  
 } 
  
 } 
  
 } 
  
 } 
 } 
 

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 .

  /** 
 * TODO(developer): Uncomment these variables before running the sample. 
 */ 
 // const gcsSourceUri = 'gs://cloud-samples-data/vision/document_understanding/kafka.pdf'; 
 // Imports the Google Cloud client libraries 
 const 
  
 { 
 ImageAnnotatorClient 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/vision 
' 
 ). 
 v1 
 ; 
 // Instantiates a client 
 const 
  
 client 
  
 = 
  
 new 
  
  ImageAnnotatorClient 
 
 (); 
 // You can send multiple files to be annotated, this sample demonstrates how to do this with 
 // one file. If you want to use multiple files, you have to create a request object for each file that you want annotated. 
 async 
  
 function 
  
 batchAnnotateFiles 
 () 
  
 { 
  
 // First Specify the input config with the file's uri and its type. 
  
 // Supported mime_type: application/pdf, image/tiff, image/gif 
  
 // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#inputconfig 
  
 const 
  
 inputConfig 
  
 = 
  
 { 
  
 mimeType 
 : 
  
 'application/pdf' 
 , 
  
 gcsSource 
 : 
  
 { 
  
 uri 
 : 
  
 gcsSourceUri 
 , 
  
 }, 
  
 }; 
  
 // Set the type of annotation you want to perform on the file 
  
 // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#google.cloud.vision.v1.Feature.Type 
  
 const 
  
 features 
  
 = 
  
 [{ 
 type 
 : 
  
 'DOCUMENT_TEXT_DETECTION' 
 }]; 
  
 // Build the request object for that one file. Note: for additional files you have to create 
  
 // additional file request objects and store them in a list to be used below. 
  
 // Since we are sending a file of type `application/pdf`, we can use the `pages` field to 
  
 // specify which pages to process. The service can process up to 5 pages per document file. 
  
 // https://cloud.google.com/vision/docs/reference/rpc/google.cloud.vision.v1#google.cloud.vision.v1.AnnotateFileRequest 
  
 const 
  
 fileRequest 
  
 = 
  
 { 
  
 inputConfig 
 : 
  
 inputConfig 
 , 
  
 features 
 : 
  
 features 
 , 
  
 // Annotate the first two pages and the last one (max 5 pages) 
  
 // First page starts at 1, and not 0. Last page is -1. 
  
 pages 
 : 
  
 [ 
 1 
 , 
  
 2 
 , 
  
 - 
 1 
 ], 
  
 }; 
  
 // Add each `AnnotateFileRequest` object to the batch request. 
  
 const 
  
 request 
  
 = 
  
 { 
  
 requests 
 : 
  
 [ 
 fileRequest 
 ], 
  
 }; 
  
 // Make the synchronous batch request. 
  
 const 
  
 [ 
 result 
 ] 
  
 = 
  
 await 
  
 client 
 . 
 batchAnnotateFiles 
 ( 
 request 
 ); 
  
 // Process the results, just get the first result, since only one file was sent in this 
  
 // sample. 
  
 const 
  
 responses 
  
 = 
  
  result 
 
 . 
 responses 
 [ 
 0 
 ]. 
 responses 
 ; 
  
 for 
  
 ( 
 const 
  
 response 
  
 of 
  
 responses 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
 `Full text: 
 ${ 
 response 
 . 
 fullTextAnnotation 
 . 
 text 
 } 
 ` 
 ); 
  
 for 
  
 ( 
 const 
  
 page 
  
 of 
  
 response 
 . 
 fullTextAnnotation 
 . 
 pages 
 ) 
  
 { 
  
 for 
  
 ( 
 const 
  
 block 
  
 of 
  
 page 
 . 
 blocks 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
 `Block confidence: 
 ${ 
 block 
 . 
 confidence 
 } 
 ` 
 ); 
  
 for 
  
 ( 
 const 
  
 paragraph 
  
 of 
  
 block 
 . 
 paragraphs 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
 ` Paragraph confidence: 
 ${ 
 paragraph 
 . 
 confidence 
 } 
 ` 
 ); 
  
 for 
  
 ( 
 const 
  
 word 
  
 of 
  
 paragraph 
 . 
 words 
 ) 
  
 { 
  
 const 
  
 symbol_texts 
  
 = 
  
 word 
 . 
 symbols 
 . 
 map 
 ( 
 symbol 
  
 = 
>  
 symbol 
 . 
 text 
 ); 
  
 const 
  
 word_text 
  
 = 
  
 symbol_texts 
 . 
 join 
 ( 
 '' 
 ); 
  
 console 
 . 
 log 
 ( 
  
 `  Word text: 
 ${ 
 word_text 
 } 
 (confidence: 
 ${ 
 word 
 . 
 confidence 
 } 
 )` 
  
 ); 
  
 for 
  
 ( 
 const 
  
 symbol 
  
 of 
  
 word 
 . 
 symbols 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
  
 `   Symbol: 
 ${ 
 symbol 
 . 
 text 
 } 
 (confidence: 
 ${ 
 symbol 
 . 
 confidence 
 } 
 )` 
  
 ); 
  
 } 
  
 } 
  
 } 
  
 } 
  
 } 
  
 } 
 } 
 batchAnnotateFiles 
 (); 
 

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 .

  from 
  
 google.cloud 
  
 import 
  vision_v1 
 
 def 
  
 sample_batch_annotate_files 
 ( 
 storage_uri 
 = 
 "gs://cloud-samples-data/vision/document_understanding/kafka.pdf" 
 , 
 ): 
  
 """Perform batch file annotation.""" 
 mime_type 
 = 
 "application/pdf" 
 client 
 = 
  vision_v1 
 
 . 
  ImageAnnotatorClient 
 
 () 
 gcs_source 
 = 
 { 
 "uri" 
 : 
 storage_uri 
 } 
 input_config 
 = 
 { 
 "gcs_source" 
 : 
 gcs_source 
 , 
 "mime_type" 
 : 
 mime_type 
 } 
 features 
 = 
 [{ 
 "type_" 
 : 
  vision_v1 
 
 . 
  Feature 
 
 . 
 Type 
 . 
 DOCUMENT_TEXT_DETECTION 
 }] 
 # The service can process up to 5 pages per document file. 
 # Here we specify the first, second, and last page of the document to be 
 # processed. 
 pages 
 = 
 [ 
 1 
 , 
 2 
 , 
 - 
 1 
 ] 
 requests 
 = 
 [{ 
 "input_config" 
 : 
 input_config 
 , 
 "features" 
 : 
 features 
 , 
 "pages" 
 : 
 pages 
 }] 
 response 
 = 
 client 
 . 
  batch_annotate_files 
 
 ( 
 requests 
 = 
 requests 
 ) 
 for 
 image_response 
 in 
 response 
 . 
 responses 
 [ 
 0 
 ] 
 . 
 responses 
 : 
 print 
 ( 
 f 
 "Full text: 
 { 
 image_response 
 . 
 full_text_annotation 
 . 
 text 
 } 
 " 
 ) 
 for 
 page 
 in 
 image_response 
 . 
 full_text_annotation 
 . 
 pages 
 : 
 for 
 block 
 in 
 page 
 . 
 blocks 
 : 
 print 
 ( 
 f 
 " 
 \n 
 Block confidence: 
 { 
 block 
 . 
 confidence 
 } 
 " 
 ) 
 for 
 par 
 in 
 block 
 . 
 paragraphs 
 : 
 print 
 ( 
 f 
 " 
 \t 
 Paragraph confidence: 
 { 
 par 
 . 
 confidence 
 } 
 " 
 ) 
 for 
 word 
 in 
 par 
 . 
 words 
 : 
 print 
 ( 
 f 
 " 
 \t\t 
 Word confidence: 
 { 
 word 
 . 
 confidence 
 } 
 " 
 ) 
 for 
 symbol 
 in 
 word 
 . 
 symbols 
 : 
 print 
 ( 
 " 
 \t\t\t 
 Symbol: 
 {} 
 , (confidence: 
 {} 
 )" 
 . 
 format 
 ( 
 symbol 
 . 
 text 
 , 
 symbol 
 . 
 confidence 
 ) 
 ) 
 

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.

first five pages of a pdf file
gs://cloud-samples-data/vision/document_understanding/custom_0773375000.pdf

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
      ]
    }
  ]
}
Create a Mobile Website
View Site in Mobile | Classic
Share by: