TextSense OCR
TextSense OCR is a large-volume document image text conversion solution based on deep learning AI. Use this to extract data from invoices, forms, bank statements or any other kind of document.
Available Methods
[POST] /textsense/job/build
Description: Use REST API to request OCR work on documents in various formats from the TextSense server.
Attributes
Hint: attributes should be inside JSON for POST request:
{
"inputUri": "url-input-link"
}
Note:
JSON attributes are case-sensitive.| Attributes |
|---|
inputUri String requiredURL to the source file. TextSense supports input types such as jpg/jpeg, png, tif/tiff/multi-tiff, pdf, and bmp. Schemas such as, http://, https://, sftp://, ftp://, s3://. Supports links from Google Drive, Dropbox, and PDF.co built-in files storage. To upload files via API, Check out the Files Upload section. Note: If you experience intermittent Too Many Requests or Access Denied errors, please try to add cache: to enable built-in URL caching. (e.g cache:https://example.com/file1.pdf) For data security, you have the option to encrypt output files and decrypt input files. Learn more about user-controlled data encryption. |
options Object requiredContains the options for the operation to be performed |
“options” Object definition |
|---|
extraJobs Object requiredDefines the OCR operation to be performed. |
“extraJobs” Object definition |
|---|
type String requiredThis is the separator for the OCR operation. To perform OCR work, “textSense” is used as a fixed value. |
option Object requiredOption values to be applied to the OCR operation are transmitted in the form of a JSON object. |
extraJobs.option Object definition |
|---|
reqType String requiredSet the recognition logic for OCR work. Use “Document” as a fixed value. |
reqOption Object requiredThe default value is an empty json object. In addition to the basic recognition of ”{}”, you can set additional settings for OCR work, such as “SearchAPI” to update the recognition target settings. |
outputType String requiredSet the type of result file to be created through OCR work. Supported output types are “pdf”, “json”, “excel”, “text”, and “text-split”. “text” saves the text of the requested document as a single txt file, and “text-split” saves the text of the requested document for each page. |
pages String optionalSet the range to perform OCR work. The default is for all pages. Examples: “all”, “1-5”, “1,2,3,” etc. are possible. |
“reqOption” explained
“reqOption” Object definition |
|---|
| When performing OCR work using the REST API, in addition to basic recognition, you can make additional settings for OCR work. |
| PreProcessOption - This option allows you to perform special operations before OCR extraction. |
| ResultOption - This option allows you to specify options for the desired result. |
| CustomSetting - This option allows you to temporarily change/set the value of a custom setting. |
| SearchAPI - This option allows you to extract data by adding special. |
PreProcessOption
| Key | Description |
|---|---|
| denoising | Reduces noise in the original file. |
| scaleUp | Enlarges the original file. |
| RotationCorrection | Corrects the rotation of the original file. |
Example:
"reqOption" : {
"PreProcessOption" : {
"scaleUp" : true,
"denoising" : true,
"RotationCorrection" : true
}
}
ResultOption
| Key | Description |
|---|---|
| Format | If set to “PlainText”, the table structure will be ignored in the recognized results. |
| WordCorrection | When set to “Custom” , you can use a word correction dictionary from an externally mounted directory. |
Example:
"reqOption" : {
"ResultOption" : {
"Format" : "PlainText",
"WordCorrection" : "Custom"
}
}
CustomSetting
You can temporarily change/set the value of “CustomSetting” through “reqOption” for one request only.
| Key | Description |
|---|---|
| TextInputMaxAxis | Image input size when detecting text. |
| TableInputMaxAxis | Table detects image input size. |
| TextScoreThreshold | Threshold for text detection score. |
| TableCellScoreThreshold | Threshold for table detection score. |
| CellAlignSearchMargin | Sets the margin for table cell alignment. The unit is a pixel, and as the value increases, it becomes less sensitive to rotation and errors, but the tendency for small cells to merge into one increases. |
| CellAlignGridMargin | Sets the size of the grid format when dividing the matrix for table cells. The units are pixels, and as the value increases, it becomes less sensitive to rotations and errors, but also increases the tendency for small cells to merge into one. |
SearchAPI
To use “SearchAPI”, you must add JSON data in the following format to “reqOption”.
| Key | Description |
|---|---|
| Type | The name of the task you want to perform. |
| Name | The name of the task. This name becomes the return name in the results. |
| Key | Keys for navigation in tasks. |
SearchAPI.Type Object definition |
| Key | Description |
|---|---|
| FindRow | Find specific characters and find data in the same column or horizontal row. |
| FindRightRow | Finds a specific character and only finds data to the right of the search target in the same column. |
| FindCol | Find specific characters and find data in the same row or vertical line. |
| FindBottomCol | Finds a specific character and only finds data below the search target in the same row. |
| FindWord | Finds a specific string and creates a set of that string. |
| FindLine | Searches for and returns data in lines that contain a specific string. |
| FindRegion | Find data within a specific region (rectangle). This function, unlike other Find APIs, uses a list of coordinates for the key value. |
FindRow
This is an API that collects and returns data in the same row as the target containing a specific string.
- If there are multiple rows with the same content, only the first row detected is returned.
- The key value of the request JSON is compared based on the word element, and may not work properly if the spacing between words is large.
Example:
"reqOption" : {
"SearchAPI" : [
{
"Type" : "FindRow",
"Name" : "Test-Title",
"Key" : ["Keyword in row"]
}
]
}
FindRightRow
This uses the same algorithm as FindRow, but returns only those positions to the right of the search target in the results.
- If there are multiple rows with the same content, only the first row detected is returned.
- The key value of the request JSON is compared based on the word element, and may not work properly if the spacing between words is large.
Example:
"reqOption" : {
"SearchAPI" : [
{
"Type" : "FindRightRow",
"Name" : "Test-Title",
"Key" : ["Keyword in row"]
}
]
}
FindCol
This collects and returns data in the same column as the target that contains a specific string.
- If there are multiple columns with the same content, only the first detected column is returned.
- The key value of the request JSON is compared based on the word element, and may not work properly if the spacing between words is large.
"reqOption" : {
"SearchAPI" : [
{
"Type" : "FindCol",
"Name" : "Test-Title",
"Key" : ["Keyword in column"]
}
]
}
FindBottomCol
This uses the same algorithm as FindCol, but only returns the results located below the search target.
- If there are multiple columns with the same content, only the first detected column is returned.
- The key value of the request JSON is compared based on the word element, and may not work properly if the spacing between words is large.
"reqOption" : {
"SearchAPI" : [
{
"Type" : "FindBottomCol",
"Name" : "Test-Title",
"Key" : ["Keyword in column"]
}
]
}
FindWord
This request searches for and returns data containing a specific string.
- The key value of the request JSON is compared based on the word element, and may not work properly if the spacing between words is large.
"reqOption" : {
"SearchAPI" : [
{
"Type" : "FindWord",
"Name" : "Test-Title",
"Key" : ["Keyword"]
}
]
}
FindLine
This request searches for and returns data on lines that contain a specific string.
- FindLine performs a similar function to FindRow, but while FindRow aims to search tables, FindLine aims to search text lines.
- Therefore, we recommend using FindRow when looking for data inside a table and FindLine when looking for data in a general document outside the table.
"reqOption" : {
"SearchAPI" : [
{
"Type" : "FineLine",
"Name" : "Test-Title",
"Key" : ["Keyword"]
}
]
}
FindRegion
This request collects and returns data contained within a specific rectangular region.
- The FindRegion API, unlike other APIs, contains coordinates rather than letters in the key.
- The coordinates are TL (Top-Left) and BR (Bottom-Right) of the area to be recognized.
"reqOption" : {
"SearchAPI" : [
{
"Type" : "FindRegion",
"Name" : "city",
"Key" : [
[
217.218085106383,
156.75531914893617
],
[
265.19680851063833,
174.2845744680851
]
]
},{
"Type" : "FindRegion",
"Name" : "phone-number",
"Key" : [
[
428.8377659574468,
296.7154255319149
],
[
507.04787234042544,
320.9627659574469
]
]
}
]
}
- Method: POST
- URL: /v1/textsense/job/build
Query parameters
No query parameters accepted.
Example payload
{
"inputUri": "https://example.com/TestFiles/input.pdf",
"options": {
"extraJobs": [
{
"type": "textSense",
"option": {
"reqType": "Document",
"reqOption": {
"SearchAPI": [
{
"Type": "FindRegion",
"Name": "test1",
"Key": [
[
103.79577464788731,
27.91146881287729
],
[
179.24396378269623,
56.97786720321933
]
]
},
{
"Type": "FindRegion",
"Name": "test2",
"Key": [
[
181.42454728370228,
26.167002012072373
],
[
274.31740442655985,
59.594567404426414
]
]
}
]
},
"outputType": "json",
"pages": "all"
}
}
]
}
}
Example response
/textsense/job/build (output as JSON)
{
"body": {
"objects": [
{
"name": "test1",
"value": "Greetings from the document!",
"rectangle": [
103.79577464788731,
27.91146881287729,
179.24396378269623,
56.97786720321933
]
},
{
"name": "test2",
"value": "We hope you enjoy your search!",
"rectangle": [
181.42454728370228,
26.167002012072373,
274.31740442655985,
59.594567404426414
]
}
],
"timestamp": "2023-08-21T19:23:31"
},
"pageCount": 1,
"error": false,
"status": 200,
"name": "textsense.json",
"remainingCredits": 60803
}
Code Snippet
CURL
curl -v -X POST "https://api.pdf.co/v1/textsense/job/build" \
-H "Content-Type: application/json" \
-H "x-api-key: " \
-d "{
\"inputUri\": \"https://pdfco-test-files.s3.us-west-2.amazonaws.com/document-parser/sample-invoice.pdf\",
\"options\": {
\"extraJobs\": [
{
\"type\": \"textSense\",
\"option\": {
\"reqType\": \"Document\",
\"reqOption\": {
\"SearchAPI\": [
{
\"Type\": \"FindRegion\",
\"Name\": \"test1\",
\"Key\": [
[
103.79577464788731,
27.91146881287729
],
[
179.24396378269623,
56.97786720321933
]
]
},
{
\"Type\": \"FindRegion\",
\"Name\": \"test2\",
\"Key\": [
[
181.42454728370228,
26.167002012072373
],
[
274.31740442655985,
59.594567404426414
]
]
}
]
},
\"outputType\": \"json\",
\"pages\": \"all\"
}
}
]
}
}"