OpenALPR JavaScript SDK Documentation

openalpr is a JS way to recognize license plates and vehicles using OpenALPR API.

You can add openalpr to your Node.js (including Express) and web (including React) projects.

Get started

This quick start is intended for intermediate to advanced developers.

1. Install the openalpr dependency

npm install openalpr

The above command installs openalpr locally on your project.

Explore our Node.js example

cd example
npm start

You will find some outputs on Terminal.

2. Import or require openalpr

// ES6 import
import openALPR from 'openalpr'

// RequireJS import
const openALPR = require('openalpr')

3. Create a configuration

We recommend that you create a separate file for the openalpr config. The config must be an object with the secretKey property, like this:

Basics

/**
 * @type {{secretKey: string}}
 */
const config = {
    secretKey: 'sk_123a4bc56d78e901fa2b3c45' // This is a non-functional key just for this example.
}

// ES6 export
export default config

// RequireJS export
module.exports = config

Replace secretKey by your CarCheck API Credential (get yours on https://cloud.openalpr.com/cloudapi/).

Make config file more secure

The example above showed just how the configuration should be created.

However, ideally, keys should not be stored in repository files.

Therefore, we recommend that you use the environment variables for this.

/**
 * @type {{secretKey: string}}
 */
const config = {
    secretKey: process.env.OPENALPR_SECRET_KEY
}

// ES6 export
export default config

// RequireJS export
module.exports = config

Trouble with getting env variables?

On development environments or some projects, maybe you'll need to install dotenv dependency to get env values. We recommend version 8.2.0 or higher.

npm install --save --save-exact dotenv

And then, create (or update) your .env or .env.development file with this:

OPENALPR_SECRET_KEY=sk_123a4bc56d78e901fa2b3c45

4. Create an instance

After importing (or requiring) openalpr, you can create an instance with the config we created before.

ES6 way

import config from './config'
import openALPR from 'openalpr'

const instance = openALPR.create(config)

RequireJS way

const config = require('./config')
const openALPR = require('openalpr')

const instance = openALPR.create(config)

5. Use recognition service

With blob images from browser Files API

Currently, we support direct recognition only of base64 image files. If you are working with file inputs on HTML forms, you can use toBase64() and encode these images before.

Promise.then

// ES6 way
import toBase64 from 'openalpr/dist/toBase64'

// RequireJS way
const toBase64 = require('openalpr/dist/toBase64')

function foo() {

    const handleResult = result => {
        // @todo recognize result
    }
    const handleError = error => {
        console.error(error)
    }
    
    toBase64(file).then(handleResult).catch(handleError)

}

With try/catch

// ES6 way
import toBase64 from 'openalpr/dist/toBase64'

// RequireJS way
const toBase64 = require('openalpr/dist/toBase64')

async function foo() {

    let result;

    try {
       const result = await toBase64(file);
        // @todo recognize result
    }
    catch (error) {
       console.error(error)
    }

}

With base64 strings

Let's suppose that we have some JPEG data encoded with base64:

const imageData = 'data:image/jpeg;base64,ABCDEFGIHJKLMNOPQRSTUVWXY/Z'

You can call recognize method from openalpr, which returns a Promise:

instance.recognize(data)
  .then(r => console.log('Response', r))
  .catch(e => console.error('Error', e))
})

Successful response

If image base64 data is valid, and your secret key too, you will find a JSON with recognition results, like this:

Response {
  uuid: '',
  data_type: 'alpr_results',
  epoch_time: 1584024229747,
  processing_time: {
    total: 785.0690000004761,
    plates: 63.24161911010742,
    vehicles: 71.50000000001455
  },
  img_height: 683,
  img_width: 1024,
  results: [
    {
      plate: 'ABC1234',
      confidence: 85.76541900634766,
      region_confidence: 0,
      vehicle_region: [Object],
      region: '',
      plate_index: 0,
      processing_time_ms: 19.37890625,
      candidates: [Array],
      coordinates: [Array],
      vehicle: [Object],
      matches_template: 1,
      requested_topn: 10
    }
  ],
  credits_monthly_used: 1,
  version: 2,
  credits_monthly_total: 2000,
  error: false,
  regions_of_interest: [ { y: 0, x: 0, height: 683, width: 1024 } ],
  credit_cost: 1
}

Error responses

Otherwise, you can find errors like Image data is empty or null. Please check recognize() function call.

Or even:

{
  data: {
    error_code: 400,
    error: 'Unable to base64 decode image_bytes body'
  },
  status: 400,
  headers: {
    // ...
  }
}

In this case, check your secret key and base64 image content.

Start contributing

Visit our code of conduct.