How to use the free OCR API

Getting Started

API Basics

The free OCR API provides you with a simple way of parsing images and even multi-page PDF documents 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...). The OCR API was first built for our own use, but - the more people use it, the more stable and robust the solution gets over time. So... please use it and please help spread the word! A tweet or link back is always appreciated.

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 1 MB 5 MB+
PDF OCR Page Limit 3 (images only) 999+
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 can not block each other. That should be enough for most use cases, But if you need a higher limit, simply let us know and we increase your rate limit.

You can check the API performance and uptime at the API status page. For our OCR PRO plans, we have 100% redundant API endpoints in the US, EU and Asia regions. For more information about the API in general see the OCR API FAQ page. If our PRO/PRO PDF plans do not fit your use case, please contact us at ocrspace AT a9t9.com for a custom quote.

Now get started.... below you find example code for calling the API from Postman, cURL, C#, Python, iOS, Java (Android app),C++/QT, and Javascript. (If you have code examples for other languages, please let us know and we add them to this list).

The Free OCR API Endpoint

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

PRO Plans Payment options

You can subscribe to the PRO plans via the PRO and PRO PDF links. You are billed monthly and you can cancel anytime. We do not store your credit card information on our servers. If you can not pay via credit card, let us know. We also offer pre-paid quarterly, half-yearly and yearly plans with other payment options like Paypal, wire transfer, purchase order and many local options such as Alipay for China.

You will receive the URLs of 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

Post Parameters

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
file: Multipart encoded image file with filename
base64Image: Image as Base64 encoded string
You can use three differents methods to upload the input image or PDF.
language [Optional] Chinese(Simplified)=chs
Chinese(Traditional)=cht
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
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 indicating if the overlay is required along with the image/pdf parsed result Default = False
Allows you to specify if the image/pdf text overlay is required. Overlay could be used to show the text over the image
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 that the Web API returns and definition of various parameters. The illustration below shows both success as well as error responses.

Key Value Description
ParsedResults An Array of all parsed results The parsed results for image file / each page of PDF. Each has its own exit code, parsed result and error message (if any)
OCRExitCode Primary exit code returned by the application for parsed results The exit code signifies if the parsing of image / pdf 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 maily because the Parsing engine fails to parse an image)
4: Error occurred when attempting to parse (This happens when a fatal error occurs during parsing image / PDF)
IsErroredOnProcessing true/false If an error occurrs when parsing the Image / PDF pages
ErrorMessage The error message The error message of the error occurred when parsing the image
ErrorDetails The details of the error message The detailed error message
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 An array of overlay of the text in the image/pdf If, 'isOverlayRequired' is set to 'True', then this will contain the text overlay for the image/pdf
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) Contains the distance (in Pixels) of the word from the left edge of the original size of image
Top Distance of word from top (in Pixels) Contains the distance (in Pixels) of the word from the top edge of the original size of image
Height Height of the word Contains the height (in Pixels) of the word in the original size of image
Width Width of the word Contains the width (in Pixels) of the word in the original size of image
MaxHeight Maximum Height of the line Contains the height (in Pixels) of the line in the original size of image
MinTop Minimum distance of the line from the top edge of image Contains the distance (in Pixels) 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 Error Message Error message returned by the parsing engine
ErrorDetails Error Details Detailed error message returned from the parsing engine for debugging purposes
Top

Code Examples

Test API with the Postman Chrome App

Getting started: Use the free Postman Chrome app to test the OCR API and play with the different parameters.
Tip: The complete Postman collection of API test calls (including a Base64 example) is available on Github. You can download it from there and import it to Postman.

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

The screenshots below shows 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 note that we are using the "File" setting to upload the image or PDF.

Upload PDF scan for OCR via Postman

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 pretty much 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) paramaters 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.

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 quickly upload and test any image with the OCR API.

For a real-life example have a 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.

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? Have a 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).

Python

Here is an example on 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).

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.

C++/QT

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

Javascript

Chrome extension

The open-source Copyfish Chrome 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 that the Copyfish extension uses a "PRO" version of our OCR service. It uses the same OCR engine but runs on different, dedicated OCR servers with a guaranteed uptime. If you are interested in using this service, too, please contact us for pricing.

Calling the OCR API from Javascript

Test it: You can install the Copyfish OCR extension directly from its page in the Chrome store.

Jquery

This is a JQuery example showing how to make a request to the api using AJAX and getting 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: 'form/multipart' (NOT json!),
  13. cache: false,
  14. contentType: false,
  15. processData: false,
  16. type: 'json',
  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
Get Copyfish for Chrome
Follow OCR API on Twitter
View the OCR API Status
Try Kantu Web Automation
Try our Copyfish 🐟 Free OCR Software Chrome extension: Extract and translate text from any image, video or PDF.
It's fun to use - and powered by this OCR API. The full source code is availabe on GitHub (OSI-certified Open-Source).

Contact info: team (at) a9t9.com or use this contact form.