class Abbyy::Client

Overview

Abbyy API-Client

The API of ABBYY Cloud OCR SDK uses HTTP POST and HTTP GET methods for sending data to an HTTP server. The parameters of requests are specified in the URL string.

Cloud OCR SDK server requires authentication before allowing access to its resources on the Internet. To authenticate on the server, you need a registered Application ID and Application Password.

See details in the Authentication section.

See http://ocrsdk.com/documentation/apireference/.

Defined in:

abbyy/client.cr

Constant Summary

USER_AGENT = "Abbyy-Client/#{VERSION} (Crystal Client)"

User-Agent

Constructors

Instance Method Summary

Constructor Detail

def self.new(application_id : String, password : String, language : Abbyy::Language | Nil = nil) #

[View source]

Instance Method Detail

def api_url : String #

Base url of the api.


[View source]
def api_url=(api_url : String) #

Base url of the api.


[View source]
def application_id : String #

User's Application ID.


[View source]
def application_id=(application_id : String) #

User's Application ID.


[View source]
def delete_task(request : DeleteTaskRequest) : DeleteTaskResponse #

The method deletes the task and the images associated with this task from the ABBYY Cloud OCR SDK storage. Only the tasks that have the status other than TaskStatus::InProgress or TaskStatus::Deleted can be deleted.

If you try to delete the task that has already been deleted, the successful response is returned.

If you submit the same image to different tasks, to delete the image from the Cloud OCR SDK storage, you will need to call the #delete_task method for each task, which contains the image.


[View source]
def delete_task(task_id : String) : DeleteTaskResponse #

[View source]
def download_task_result(task_response : TaskResponse, wait_until_complete : Bool = true) : TaskResult | Nil #

[View source]
def download_task_result(task : Task, wait_until_complete : Bool = true) : TaskResult | Nil #

[View source]
def download_task_result(task_id : String, wait_until_complete : Bool = true) : TaskResult | Nil #

[View source]
def get_application_info : GetApplicationInfoResponse #

This method allows you to receive information about the application type, its current balance and expiration date.

The application is identified by its authentication information.

By default the call to this method is disabled for all applications. To enable getting the application information using this method:

  • go to http://cloud.ocrsdk.com/ and log in
  • click Settings under your application's name
  • on the next screen, click enable

[View source]
def get_task_status(request : GetTaskStatusRequest) : GetTaskStatusResponse #

The method returns the current status of the task and the URL of the result of processing for completed tasks. The hyperlink has limited lifetime. If you want to download the result after the time has passed, call the #get_task_status or #list_tasks method to obtain the new hyperlink.

See here for the description of all statuses a task can have.

Please note that the task status is not changed momentarily. Do not call this method more frequently than once in 2 or 3 seconds.


[View source]
def get_task_status(task_id : String) : GetTaskStatusResponse #

[View source]
def language : Language | Nil #

Default language setting for recognize text.


[View source]
def language=(language : Language | Nil) #

Default language setting for recognize text.


[View source]
def list_finished_tasks #

The method returns the list of finished tasks. A task is finished if it has one of the following statuses: TaskStatus::Completed, TaskStatus::ProcessingFailed, TaskStatus::NotEnoughCredits.

The tasks are ordered by the time of the end of processing. No more than 100 tasks can be returned at one method call. To obtain more tasks, delete some finished tasks using the #delete_task method and then call the #list_finished_tasks method again.

The method may be useful if you work with a large number of tasks simultaneously. But there is no sense in calling this method if your application does not have any incomplete tasks sent for the processing.

Please note that the task status is not changed momentarily. Do not call this method more frequently than once in 2 or 3 seconds.


[View source]
def list_tasks(request : ListTasksRequest | Nil) : ListTasksResponse #

The method returns the list of tasks created by your application. By default, the TaskStatus::Deleted tasks are included, but you can filter them out.

The tasks are ordered by the date of the last action with the task. This method can list up to 1000 tasks. If you process a large number of tasks, call this method for shorter time periods.


[View source]
def list_tasks(from_date : Time | Nil = nil, to_date : Time | Nil = nil, exclude_deleted : Bool | Nil = nil) : ListTasksResponse #

[View source]
def password : String #

User's password for authenticaion.


[View source]
def password=(password : String) #

User's password for authenticaion.


[View source]
def perform_barcode_field_processing(request : ProcessBarcodeFieldRequest) : TaskResult | Nil #

Performs a #process_barcode_field call and downloads the result.


[View source]
def perform_barcode_field_processing(file_path : String, region : Region | Nil = nil, barcode_type : BarcodeType | Array(BarcodeType) | Nil = nil, contains_binary_data : Bool | Nil = nil, description : String | Nil = nil, pdf_password : String | Nil = nil) : TaskResult | Nil #

