Frequently Asked Questions (FAQ)

Q: Why does it take two calls to get my OCR results, couldn't you just return them with the first call?


Unfortunately, no. The reason is that, for larger documents, the OCR analysis process may take some time, up to several minutes in the most extreme cases. Even if your application was willing to wait that long for results (which probably it wouldn't be), many intermediaries would time out an HTTP transaction that we held open that long. The cleanest model for such a transaction over HTTP/HTTPS, is the post-then-get model, which is why we use it. But rest assured we have taken that into account when allocating hits to plans.

Q: What is a "hit"? How are they calculated?


A hit is the the primary unit of measurement in calculating OCRestful plan usage. In non-technical language, a hit is either a single request made from your application to OCRestful, or another measure of resource consumption such as storing a page for a month.

 

In more technical terms, a hit is one of two things: an API transaction (GET, POST, PUT, DELETE, or HEAD) or a page-instance of storage for an OCR resource (e.g. a document you POSTED). A page-instance of storage is the initial creation of the document-page, or a month of storage for a page. So a 5-page document counts as 5 hits to create, and then 5 hits per month to store thereafter.

Taking a single-document use case, if you had a four page document you uploaded for OCR processing and then immediately retrieved results for and deleted, that would count as 7 hits:

1 POST + 1 GET + 4 page-instances + 1 DELETE = 7 hits

You could get this down to 6 hits by using an x-resource-ttl header (that is set to 12 hours or less), saving you from having to explicitly DELETE the document.

In another example, a one-page document would count for 3 hits if you use the x-resource-ttl header to avoid the DELETE:

1 POST + 1 GET + 1 page-instance = 3 hits

Additionally, resource-level operations (e.g. applying a smart OCR template to OCR results) count for one hit each, and page-level operations (e.g. applying a barcode-recognition pass on the document) count for one hit per page processed.

Q: Why not measure usage by the document instead of hits? It seems more complicated than it should be.


While that would be simpler, it would be unfair to many customers. Documents can range from a single page to dozens or even hundreds of pages, and charging per document would either result in overcharging of customers who tend to process one-page or two-page documents, or forcing us to impose document page limits, which would limit flexibility and choice for customers.

In essence, we think the hits model is fairest to everybody, and ensures everyone is paying a fair price for the resources they consume.

Q: What languages does OCRestful support?


At this time we support English, French, German, Italian, Russian, and Spanish. We have plans in our roadmap to support additional languages, but each language calls for its own development and testing cycle, so we will likely be rolling them out individually.

Q: I meant what programming languages does OCRestful support?


Oh. Being a cloud product with an all-REST API, we are compaitible with virtually any language you can think of—at least any that can communicate via HTTP/HTTPS. We've seen client implementations in Javascript (Node.js), Ruby/RoR, Java, .NET, PHP, Python, and Perl. But we'd take the bet that a client could be developed in FORTRAN, COBOL, or Assembly. So your programming language ought to be covered.

Q: My OCR results include garbage characters—What's up?


The most likely reason for this is a low-resolution document. We recommend that you use images that are scanned at 300 DPI. Low-resolution scans are the primary cause of bad OCR results. Other reasons might include low contrast between the text and the background, document noise (e.g. lots of speckling), and excessive skewing (although our engine does attempt to auto-correct skewed images).

Q: Does OCRestful auto-rotate my document?


Yes, OCRestful applies auto-rotate and auto-deskew to images before running its OCR passes. This works well on images containing text that is all in the same orientation. Images where text runs left-to-right as well as other directions (e.g. vertically, at angles greater than 30%) tend to not work as well. If you're processing such images, you may need to break them up into smaller images with text of a single orientation before attempting to process them with OCRestful.