Apr-2020 @

OCR::OcrSpace - Perl Interface to access

The free OCR API provides a simple way of parsing images and multi-page PDF documents (PDF OCR) and getting the extracted text results returned in a JSON format.

This module implemented the Post request only.

Extract text from images , pdf via ocr-space


Version 0.01


    #using object oriented interaface
    use OCR::OcrSpace;

    my $ocrspace_obj = OCR::OcrSpace->new();

    my $param = {
        file                         => '/tmp/image.png',                     #full iamge path


        url                         => ''   #image url to fetch from


        base64Image                 => 'data:image/png;base64,iVBORw0KGgoAx7/7LNuCQS0posnocgEAFpySUVORK5CYII='

        #following optional parameter
        ocr_space_url                  => "",  
        apikey                         => 'XXXXXXXXXXXXXXXXXX',                 #API Key (mandatory)
        isOverlayRequired              =>'True',                                #optional
        language                       =>'eng' ,                                #optional
        scale                          => 'True',                               #optional
        isTable                        => 'True',                               #optional
        OCREngine                      => 2,                                    #optional
        filetype                       => 'PNG',                                #optional
        detectOrientation              => 'False',                              #optional
        isCreateSearchablePdf          => 'True',                               #optional
        isSearchablePdfHideTextLayer   => 'True',                               #optional


    print $ocrspace_obj->get_result( $param );

    #using non-object oriented interaface

    use OCR::OcrSpace;
    print get_result( $param );

    #since ocrSpace uses http as well as HTTPs you can always set the following varible before call






    used to create a constructor of OCR::OcrSpace for object oriented mode


     params hash ref of following valid keys
  • invocant { optional but required when using object oriented interface }

  • ocr_space_url { optional url if you want to use https mention url }

    ocr_space_url scalar string ([Optional] Default

  • apikey { scalar string }

    apikey API Key (send in the header)

    get your key from here

  • url or file or base64Imag

    url or file or base64Imag You can use three methods to upload the input image or PDF. We recommend the URL method for file sizes > 10 MB for faster upload speeds.

        url: URL of remote image file (Make sure it has the right content type)
        file: Multipart encoded image file with filename
        base64Image: Image as Base64 encoded string
  • language


        Croatian = hrv
        Czech = cze
        Danish = dan
        Dutch = dut
        English = eng
        Finnish = fin
        French = fre
        German = ger
        Greek = gre
        Hungarian = hun
        Korean = kor
        Italian = ita
        Japanese = jpn
        Polish = pol
        Portuguese = por
        Russian = rus
        Slovenian = slv
        Spanish = spa
        Swedish = swe
        Turkish = tur

    Language used for OCR. If no language is specified, English eng is taken as default.

    IMPORTANT: The language code has always 3-letters (not 2). So it is "eng" and not "en".

  • isOverlayRequired

    isOverlayRequired scalar string ([Optional] Boolean value)

    Default = False If true, returns the coordinates of the bounding boxes for each word. If false, the OCR'ed text is returned only as a text block (this makes the JSON reponse smaller). Overlay data can be used, for example, to show text over the image.

  • filetype

    filetype scalar string (Optional] String value: PDF, GIF, PNG, JPG, TIF, BMP)

    Overwrites the automatic file type detection based on content-type. Supported image file formats are png, jpg (jpeg), gif, tif (tiff) and bmp. For document ocr, the api supports the Adobe PDF format. Multi-page TIFF files are supported.

  • detectOrientation

    detectOrientation scalar string ([Optional] true/false)

    if set to true, the api autorotates the image correctly and sets the TextOrientation parameter in the JSON response. If the image is not rotated, then TextOrientation=0, otherwise it is the degree of the rotation, e. g. "270".

  • isCreateSearchablePdf

    isCreateSearchablePdf scalar string ([Optional] Boolean value)

    Default = False If true, API generates a searchable PDF. This parameter automatically sets isOverlayRequired = true

  • isSearchablePdfHideTextLayer

    isSearchablePdfHideTextLayer scalar string ([Optional] Boolean value)

    Default = False. If true, the text layer is hidden (not visible)

  • scale

    scale scalar string ([Optional] true/false)

    If set to true, the api does some internal upscaling. This can improve the OCR result significantly, especially for low-resolution PDF scans. Note that the front page demo uses scale=true, but the API uses scale=false by default. See also this OCR forum post.

  • isTable

    isTable scalar string ([Optional] true/false)

    If set to true, the OCR logic makes sure that the parsed text result is always returned line by line. This switch is recommended for table OCR, receipt OCR, invoice processing and all other type of input documents that have a table like structure.

  • OCREngine

    OCREngine scalar int ([Optional] 1 or 2)

    The default is engine 1. OCR Engine 2 is a new image-processing method.

Notes from

Tip: When serving images from an Amazon AWS S3 bucket or a similar service for use with the "URL" parameter, make sure it has the right content type. It should not be "Content-Type:application/x-www-form-urlencoded" (which seems to be the default) but image/png or similar. Alternatively you can include the filetype parameter and tell the API directly what type of document you are sending (PNG, JPG, GIF, PDF).

New: If you need to detect the status of checkboxes, please contact us about the Optical Mark Recognition (OMR) (Beta) features.

Select the best OCR Engine

New: We implemented a second OCR engine with a different processing logic. It is better than the default engine (engine1) in certain cases. So we recommend that you try engine1 first (since it is faster), but if the OCR results are not perfect, please try the same document with engine2. You can use the new OCR engine with our free online OCR service on the front page, and with the API.

Features of OCR Engine 1:

- Supports more languages (including Asian languages like Chinese, Japanese and Korean)

- Faster

- Supports larger images

- PDF OCR and Searchable PDF creation support

- Multi-Page TIFF scan support

- Parameter: OCREngine=1

Features of OCR Engine 2:

- Western Latin Character languages only (English, German, French,...)

- Language auto-detect (so it does not really matter what OCR language you select, as long as it uses Latin characters)

- Usually better at single number OCR and alphanumeric OCR (e. g. SUDOKO, Dot Matrix OCR, MRZ OCR,... )

- Usually better at special characters OCR like @+-...

- Image size limit 5000px width and 5000px height

- Parameter: OCREngine=2

- No PDF OCR and Offline OCR yet. If you need this, please contact us for an internal beta.

The returned OCR result JSON response is identical for both engines! So you can easily switch between both engines as needed. If you have any question about using Engine 1 or 2, please ask in our OCR API Forum.

Sample Ouput success

    {"ParsedResults":[{"TextOverlay":{"Lines":[{"LineText":"Current","Words":[{"WordText":"Current","Left":11.666666030883789,"Top":59.166664123535156,"Height":14.999999046325684,"Width":54.999996185302734}],"MaxHeight":14.999999046325684,"MinTop":59.166664123535156},{"LineText":"59","Words":[{"WordText":"59","Left":32.5,"Top":239.99998474121094,"Height":20.833332061767578,"Width":29.166666030883789}],"MaxHeight":20.833332061767578,"MinTop":239.99998474121094}],"HasOverlay":true,"Message":"Total lines: "2"},"TextOrientation":"0","FileParseExitCode":1,"ParsedText":"Current\t\r\n59\t\r\n","ErrorMessage":"","ErrorDetails":""}],"OCRExitCode":1,"IsErroredOnProcessing":false,"ProcessingTimeInMilliseconds":"437","SearchablePDFURL":""}

Sample Ouput error

    {"OCRExitCode":99,"IsErroredOnProcessing":true,"ErrorMessage":["Parameter name 'attributes' is invalid. Valid parameters: apikey,url,language,isoverlayrequired,base64image,iscreatesearchablepdf,issearchablepdfhidetextlayer,filetype,addressparsing,scale,detectorientation,istable,ocrengine,detectcheckbox,checkboxtemplate,checkboxtemplateregex","Please check if you need to URL encode the URL passed in request parameters."],"ProcessingTimeInMilliseconds":"0"}


sushrut pajai, <spajai at>


Please report any bugs or feature requests to bug-ocr-ocrspace at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc OCR::OcrSpace

You can also look for information at:



This software is copyright (c) 2020 by sushrut pajai.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.