Overview

The Hydra API recognizes user-specified fields of text in documents. It accounts for skews, shifts, rotations, and changes in layout in each document. It works like this:

  1. A user uploads a sample document — an invoice, say — and draws bounding boxes around desired text.
  2. The user programmatically uploads all documents that need to be processed to the Hydra API.
  3. The Hydra API then recognizes and returns the desired text in each document, taking into account skews, shifts, rotations, changes in layout, and variable size tables.

Try it out

You can try out the API via a graphical web interface by signing up for an account and creating a new data source with the "store results in Siftrics" checkbox unchecked.

Without writing any code

You can use Hydra without writing any code. There is a command-line program which takes files in which to recognize text and writes the results to a specified file.

For developers

We provide official, single-function libraries for the Hydra API:

Users of other languages must make POST requests to the hydra endpoint.

The Endpoint

Make a POST request to https://siftrics.com/api/hydra/YOUR_DATA_SOURCE_ID/ with JSON that looks like this:

    {
      "files": [
        {
          "mimeType": "application/pdf",
          "base64File": fileContentsEncodedAsBase64String
        },
        ...
      ]
    }

The exact endpoint is provided on the webpage of the data source in question. You can copy-and-paste it from that page, if you so desire.

Additionally, an API key must be provided by setting the "Authorization" header to

    "Basic API_KEY_HERE"

Other valid mimeTypes are: "image/bmp", "image/gif", "image/png", "image/jpeg", and "image/jpg".

The Response

    {
      "Rows": [
        {
          "Error": "",
          "FileIndex": 0,
          "RecognizedText": {
            "My Field 1": "text from your document...",
            "My Field 2": "text from your document...",
            ...
          }
        },
        ...
      ]
    }

Each entry in "Rows" corresponds to one file and, in the most common case, one row in a database.

If "Error" is not an empty string, then there was an error processing that file.

"FileIndex" is the index of this file in the original request's "files" array. This value is always valid.

Returning Transformed / Pre-Processed Images

Hydra can transform input documents so they are cropped and aligned with the original image used to create the data source.

To transform and return images so they are aligned with the original image, set the "returnTransformedImages" top-level field to true:

    {
      "returnTransformedImages": true,
      "files": [
        {
          "mimeType": "application/pdf",
          "base64File": fileContentsEncodedAsBase64String
        },
        ...
      ]
    }

Returned images will be available in the "TransformedImages" field of each element of "Rows" in the response:

    {
      "Rows": [
        {
          "Error": "",
          "FileIndex": 0,
          "RecognizedText": {
            "My Field 1": "text from your document...",
            "My Field 2": "text from your document...",
            ...
          },
          "TransformedImages": [
            {
              "Base64Image": ...,
              "PageNumber": 1
            },
            ...
          ]
        },
        ...
      ]
    }

Exporting JPGs instead of PNGs

To export cropped images in JPG format instead of PNG format, set the "returnJpgs" top-level field to true. Additionally, quality can be specified by setting "jpgQuality" to a number between 1 and 100 inclusive:

    {
      "returnJpgs": true,
      "jpgQuality": 85,
      "files": [
        {
          "mimeType": "application/pdf",
          "base64File": fileContentsEncodedAsBase64String
        },
        ...
      ]
    }

When "jpgQuality" is set to 85, at the cost of a small reduction quality, JPG images returned by the Hydra API are typically 7-10x smaller than their PNG version.

Faster Results

The Hydra API works by making multiple "passes" over each uploaded document. With each pass, the accuracy of results tends to increase.

It is possible to process documents in half the usual time, by telling the Hydra API to do half the number of passes as it normally would over each document. This behavior can be enabled by setting the top-level boolean field "doFaster" to true in your POST request:

    {
      "doFaster": true,
      "files": [
        {
          "mimeType": "application/pdf",
          "base64File": fileContentsEncodedAsBase64String
        },
        ...
      ]
    }

Based on our own research, "doFaster" tends to provide accurate results on all documents, except those that are extremely rotated — "doFaster" results are often inaccurate with documents that are rotated more than 90 degrees in any direction. If all of your documents are rotated less than 90 degrees and you want to minimize the amount of time Hydra takes processing each document, it is recommended to enable the "doFaster" behavior.