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.

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 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 for a custom quote.

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

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

The Free OCR API Endpoint (POST)

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


"GET" OCR API Endpoint

Using an OCR API was never easier...

In addition to 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 extremly 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 that 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. In contrast, GET requests include all required data in the URL. So by design, a GET api can not support file uploads (file parameter) or BASE64 strings (base64image).

The GET API is designed to be very easy and fast to use. This also means that your API key will be send as a part of the unencrypted URL query string. This is not a security problem because even if somebody would gain 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 up all your free conversions. If this might be a problem for your application, simply continue use the fully SSL-encrypted POST version of the API or switch to the PRO OCR API, which provides additional options.


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


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

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 -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 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"

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"

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.


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


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

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.

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.


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


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 the PRO OCR API version.

Calling the OCR API from Javascript

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


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:,
  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. });
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).

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