[View source]
def perform_business_card_processing(request : ProcessBusinessCardRequest) : TaskResult | Nil #

Performs a #process_business_card call and downloads the result.


[View source]
def perform_business_card_processing(file_path : String, language : Language | Array(Language) | Nil = nil, image_source : ImageSource | Nil = nil, correct_orientation : Bool | Nil = nil, correct_skew : Bool | Nil = nil, export_format : ExportFormat | Nil = nil, xml_write_extended_character_info : Bool | Nil = nil, pdf_write_field_components : Bool | Nil = nil, description : String | Nil = nil, pdf_password : String | Nil = nil) : TaskResult | Nil #

[View source]
def perform_checkmark_field_processing(request : ProcessCheckmarkFieldRequest) : TaskResult | Nil #

Performs a #process_checkmark_field call and downloads the result.


[View source]
def perform_checkmark_field_processing(file_path : String, region : Region | Nil = nil, checkmark_type : CheckmarkType | Nil = nil, correction_allowed : Bool | Nil = nil, description : String | Nil = nil, pdf_password : String | Nil = nil) : TaskResult | Nil #

[View source]
def perform_document_processing(request : ProcessDocumentRequest) : TaskResult | Nil #

Performs a #process_document call and downloads the result.


[View source]
def perform_document_processing(task_id : String, language : Language | Array(Language) | Nil = nil, profile : Profile | Nil = nil, text_type : TextType | Array(TextType) | Nil = nil, image_source : ImageSource | Nil = nil, correct_orientation : Bool | Nil = nil, correct_skew : Bool | Nil = nil, read_barcodes : Bool | Nil = nil, export_format : ExportFormat | Array(ExportFormat) | Nil = nil, xml_write_recognition_variants : Bool | Nil = nil, pdf_write_tags : PdfWriteTag | Nil = nil, description : String | Nil = nil) : TaskResult | Nil #

[View source]
def perform_fields_processing(task_id : String, file_path : String, description : String | Nil = nil, write_recognition_variants : Bool | Nil = nil) : TaskResult | Nil #

[View source]
def perform_fields_processing(request : ProcessFieldsRequest) : TaskResult | Nil #

Performs a #process_fields call and downloads the result.


[View source]
def perform_image_processing(request : ProcessImageRequest) : TaskResult | Nil #

Performs a #process_image call and downloads the result.


[View source]
def perform_image_processing(file_path : String, language : Language | Array(Language) | Nil = nil, profile : Profile | Nil = nil, text_type : TextType | Array(TextType) | Nil = nil, image_source : ImageSource | Nil = nil, correct_orientation : Bool | Nil = nil, correct_skew : Bool | Nil = nil, read_barcodes : Bool | Nil = nil, export_format : ExportFormat | Array(ExportFormat) | Nil = nil, xml_write_recognition_variants : Bool | Nil = nil, pdf_write_tags : PdfWriteTag | Nil = nil, description : String | Nil = nil, pdf_password : String | Nil = nil) : TaskResult | Nil #

[View source]
def perform_mrz_processing(request : ProcessMRZRequest) : TaskResult | Nil #

Performs a #process_mrz call and downloads the result.


[View source]
def perform_mrz_processing(file_path : String) : TaskResult | Nil #

[View source]
def perform_receipt_processing(request : ProcessReceiptRequest) : TaskResult | Nil #

Performs a #process_receipt call and downloads the result.


[View source]
def perform_receipt_processing(file_path : String, country : Country | Array(Country) | Nil = nil, image_source : ImageSource | Nil = nil, correct_orientation : Bool | Nil = nil, correct_skew : Bool | Nil = nil, xml_write_extended_character_info : Bool | Nil = nil, description : String | Nil = nil, pdf_password : String | Nil = nil) : TaskResult | Nil #

[View source]
def perform_submit_image(request : SubmitImageRequest) : TaskResult | Nil #

Performs a #submit_image call and downloads the result.


[View source]
def perform_submit_image(file_path : String, task_id : String | Nil = nil, pdf_password : String | Nil = nil) : TaskResult | Nil #

[View source]
def perform_text_field_processing(request : ProcessTextFieldRequest) : TaskResult | Nil #

Performs a #process_text_field call and downloads the result.


