How to use the free OCR API


Getting Started

API Basics

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. The API can be used from any internet-connected device (desktop, mobile, iPhone, Android, Windows phone, refrigerator...). For even faster response times and guaranteed uptime PRO plans are available. In addition, we offer a locally (on-premise) installable version with our Local Enterprise plan.

Get Your Free OCR API Key

The OCR API has three tiers/levels. If you want to use the free tier register here for your free OCR API key. It has a rate limit of 500 requests within one day per IP address to prevent accidental spamming.

Pricing Free US$24.95/month US$49.95/month
Requests/month 25,000 250,000 250,000
Additional conversions n/a US$10/100,000 US$20/100,000
API Key Register for
free API key
File Size Limit 1 MB 5 MB 100 MB+
PDF OCR Page Limit 3 (images only) 999+
Make Searchable PDF Yes (with watermark) Yes, from images Yes
Commercial use allowed Yes Yes Yes
Speed Fast Faster (more servers, lower load)
Rate Limit* 500 calls/DAY 600 calls/1min 600 calls/1min
Service-level agreement (SLA) n/a 100% uptime or money back
(dedicated, redundant servers in USA/EU/Asia)
*The rate limit is per IP address. For the PRO plans, we can adjust the default rate limit at no extra cost.

Example: If you use a PRO API key inside a mobile phone app, every user (= every unique IP address) has a rate limit of 60 OCR conversions within one minute. So, different users cannot block each other. That should be enough for most use cases, but if you need a higher limit, simply let us know and we will increase your rate limit. For more information about the API see the OCR API FAQ page.

You can check the API performance and uptime at the API status page.

Now it's time to get started: Below you find example code for calling the API from Postman, AutoHotKey (AHK), cURL, C#, Delphi, iOS, Java (Android app), Python, C++/QT, Ruby, and Javascript. (If you have code examples for other languages, please let us know and we will add them to this list).


Faster OCR with the PRO plans

For our OCR PRO plans we use redundant high-performance API endpoints in the US, EU and Asia regions. We guarantee 100% uptime or money back.

You can subscribe to the PRO plans either as monthly plan (PRO monthly and PRO PDF monthly ) or as yearly pre-paid plans with a 20% discount (PRO yearly and PRO PDF yearly). You can cancel your subscription anytime and we will not bill you again. We do not store your credit card information on our servers. If you cannot pay via credit card, let us know. We also offer pre-paid plans with other payment options like invoice, PayPal, wire transfer, purchase order and many local options such as Alipay for China. If our PRO/PRO PDF plans do not fit your use case, please contact us for a custom quote.

The PRO OCR API runs on physically different servers then our free OCR API service. You receive the URLs for the three global PRO endpoints and your API key in the welcome email directly after you have signed-up for the PRO or PRO PDF account.

Top Local Self-hosted, On-Premise OCR Server Local - Enterprise Image and PDF OCR is powerful server-based OCR software for automated document capture and PDF conversion. With Local you can install and host our popular OCR API and Searchable PDF creation software on your own PC and/or inside your data-center. The installation on virtualized and cloud environments like Amazon AWS AMI or Microsoft Azure is fully supported. Technically the local OCR server is identical to our popular online OCR API service.

The on-premise version has the same features, same API parameters and the same OCR quality as the PRO PDF plan, but runs 100% local and offline - it never contacts the Internet.
For more information and to order Local licenses please contact sales.

The Free OCR API Endpoint (POST)

Free OCR API The API supports https:// (SSL) and plain http:// connections.


"GET" OCR API Endpoint

Using an OCR API was never easier...

Besides the full-featured "POST" OCR API at /parse/image we provide an additional OCR API endpoint at /parse/ImageUrl for GET requests. While not as versatile as the POST API, it is easy to use. Everything you need for the api call is inside the URL.

Example (just click the link to start the OCR):

The default OCR language is English. To use another language, add &language to the url. You can also request the x/y word coordinates with isOverlayRequired:

The important limitation of the GET api endpoint is it only allows image and PDF submissions via the URL method, as only HTTP POST requests can supply additional data to the server in the message body. GET requests include all required data in the URL. So by design, a GET api cannot support file uploads (file parameter) or BASE64 strings (base64image).

The GET API is easy and fast to use. Just note that the URL with the api key might be stored in your browser's history. But this is not a security problem because even if somebody gains access to your personal API key, he or she can not access any information about you or the OCR'ed documents, because we do not store such information in the first place. The worst-case scenario is that somebody uses all your free conversions. If this might be a problem for your application, simply continue to use the fully SSL-encrypted POST version of the API or switch to the PRO OCR API, which provides additional options.


Post Parameters

The table below lists all possible API parameters. As additional documentation, we published a sample api call collection that you can load into Postman. And last but not least: Our free online ocr form on the front page is nothing else than a POST call to the free OCR API endpoint and can be used for testing as well.

Key Value Description
apikey API Key (send in the header) Get your free API key
url or file or base64Image 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
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.
language [Optional]
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 [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 [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 [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 [Optional] Boolean value Default = False
If true, API generates a searchable PDF. This parameter automatically sets isOverlayRequired = true.
isSearchablePdfHideTextLayer [Optional] Boolean value Default = False. If true, the text layer is hidden (not visible)
scale [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 [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 [Optional] 1 or 2 The default is engine 1. OCR Engine 2 is a new image-processing method.

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.



The API returns results in JSON format. The result typically contains the ExitCode, Error details (if occurred) and a bunch of parsed results for the Image / PDF pages. Please check below the response the Web API returns and definition of various parameters. The illustration below shows success and error responses.

Key Value Description
ParsedResults OCR results The OCR results for the image or for each page of PDF. For PDF: Each page has its own OCR result and error message (if any)
OCRExitCode Integer The exit code shows if OCR completed successfully, partially or failed with error

1: Parsed Successfully (Image / All pages parsed successfully)
2: Parsed Partially (Only few pages out of all the pages parsed successfully)
3: Image / All the PDF pages failed parsing (This happens mainly because the OCR engine fails to parse an image)
4: Error occurred when attempting to parse (This happens when a fatal error occurs during parsing )
IsErroredOnProcessing true/false If an error occurs when parsing the Image / PDF pages
ErrorMessage Text The error message of the error occurred when parsing the image
ErrorDetails Text Detailed error message
SearchablePDFURL Link See Searchable PDF
FileParseExitCode Exit code for each parsed result The exit code returned by the parsing engine
0: File not found
1: Success
-10: OCR Engine Parse Error
-20: Timeout
-30: Validation Error
-99: Unknown Error
ParsedText Parsed Text The parsed text for an image
TextOverlay Overlay data for the text in the image/pdf Only if 'isOverlayRequired' is set to 'True'
Lines An array of lines in the overlay text This contains an array of all the lines. Each line will contain an array of words
Words An array of words in a line This contains the words with the specific details of a word like its text and position
WordText Text of the word This contains the text of that specific word
Left Distance of word from left (in pixels (px)) Contains the distance (in px) of the word from the left edge of the imagee
Top Distance of word from top (in px) Contains the distance (in px) of the word from the top edge of the image
Height Height of the word Contains the height (in px) of the word
Width Width of the word Contains the width (in px) of the word
MaxHeight Maximum height of the line Contains the height (in px) of the line
MinTop Minimum distance of the line from the top edge of image Contains the distance (in px) of the line from the top edge in the original size of image
HasOverlay Overlay is present or not True/False depending upon if the overlay for the parsed result is present or not
ErrorMessage Text Error message returned by the parsing engine
ErrorDetails Text Detailed error message returned from the parsing engine for debugging purposes

Searchable PDF

You can create searchable PDFs (sometimes also called Sandwich PDFs) directly via the API. The PDF is returned as download link in the API JSON response the form of "SearchablePDFURL": "...". The download link is valid for one hour, after this time the document is deleted from our OCR servers.

The isCreateSearchablePdf = true switch triggers the generation of the searchable PDF. By default, the added text layer is visible - - this is ideal for testing the result as you can compare the OCR'ed output directly with the scan image. By adding isSearchablePdfHideTextLayer = true you make the text layer invisible. Creating a searchable PDF from the OCR result takes additional processing time, so you should only activate this feature if you need the OCR result in PDF format.

Searchable PDF API Test with Postman

NOTE: You must use both parameters, isCreateSearchablePdf = true and isSearchablePdfHideTextLayer = false or true, otherwise the generated PDF contains no text layer.

When used with the free OCR API tier, the generated PDF contains a watermark "Generated by" in the lower right corner. With the PRO OCR API, no watermark is added to the PDF.


Code Examples

Test API with the Postman App

Getting started: Use the free Postman Chrome app to test the OCR API and play with the different parameters.

Tip: If you have Postman installed you can click the "Run in Postman" button above to import a set of five API test calls to Postman. The samples use the "helloworld" api key and are ready to run without any further edits.

(a) Provide image/PDF to be OCR'ed via URL

The screenshots below show the settings for sending the image/PDF via a URL. Note that the encoding is set to multipart/form-data.

Test OCR API via Postman

(b) Upload image/PDF to be OCR'ed from your server/PC

Same Postman app, but this time we are using the "File" setting to upload the image or PDF.

Upload PDF scan for OCR via Postman

(c) Send image as Base64 string

Same Postman app, but this time, we are using the "Base64Image" parameter to send the image as string.

Base64 testing with Postman

Tip: Make sure there is no extra "new line" after pasting a base64 string into Postman. If there is, the API will (rightfully) return a "Not a valid base64 image." error.

Test BASE64 strings: Image Base64 String, PDF as Base64 string. The links open a text file in the browser. You can paste the content of these text files directly into the "base64image" field of Postman, or any other test code.

cURL command-line

(a) Provide image/PDF to be OCR'ed via URL

curl -H "apikey:helloworld" --data "isOverlayRequired=true&url="

curl is an open source command line tool and library for transferring data with URL syntax. The libcurl library is portable. It builds and works identically on nearly any platform (Windows, Mac, Linux,...).

(b) Upload image/PDF to be OCR'ed from your server/PC

curl -H "apikey:helloworld" --form "file=@screenshot.jpg" --form "language=eng" --form "isOverlayRequired=true"

Note: @screenshot.jpg assumes an image with name "screenshot.jpg" is in the same directory as cURL.exe. Note that the isOverlayrequired (default: no) and the language (default: eng) parameters are optional.

(c) Send image as string in Base64 format

curl -H "apikey:helloworld" --form "base64Image=data:image/jpeg;base64,/9j/AAQSk [Long string here ]" --form "language=eng" --form "isOverlayRequired=false"

The base64 string in this example is truncated. You can download the full command line as Windows batch file from GitHub.

Test BASE64 strings: Image Base64 String, PDF as Base64 string. The links open a text file in the browser. You can paste the content of these text files directly into the "base64image" field of the cURL command line.


C# (Visual Studio Project)

There is a ready-to-use Visual Studio C# sample project for using the OCR API from C# on GitHub.


The test app allows you to upload and test any image quickly with the OCR API.

For a real-life example, look at the popular "ShareX" productivity tool:

ShareX Screenshot OCR

ShareX uses the PRO API and the full C# source code is available.


iOS: Objective-C and Swift

The user-provided code snippets for Objective-C and Swift are a good starting point for iPhone apps with OCR features.


Android: Java

Using Android? Look at this Android sample app that uses the free OCR API. The Java app shows how to call the API using HttpsURLConnection (thanks to user "bsuhas" for providing this code snippet).


PHP OCR API Demo Web App

For PHP we have a complete, ready-to-run demo web app that allows the user to select a document and then uploads the image or PDF document to the OCR API.

Calling the OCR API from PHP
You find the full source code at Github .



Here is an example of how to access the API from Python using the command.

Calling the OCR API from Python

The full source code can be found on GitHub (thanks to user "Zaargh" for providing this code snippet). Another Python wrapper for our OCR SDK is available from GitHub user a4fr (thanks to everyone for creating code snippets).


AutoHotKey (AHK)

AHK is a popular Windows Macro Recorder. For windows automation projects that require to recognize text on images you can connect to the OCR API with CreateFormData(PostData, ContentType, oForm). This AHK forum post has the details.



Using C++? Jhiroka from UCLA shared this example with us: C++/QT OCR API sample app.

If you are using the C++ Casablanca Library for the HTTP POST call, note that you need to url encode the image data on top of Base64 encoding. The C++ library Casablanca does not seem to do this automatically (unlike Postman does), so use the function web::uri::encode_data_string to encode the file data after Base64 encoding the request.



Using Ruby? Suyesh shared this Ruby gem (library) with us: OCR API Ruby gem.



Chrome extension

The open-source Copyfish Chrome and Firefox extension uses our OCR API. You find its Javascript source code here. This includes code that shows how to process the returned text overlay data. Note the Copyfish extension uses the PRO OCR API version.

Calling the OCR API from Javascript

Test it: You can install the Copyfish OCR extension in Chrome and Firefox.



User Dennis.K published a NPM package for the OCR API.



User Matteo made a Github repository with a Go module for the OCR API.



This is a JQuery example showing how to make a request to the api using AJAX and get the image results for processing.

  1. //Prepare form data
  2. var formData = new FormData();
  3. formData.append("file", fileToUpload);
  4. formData.append("url", "URL-of-Image-or-PDF-file");
  5. formData.append("language" , "eng");
  6. formData.append("apikey" , "Your-API-Key-Here");
  7. formData.append("isOverlayRequired", True);
  8. //Send OCR Parsing request asynchronously
  9. jQuery.ajax({
  10. url:,
  11. data: formData,
  12. dataType: 'json',
  13. cache: false,
  14. contentType: false,
  15. processData: false,
  16. type: 'POST',
  17. success: function (ocrParsedResult) {
  18. //Get the parsed results, exit code and error message and details
  19. var parsedResults = ocrParsedResult["ParsedResults"];
  20. var ocrExitCode = ocrParsedResult["OCRExitCode"];
  21. var isErroredOnProcessing = ocrParsedResult["IsErroredOnProcessing"];
  22. var errorMessage = ocrParsedResult["ErrorMessage"];
  23. var errorDetails = ocrParsedResult["ErrorDetails"];
  24. var processingTimeInMilliseconds = ocrParsedResult["ProcessingTimeInMilliseconds"];
  25. //If we have got parsed results, then loop over the results to do something
  26. if (parsedResults!= null) {
  27. //Loop through the parsed results
  28. $.each(parsedResults, function (index, value) {
  29. var exitCode = value["FileParseExitCode"];
  30. var parsedText = value["ParsedText"];
  31. var errorMessage = value["ParsedTextFileName"];
  32. var errorDetails = value["ErrorDetails"];
  33. var textOverlay = value["TextOverlay"];
  34. var pageText = '';
  35. switch (+exitCode) {
  36. case 1:
  37. pageText = parsedText;
  38. break;
  39. case 0:
  40. case -10:
  41. case -20:
  42. case -30:
  43. case -99:
  44. default:
  45. pageText += "Error: " + errorMessage;
  46. break;
  47. }
  48. $.each(textOverlay["Lines"], function (index, value) {
  49. ..........................
  50. ..........................
  51. ..........................
  53. ..........................
  54. ..........................
  55. ..........................
  56. });
  57. ..........................
  58. ..........................
  59. ..........................
  61. ..........................
  62. ..........................
  63. ..........................
  64. });
  65. }
  66. }
  67. });
View OCR API Performance
Follow OCR API on Twitter
UI Vision Free RPA Software
Copyfish OCR Browser Extension
Selenium IDE
Try UI.Vision RPA, our OCR-powered Robotic Process Automation (RPA) software. It is available as free browser extension as RPA Chrome and RPA Firefox (OSI-certified Open-Source) plus computer-vision extension modules. UI.Vision RPA is fun to use - and its OCR screen scraping features are powered by the OCR API.

Do you have an OCR API question? Please email us or visit the OCR API Forum - we love to answer OCR questions.