OCR API Reference

Welcome to the Plate Recognizer OCR API! Our API allows you to seamlessly extract text identifiers from images with high accuracy and efficiency. It supports multiple recognition types, including VIN and trailer identification numbers.

Important: Processing Time

The OCR API uses advanced AI models for text extraction. Processing times are typically 20–30 seconds per image. Please account for this when designing your integration, especially for real-time or high-throughput use cases.

For comprehensive guidelines on utilizing OCR Cloud, please refer to our detailed documentation here.

We offer support for multiple programming languages. Scroll down to explore code examples in various languages for easy integration.

OCR Cloud API

Authentication

OCR Cloud is only available to registered users. Sign up for a Free Trial and get an API Token. It has to be included in all API calls. The HTTP headers must contain:

Authorization: Token YOUR_API_TOKEN

danger

For the commands below, make sure to replace YOUR_API_TOKEN with your API Token. For example, Authorization: Token abcdef123456xxxxxxxxxxxxxxxxxxxxxxxxxxxx.

Get your token from, here.

Extract Text from an Image

HTTP Request

POST https://api.platerecognizer.com/v1/ocr/reader/

The CORS policy of this endpoint allows requests from all origins.

POST Parameters

Parameter	Required	Description
upload	Yes	The file to be uploaded. The parameter can either be the file bytes (using Content-Type multipart/form-data) OR a base64 encoded image. This parameter becomes optional if upload_url parameter is present.
upload_url	No	The url of file to be uploaded. This parameter is to be used as an alternative to upload parameter.
type	Yes	The type of text to extract. Supported values: vin (Vehicle Identification Number), trailer_id (Trailer Identification Number).
camera_id	No	Unique camera identifier.
timestamp	No	ISO 8601 timestamp. For example, 2019-08-19T13:11:25. The timestamp has to be in UTC.

Shell

#On Linux
curl -F "upload=@/your-image.jpg" \
  -F "type=trailer_id" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  https://api.platerecognizer.com/v1/ocr/reader/

#Calling the API with an image URL.
curl -X POST -F upload_url="https://www.demo.com/static/your-image.jpg" -F "type=vin" -H "Authorization: Token YOUR_API_TOKEN" https://api.platerecognizer.com/v1/ocr/reader/

#On Windows
curl -F "[email protected]" ^
  -F "type=trailer_id" ^
  -H "Authorization: Token YOUR_API_TOKEN" ^
  https://api.platerecognizer.com/v1/ocr/reader/

Ruby

#gem install multipart-post
require 'net/http/post/multipart'

url = URI.parse('https://api.platerecognizer.com/v1/ocr/reader/')
path = '/path/to/your-image.jpg'
File.open(path) do |jpg|
  req = Net::HTTP::Post::Multipart.new url.path,
    "upload" => UploadIO.new(jpg, "image/jpeg", path),
    "type" => "trailer_id"
  req['Authorization'] = 'Token YOUR_API_TOKEN'
  res = Net::HTTP.start(url.host, url.port, use_ssl: true) do |http|
    http.request(req)
  end
end

Python

import requests
from pprint import pprint
with open('/path/to/your-image.jpg', 'rb') as fp:
    response = requests.post(
        'https://api.platerecognizer.com/v1/ocr/reader/',
        data=dict(type='trailer_id'),
        files=dict(upload=fp),
        headers={'Authorization': 'Token YOUR_API_TOKEN'})

    #For files field, if needed, use imencode method of cv2 library to encode an image and producing a compressed representation that can be easier stored, transmitted, or processed.
    #import cv2
    #success, image_jpg = cv2.imencode('.jpg', fp)
    #files=dict(upload=image_jpg.tostring())

pprint(response.json())

# With OpenCV
import cv2
success, image_jpg = cv2.imencode('.jpg', image)
files={'upload':image_jpg.tostring()}
response = requests.post(
            'https://api.platerecognizer.com/v1/ocr/reader/',
            data=dict(type='vin'),
            headers={'Authorization': 'Token YOUR_API_TOKEN'})