[View source]
def perform_text_field_processing(file_path : String, region : Region | Nil = nil, language : Language | Array(Language) | Nil = nil, letter_set : String | Nil = nil, reg_exp : String | Nil = nil, text_type : TextType | Array(TextType) | Nil = nil, one_text_line : Bool | Nil = nil, one_word_per_text_line : Bool | Nil = nil, marking_type : FieldMarkingType | Nil = nil, placeholders_count : Int32 | Nil = nil, writing_style : WritingStyle | Nil = nil, description : String | Nil = nil, pdf_password : String | Nil = nil) : TaskResult | Nil #

[View source]
def proces_mrz(file_path : String) : ProcessMRZRequest #

[View source]
def process_barcode_field(request : ProcessBarcodeFieldRequest) : ProcessBarcodeFieldResponse #

The method allows you to extract the value of a barcode on an image. The method loads the image, creates a processing task for the image with the specified parameters, and passes the task for processing.

The image file is transmitted in the request body. See the list of supported input formats.

Profile::BarcodeRecognition profile is used for processing.

The result of recognition is returned in XML format. Binary data is returned in Base64 encoding.

See How to Recognize Barcodes to know another way of barcode recognition.

For details on task cost please see billing terms.


[View source]
def process_barcode_field(file_path : String, region : Region | Nil = nil, barcode_type : BarcodeType | Array(BarcodeType) | Nil = nil, contains_binary_data : Bool | Nil = nil, description : String | Nil = nil, pdf_password : String | Nil = nil) : ProcessBarcodeFieldResponse #

[View source]
def process_business_card(request : ProcessBusinessCardRequest) : ProcessBusinessCardResponse #

The method allows you to recognize a business card on an image. The method loads the image, creates a processing task for the image with the specified parameters, and passes the task for processing.

The image file is transmitted in the request body. See the list of supported input formats.

For details on task cost please see billing terms.


[View source]
def process_business_card(file_path : String, language : Language | Array(Language) | Nil = nil, image_source : ImageSource | Nil = nil, correct_orientation : Bool | Nil = nil, correct_skew : Bool | Nil = nil, export_format : ExportFormat | Nil = nil, xml_write_extended_character_info : Bool | Nil = nil, pdf_write_field_components : Bool | Nil = nil, description : String | Nil = nil, pdf_password : String | Nil = nil) : ProcessBusinessCardResponse #

[View source]
def process_checkmark_field(request : ProcessCheckmarkFieldRequest) : ProcessCheckmarkFieldResponse #

The method allows you to extract the value of a checkmark on an image. The method loads the image, creates a processing task for the image with the specified parameters, and passes the task for processing.

The image file is transmitted in the request body. See the list of supported input formats.

The result of recognition is returned in XML format. The values of checkmarks are "checked", "unchecked", or "corrected".

For details on task cost please see billing terms.


[View source]
def process_checkmark_field(file_path : String, region : Region | Nil = nil, checkmark_type : CheckmarkType | Nil = nil, correction_allowed : Bool | Nil = nil, description : String | Nil = nil, pdf_password : String | Nil = nil) : ProcessCheckmarkFieldResponse #

[View source]
def process_document(request : ProcessDocumentRequest) : ProcessDocumentResponse #

The method starts the processing task with the specified parameters.

This method allows you to process several images using the same settings and obtain recognition result as a multi-page document. You can upload several images to one task using #submit_image method.

It is also possible to specify up to three file formats for the result, in which case the server response for the completed task will contain several result URLs.

Only the task with TaskStatus::Submitted, TaskStatus::Completed or TaskStatus::NotEnoughCredits status can be started using this method.

For details on task cost please see billing terms.


[View source]
def process_document(task_id : String, language : Language | Array(Language) | Nil = nil, profile : Profile | Nil = nil, text_type : TextType | Array(TextType) | Nil = nil, image_source : ImageSource | Nil = nil, correct_orientation : Bool | Nil = nil, correct_skew : Bool | Nil = nil, read_barcodes : Bool | Nil = nil, export_format : ExportFormat | Array(ExportFormat) | Nil = nil, xml_write_recognition_variants : Bool | Nil = nil, pdf_write_tags : PdfWriteTag | Nil = nil, description : String | Nil = nil) : ProcessDocumentResponse #

[View source]
def process_fields(task_id : String, file_path : String, description : String | Nil = nil, write_recognition_variants : Bool | Nil = nil) : ProcessFieldsResponse #

[View source]
def process_fields(request : ProcessFieldsRequest) : ProcessFieldsResponse #

The method allows you to recognize several fields in a document. The method starts the processing task with the parameters of processing specified in an XML file.

The XML file with the parameters of processing is transmitted in the request body. You can use the XSD schema of the XML file to create the file with necessary settings. See also the description of the tags and several examples of XML files with settings in XML Parameters of Field Recognition.

Image files can be uploaded to the task using #submit_image method.

