Log inGet started

Getting Started

Suggest Edits

This guide will help you get the most out of the Mindee Node.js OCR SDK to easily extract data from your documents.

📘

Info

The library is written in TypeScript for your coding pleasure and is officially supported on all current LTS versions of node.js.
All examples shown in this guide should work in both TypeScript and Javascript.

Installation

Prerequisites

You'll need npm and Node.js.

Note: When installing a Node.js instance, nvm will also install a compatible npm version.

Standard Installation

The easiest way to install the Mindee OCR SDK for your project is by using npm:

npm install mindee

Development Installation

If you'll be modifying the source code, you'll need to follow these steps to get started.

  1. First clone the repo.
git clone [email protected]:mindee/mindee-api-nodejs.git
  1. Navigate to the cloned directory and install all required libraries.
cd mindee-api-node.js
npm install

Updating the Library

It is important to always check the version of the Mindee OCR SDK you are using, as new and updated features won’t work on older versions.

To get the latest version of your OCR SDK:

npm update mindee

To install a specific version of Mindee:

npm install [email protected]<version>

Usage

Using Mindee's APIs can be broken down into the following steps:

  1. Import the required classes in your program
  2. Initialize a Client
  3. Load a file
  4. Send the file to Mindee's API
  5. Retrieve the response
  6. Process the response in some way

Let's take a deep dive into how this works.

Importing Requirements

In most cases, you'll just need to require the mindee module:

const mindee = require("mindee");

If you're building your own module, or using TypeScript, the equivalent would be:

import * as mindee from "mindee";

Initializing the Client

The Client centralizes document configurations in a single object.

The Client requires your API key.

You can either pass these directly to the constructor or through environment variables.

Pass the API key directly

// Init a new client and passing the key directly
const mindeeClient = new mindee.Client({apiKey: "my-api-key"});

Set the API key in the environment

API keys should be set as environment variables, especially for any production deployment.

The following environment variable will set the global API key:

MINDEE_API_KEY="my-api-key"

Then in your code:

// Init a new client without an API key
const mindeeClient = new Client();

Loading a Document File

Before being able to send a document to the API, it must first be loaded.

You don't need to worry about different MIME types, the library will take care of handling
all supported types automatically.

Once a document is loaded, interacting with it is done in exactly the same way, regardless
of how it was loaded.

There are a few different ways of loading a document file, depending on your use case:

Path

Load from a file directly from disk. Requires an absolute path, as a string.

const doc = mindeeClient.docFromPath("/path/to/the/document.pdf");

Stream Object

Load a standard readable stream object, for example as returned by the fs.createReadStream() function.

Note: The original filename is required when calling the method.

const stream = fs.createReadStream("/path/to/the/document.jpg");
const doc = mindeeClient.docFromStream(stream, "document.jpg");

Base64

Load file contents from a base64-encoded string.

Note: The original filename is required when calling the method.

const b64String = "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLD...."
const doc = mindeeClient.docFromBase64(b64String, "document.jpg");

URL

Specify a URL to send to the Mindee API.

Note: The URL will not be downloaded locally, so checks (i.e. MIMEtype) and transformations (i.e. remove pages from a PDF) will not be possible.

const doc = mindeeClient.docFromUrl("https://example.com/image.jpg");

Sending a Document

To send a file to the API, we need to specify how to process the document.
This will determine which API endpoint is used and how the API return will be handled internally by the library.

More specifically, we need to set a Document class as the first parameter of the parse method.

This is because the parse method is generic, and its return type depends on its first argument.

Each document type available in the library has its corresponding class, which inherit from the base Document class.
This is detailed in each document-specific guide.

Off-the-Shelf Documents

Simply setting the correct class is enough:

const respPromise = doc.parse(mindee.InvoiceV4);

Custom Documents

The endpoint to use must also be set, this is done in the second argument of the parse method:

const respPromise = doc.parse(mindee.CustomV1, { endpointName: "wsnine" });

This is because the CustomV1 class is enough to handle the return processing, but the actual endpoint needs to be specified.

Retrieving the Response

The return of the parse method is a Promise that resolves to a Response object.

More technically, the return object is instantiated depending on the specific Document class passed as the first argument to parse.

Handling the return is done like any other Promise:

respPromise.then((resp) => {
  console.log(resp.document);
});

Some other styles:

// One-liner
doc.parse(mindee.InvoiceV4).then((resp) => {
  console.log(resp.document);
});

// Async function
async function parseInvoice() {
  const doc = mindeeClient.docFromPath("/path/to/the/invoice.pdf");
  const response = await doc.parse(mindee.InvoiceV4);
}

Processing the Response

The Response objects all have the following attributes:

Document Level Prediction

The document attribute is an object specific to the type of document being processed.
Technically, it's an instance of a class that extends the base Document class.

It contains the data extracted from the entire document, all pages combined.
It's possible to have the same field in various pages, but at the document level only the highest confidence field data will be shown (this is all done automatically at the API level).

// print the complete object
console.log(resp.document);

// print a summary of the document-level info
 console.log(resp.document.toString());
// or
console.log(`${resp.document}`);

Each class will have its own specific attributes, which correspond to the various fields extracted from the document.

The various attributes are detailed in these document-specific guides:

Page Level Prediction

The pages attribute is an array, each element is an object of the same class as the document attribute.

Each page element contains the data extracted for a particular page of the document.
The order of the elements in the array matches the order of the pages in the document.

All response objects have this property, regardless of the number of pages.
Single page documents will have a single entry.

Iteration is done like any JavaScript array, for example:

resp.pages.forEach((page) => {

  // as object, complete
  console.log(page);

  // as string, summary
  console.log(`${page}`);
});

Raw HTTP Response

The httpResponse attribute contains the full Mindee API HTTP response object in JSON format.
It can be useful for debugging.

console.log(resp.httpResponse);

 

Questions?
Slack Logo Icon  Join our Slack

Updated 3 months ago

What’s Next