JavaScript

// Using Node-RED?
// Check https://github.com/parkpow/node-red-contrib-plate-recognizer

const fetch = require("node-fetch");
const FormData = require("form-data");
const fs = require("fs");

let image_path = "/path/to/your-image.jpg";
let body = new FormData();
body.append("upload", fs.createReadStream(image_path));
body.append("type", "trailer_id");
// Or body.append('upload', base64Image);
fetch("https://api.platerecognizer.com/v1/ocr/reader/", {
  method: "POST",
  headers: {
    Authorization: "Token YOUR_API_TOKEN",
  },
  body: body,
})
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch((err) => {
    console.log(err);
  });

Response

{
  "processing_time": 128.758,
  "results": [
    {
      "identifier": {
        "type": "text",
        "props": {
          "code": [
            {
              "value": "12345"
            }
          ],
          "orientation": [
            {
              "value": "horizontal"
            }
          ],
          "confidence": 0.8
        }
      }
    }
  ],
  "filename": "image.jpg",
  "version": 1,
  "camera_id": null,
  "timestamp": "2025-03-22T13:26:01.683008Z"
}

Attribute	Description
results/identifier/code	The extracted text identifier
results/identifier/orientation	The orientation of the identifier text. One of vertical, horizontal.
results/identifier/confidence	The confidence level of the detection (0 to 1)

Statistics

Get number of recognition calls done during the current month.

HTTP Request

GET https://api.platerecognizer.com/v1/ocr/statistics/

curl -H "Authorization: Token YOUR_API_TOKEN" \
  https://api.platerecognizer.com/v1/ocr/statistics/

JSON Response

{
  "usage": {
    "month": 3,
    "calls": 55,
    "year": 2025,
    "resets_on": "2025-03-20T00:00:00Z"
  },
  "total_calls": 5000
}

Response fields description:

Attribute	Description
calls	Number of API calls made during the current period.
month	Month of the current period.
year	Year of the current period.
resets_on	Date when the counter will reset.
total_calls	Maximum number of API calls you can make during the period. Need more? Upgrade.

Webhooks

OCR supports webhooks, allowing you to receive an HTTP POST request to a target URL of your choosing whenever an image is processed.

To manage your webhooks or add a new webhook target, head to the OCR webhooks page, where you'll find the webhook configuration options.

note

• The Target URL should return a valid HTTP status code 200. If the Target URL consistently returns an error code, the webhook will be deactivated and an email will be sent to the account owner.
• To quickly test out this feature, you can use webhook.site. It generates a unique target URL and displays all the requests made to that URL.

Payload

The payload is a JSON object sent to the target URL containing the OCR results. Here is an example:

{
  "hook": {
    "target": "https://your-webhook-url.com/endpoint",
    "id": 123
  },
  "data": {
    "processing_time": 128.758,
    "results": [
      {
        "identifier": {
          "type": "text",
          "props": {
            "code": [
              {
                "value": "12345"
              }
            ],
            "orientation": [
              {
                "value": "horizontal"
              }
            ],
            "confidence": 0.8
          }
        }
      }
    ],
    "filename": "image.jpg",
    "version": 1,
    "camera_id": null,
    "timestamp": "2025-03-22T13:26:01.683008Z",
    "file_url": "https://example.com/path-to-uploaded-image.jpg"
  }
}

The payload contains the following fields:

• hook: Information about the webhook.
  • target: The target URL the webhook was sent to.
  • id: The unique identifier of the webhook.
• data: The OCR processing results (same format as the API response).
  • file_url: URL of the uploaded image.

Errors

Error Code	Meaning
400	Bad Request: Missing required parameters (e.g., type) or invalid image format
401	Unauthorized: Invalid or missing API token
403	Forbidden: OCR is not enabled for your account or API call limit reached
429	Too Many Requests: Rate limit exceeded
503	Service Unavailable: Prediction service error