Only the task with TaskStatus::Submitted, TaskStatus::Completed or TaskStatus::NotEnoughCredits status can be started using this method.

The result of recognition is returned in XML format. Binary data is returned in Base64 encoding.

Note that this method is most convenient when you process a large number of fields on one page: in this case the price of recognition of all fields on one page does not exceed the price of recognition of a page of A4 size. See details in Billing terms.


[View source]
def process_image(request : ProcessImageRequest) : ProcessImageResponse #

The method loads the image, creates a processing task for the image with the specified parameters, and passes the task for processing.

The image file is transmitted in the request body. See the list of supported input formats.

This method allows you to specify up to three file formats for the result, in which case the server response for the completed task will contain several result URLs.

If there is not enough money on your account, the task will be created, but will be suspended with TaskStatus::NotEnoughCredits status. You can pass this task for processing using the #process_document method after you have topped up your account.

The task will not be created, if you exceed the limit of uploaded images.

For details on task cost please see billing terms.


[View source]
def process_image(file_path : String, language : Language | Array(Language) | Nil = nil, profile : Profile | Nil = nil, text_type : TextType | Array(TextType) | Nil = nil, image_source : ImageSource | Nil = nil, correct_orientation : Bool | Nil = nil, correct_skew : Bool | Nil = nil, read_barcodes : Bool | Nil = nil, export_format : ExportFormat | Array(ExportFormat) | Nil = nil, xml_write_recognition_variants : Bool | Nil = nil, pdf_write_tags : PdfWriteTag | Nil = nil, description : String | Nil = nil, pdf_password : String | Nil = nil) : ProcessImageResponse #

[View source]
def process_mrz(request : ProcessMRZRequest) : ProcessMRZResponse #

This method finds a machine-readable zone on the image and extracts data from it.

Machine-readable zone (MRZ) is typically found on official travel or identity documents of many countries. It can have 2 lines or 3 lines of machine-readable data. This method allows to process MRZ written in accordance with ICAO Document 9303 (endorsed by the International Organization for Standardization and the International Electrotechnical Commission as ISO/IEC 7501-1)).

The image file is transmitted in the request body. See the list of supported input formats.

The result of recognition is returned in XML format.

For details on task cost please see billing terms.


[View source]
def process_receipt(request : ProcessReceiptRequest) : ProcessReceiptResponse #

Important: the technology fully supports US receipts, other countries are currently supported in beta mode.

The method allows you to recognize the image of a receipt. The method loads the image, creates a processing task for the image with the specified parameters, and passes the task for processing.

The image file is transmitted in the request body. See the list of supported input formats.

The result is returned in XML format. The elements and attributes of the resulting file are described in Output XML with Receipt Data.

For details on task cost please see billing terms.

For a step-by-step guide, see How to Recognize Receipts. The best practices can be found at ABBYY Technology Portal.


[View source]
def process_receipt(file_path : String, country : Country | Array(Country) | Nil = nil, image_source : ImageSource | Nil = nil, correct_orientation : Bool | Nil = nil, correct_skew : Bool | Nil = nil, xml_write_extended_character_info : Bool | Nil = nil, description : String | Nil = nil, pdf_password : String | Nil = nil) : ProcessReceiptRequest #

[View source]
def process_text_field(request : ProcessTextFieldRequest) : ProcessTextFieldResponse #

The method allows you to extract the value of a text field on an image. The method loads the image, creates a processing task for the image with the specified parameters, and passes the task for processing.

The image file is transmitted in the request body. See the list of supported input formats.

Profile::FieldLevelRecognition profile is used for processing.

The result of recognition is returned in XML format.

See How to Recognize Text Fields to know how to tune the parameters.

For details on task cost please see billing terms.


[View source]
def process_text_field(file_path : String, region : Region | Nil = nil, language : Language | Array(Language) | Nil = nil, letter_set : String | Nil = nil, reg_exp : String | Nil = nil, text_type : TextType | Array(TextType) | Nil = nil, one_text_line : Bool | Nil = nil, one_word_per_text_line : Bool | Nil = nil, marking_type : FieldMarkingType | Nil = nil, placeholders_count : Int32 | Nil = nil, writing_style : WritingStyle | Nil = nil, description : String | Nil = nil, pdf_password : String | Nil = nil) : ProcessTextFieldResponse #

[View source]
def submit_image(request : SubmitImageRequest) : SubmitImageResponse #

The method adds the image to the existing task or creates a new task for the image. This task is not passed for processing until the #process_document or #process_fields method is called for it.


[View source]
def submit_image(file_path : String, task_id : String | Nil = nil, pdf_password : String | Nil = nil) : SubmitImageResponse #

[View source]