How to use the free OCR API

Top

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 OCR.space 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.

OCR API Tier Free PRO PRO PDF
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
Buy PRO
API Key
Buy PRO PDF
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).

Top

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

OCR.space Local Self-hosted, On-Premise OCR Server

OCR.space Local - Enterprise Image and PDF OCR
OCR.space is powerful server-based OCR software for automated document capture and PDF conversion. With OCR.space 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 OCR.space PRO PDF plan, but runs 100% local and never contacts the Internet.
For more information and to order OCR.space Local licenses please contact sales.
Top

The Free OCR API Endpoint (POST)

Free OCR APIhttps://api.ocr.space/parse/image The API supports https:// (SSL) and plain http:// connections.

Top

"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):
https://api.ocr.space/parse/imageurl?apikey=helloworld&url=http://i.imgur.com/fwxooMv.png

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:
https://api.ocr.space/parse/imageurl?apikey=helloworld&url=http://i.imgur.com/s1JZUnd.gif&language=chs&isOverlayRequired=true

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. This also means your API key will be sent as a part of the unencrypted URL query string. This is not a security problem because even if somebody gains access to your personal API key, he or she can access no 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.

Top

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]
Arabic=ara
Bulgarian=bul
Chinese(Simplified)=chs
Chinese(Traditional)=cht
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
Norwegian = nor
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 Overwrites the automatic file type detection based on content-type.
detectOrientation [Optional] true/false If set to true, the api autorotates the image correctly and sets the TextOrientation parameter in the JSON response. Autorotation is for images only, not PDF.
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. In the front page demo, this parameter is set to true.

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).

Top

Response

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
IMAGE / PAGE PARSING RESULT
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
Top

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 OCR.space" in the lower right corner. With the PRO OCR API, no watermark is added to the PDF.

Top

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.

cURL command-line

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

curl https://api.ocr.space/Parse/Image -H "apikey:helloworld" --data "isOverlayRequired=true&url=http://dl.a9t9.com/blog/ocr-online/screenshot.jpg&language=eng"

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" https://api.ocr.space/Parse/Image

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" https://api.ocr.space/parse/image

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

Top

C# (Visual Studio Project)

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

C# Test APP for OCR API/SDK

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 OCR.space PRO API and the full C# source code is available.

Top

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.

Top

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).

Top

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 .

Top

Python

Here is an example of how to access the API from Python using the requests.post 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).

Top

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.

Top

C++/QT

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.

Top

Ruby

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

Top

Javascript

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.

Top

NPM

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

Top

Jquery

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: https://api.ocr.space/parse/image,
  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. ..........................
  52. LOOP THROUGH THE LINES AND GET WORDS TO DISPLAY ON TOP OF THE IMAGE AS OVERLAY
  53. ..........................
  54. ..........................
  55. ..........................
  56. });
  57. ..........................
  58. ..........................
  59. ..........................
  60. YOUR CODE HERE
  61. ..........................
  62. ..........................
  63. ..........................
  64. });
  65. }
  66. }
  67. });
Top
Copyfish for Chrome/Firefox
Follow OCR API on Twitter
View the OCR API Status
Try Kantu Web Automation
Selenium IDE for Chrome
Try our Copyfish 🐟 Free OCR Software Chrome and Firefox extension: Extract and translate text from any image, video or PDF. It's fun to use - and powered by our OCR API. The full source code is available on GitHub (OSI-certified Open-Source).

OCR software or OCR API questions? Please contact the OCR team - we love to answer OCR questions.