API Documentations - VINocr API

REST API Description

This API uses multipart POST HTTP method. Ensure your POST is a multipart/form-data request. Five parameters and their values are available as follows.

Parameter Name	Parameter	Value	Used in URL
API Key	accesscode	xxxxx-xxxxx-xxxxx-xxxxx	POST https://www.recognition.ws/vinocr/v2?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&saveimage=TRUE
Input Image*	Image File*	JPG, JPEG, PNG, GIF, BMP	POST https://www.recognition.ws/vinocr/v2?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&saveimage=TRUE
Save Image**	saveimage**	TRUE or FALSE (default: FALSE)	POST https://www.recognition.ws/vinocr/v2?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&saveimage=TRUE
VIN Decode***	vindecode***	TRUE or FALSE (default: FALSE)	POST https://www.recognition.ws/vinocr/v2?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&saveimage=TRUE&vindecode=TRUE
Data Format****	format****	XML or JSON (default: XML)	POST https://www.recognition.ws/vinocr/v2?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&saveimage=TRUE&vindecode=TRUE&format=JSON

* Only one image file is allowed in a POST request. A POST request with multiple files would be rejected immediately. Only the first found VIN will be processed if an input image contains more than one VIN.

** Set parameter "saveimage" to "TRUE" if you'd like the service to save the input image so that later you can log in to your account to review it. Set the value of this parameter to "FALSE" otherwise.

*** Set parameter "vindecode" to "TRUE" if you'd like the service to retrieve make/model/year for the captured VIN code. Set the value of this parameter to "FALSE" otherwise.

**** Set parameter "format" to "JSON" if you'd like the service to send data in Json format. If you don't include this parameter at all in the API URL, or explicitly set the value of this parameter to "XML" to get data in XML format.

                    
    <html>
       <form enctype="multipart/form-data" action="https://www.recognition.ws/vinocr/v2?accesscode=xxxxx-xxxxx-xxxxx-xxxxxx&saveimage=FALSE&vindecode=FALSE"
       method="POST">
          Choose an image to process: <input name="anyName" type="file" />
          <input type="submit" value="Go" />
       </form>
    </html>

Input Image Specs

VIN characters have to meet the specification of at least 25 pixels high characters. In general, OCR can decode characters lower than this requirement but not at the extremely high(99.8%) accuracies required.

Input Image Specs
Height of the VIN portion in an input image	20 - 150 pixels
Width of the VIN portion in an input image	80 - 400 pixels
Length of a VIN	17 characters
Size of Input Image	< 2.0 MB

Output in XML or Json

VIN: VIN number in ASCII
Position of the VIN portion in an input image: Top(pixels), Left(pixels), Width(pixels), Height(pixels). The origin(0,0) is the top-left corner of an input image.

VINocr without VINdecode output in XML format: POST https://www.recognition.ws/vinocr/v2?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx

                
    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <VINocr Version="2.0." Date="12/14/2015 3:23:58 PM" Status="SUCCESS">
      <VIN_Captured>XXXXXXXXXXXXXXXXX</VIN_Captured>
      <Left>299</Left>
      <Top>429</Top>
      <Width>450</Width>
      <Height>42</Height>
    </VINocr>

VINocr without VINdecode output in Json format: POST https://www.recognition.ws/vinocr/v2?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&format=JSON

                
    {
      "service": "vinocr",
      "version": "2.0",
      "date": "3/7/2021 3:53:26 PM",
      "status": "SUCCESS",
      "vin_captured": "XXXXXXXXXXXXXXXXX",
      "left": 299.0,
      "top": 429.0,
      "width": 450.0,
      "height": 42.0
    }

VINocr with VINdecode output in XML format: POST https://www.recognition.ws/vinocr/v2?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&vindecode=TRUE

                
    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <VINocr Version="2.0" Date="8/14/2020 10:13:32 AM" Status="SUCCESS">
      <VIN_Captured>XXXXXXXXXXXXXXXXX</VIN_Captured>
         <VINdecode Status="SUCCESS">
             <Make>Audi</Make>
             <Model>A4</Model>
             <Year>2010</Year>
         </VINdecode>
      <Left>299</Left>
      <Top>429</Top>
      <Width>450</Width>
      <Height>42</Height>
    </VINocr>

VINocr with VINdecode output in Json format: POST https://www.recognition.ws/vinocr/v2?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&vindecode=TRUE&format=JSON

                
    {
      "service": "vinocr",
      "version": "2.0",
      "date": "3/7/2021 3:53:26 PM",
      "status": "SUCCESS",
      "vin_captured": "XXXXXXXXXXXXXXXXX",
      "vindecode": {
        "status": "SUCCESS",
        "make": "Audi",
        "model": "A4",
        "year": 2010
      },
      "left": 299.0,
      "top": 429.0,
      "width": 450.0,
      "height": 42.0
    }

Error Codes

Following errors can occur when the system attempts to locate & read a VIN code in a given image:

Error Code (Key)	Description (Value)
0	Database Errors.
23	Insufficient balance for Recognition.
25	No image has been uploaded.
26	Recognition failed.
27	Unknown error(s) occured.
29	One or more required parameters missing.

                    
    // XML

    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <VINocr version="2.0" Date="5/28/2015 1:39:10 PM" Status="FAILED">
      <Message Key="0" Value="Database Errors." />
    </VINocr>

                    

    // Json
    {
      "service": "vinocr",
      "version": "2.0",
      "date": "03/08/21 3:23:27 PM",
      "status": "FAILED",
      "message_key": 0,
      "message": "Database Errors." 
    }

Following errors can occur when the system attempts to decode the captured VIN:

Error Code (Key)	Description (Value)
0	Database Errors.
2	Valid VIN number. However, no data available for it at this moment.
3	Invalid VIN number: This VIN number did not pass checksum test
4	A valid VIN number must be exactly 17 digits.
5	Invalid VIN number: This VIN number contains invalid letters: I, O or Q.
7	Invalid VIN number: The last 4 digits of a VIN number must be numeric..
14	Invalid VIN number: The 10th digit of a VIN number cannot be letter U, letter Z or number 0.
16	A VIN can only contain alphanumeric characters.

                    
    // XML

    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <VINocr version="2.0" Date="9/24/2020 1:43:16 AM" Status="SUCCESS">
      <VIN_Captured>1FTRF02W24KXXXXXX</VIN_Captured>
        <VINdecode>
            <Message Key="3" Value="Invalid VIN number: This VIN number did not pass checksum test." />
        </VINdecode>
        <Left>40</Left>
        <Top>60</Top>
        <Width>195</Width>
        <Height>45</Height>
    </VINocr>

                    
    // Json

    {
      "service": "vinocr",
      "version": "2.0",
      "date": "03/08/21 3:23:27 PM",
      "status": "SUCCESS",
      "vin_captured": "1FTRF02W24KXXXXXX<",
      "vindecode": {
        "status": "FAILED",
        "message_key": 3,
        "message": "Invalid VIN number: This VIN number did not pass checksum test."
      },
      "left": 40.0,
      "top": 60.0,
      "width": 195.0,
      "height": 45.0
    }

Coding Examples (XML and Json)

JavaScript(Python, C#, Java, Swift)



    <html>
    <head></head>
    <body>
    <form id = "form">
        <label>Please submit an image containing a VIN code:<input type = "file" id = "input"></label>
        <br>
        <a href="javascript: fetchResponseXml()"> Submit (XML Output) </a>
        <br>
        <a href="javascript: fetchResponseJson()"> Submit (Json Output) </a>
    </form>

    <pre id = "p1"></pre>
    </body>

    <script>

    const form = document.getElementById("form")
    const out = document.getElementById("p1")


    // JavaScript XML

    async function fetchResponseXml() {
        console.log("XML")
        const url = "https://www.recognition.ws/vinocr/v2?accesscode=YOUR_ACCESS_CODE&vindecode=TRUE"
        var imgInput = document.getElementById("input")
        var img = imgInput.files[0]
        var formData = new FormData();
        formData.append('file', img)

        var parser = new DOMParser();
        var xmlHttp = new XMLHttpRequest();
        xmlHttp.open("POST", url, false);
        xmlHttp.send(formData);
        var xmlResponse = parser.parseFromString(xmlHttp.responseText, "text/xml");
        var text = "";
        var children = xmlResponse.documentElement.children;
        for (var i = 0; i < children.length; i++) {
            text += children[i].nodeName + ": " + children[i].textContent + "\n"
        }

        out.textContent = text;
    }

    // JavaScript Json

    async function fetchResponseJson() {
        console.log("JSON")
        const url = "https://www.recognition.ws/vinocr/v2?accesscode=YOUR_ACCESS_CODE&vindecode=TRUE&format=JSON"

        var imgInput = document.getElementById("input")
        var img = imgInput.files[0]
        var formData = new FormData();
        formData.append('file', img)

        var xHttp = new XMLHttpRequest();
        xHttp.open("POST", url, false);
        xHttp.send(formData);
        var jsonResponse = JSON.parse(xHttp.responseText)
        var text = "";

        for (let childProperty in jsonResponse) {
            let childValue = jsonResponse[childProperty];

            if (typeof childValue === 'object') {
                text += childProperty + ": \n" 
                for (let nestedChildProperty in childValue) {
                    let nestedChildValue = childValue[nestedChildProperty]
                    text += "\t" + nestedChildProperty + ": " + nestedChildValue + "\n";
                }
            } else {
                text += childProperty + ": " + childValue + "\n";
            }
        }

        out.textContent = text;
    }

    </script>
    </html>

Python(JavaScript, C#, Java, Swift)



    ### Python XML

    import xml.etree.ElementTree as ET
    import requests

    url = "https://www.recognition.ws/vinocr/v2?accesscode=YOUR_ACCESS_CODE&vindecode=TRUE"
    path = "YOUR_IMAGE_PATH"

    with open(path, 'rb') as img:
        imgName = os.path.basename(path)
        images = {'image': (imgName, img)}
        with requests.Session() as s:
            r = s.post(url, files = images)
            xml = ET.fromstring(r.text)
            output = "VIN Captured: " + xml[0].text
            print(output)

    ### Python Json

    import requests
    import json
    import os

    url = "https://www.recognition.ws/vinocr/v2?accesscode=YOUR_ACCESS_CODE&vindecode=TRUE&format=JSON"
    path = "YOUR_IMAGE_PATH"

    with open(path, 'rb') as img:
        imgName = os.path.basename(path)
        images = {'image': (imgName, img)}
        with requests.Session() as s:
            r = s.post(url, files = images)
            result = r.json()
            for attribute, value in result.items():
                print(attribute, ":", value)

C#(JavaScript, Python, Java, Swift)



    // C# XML

    using System;
    using System.IO;
    using System.Net;
    using System.Xml.Linq;


    static void Main(string[] args)
    {
        String url = "https://www.recognition.ws/vinocr/v2?accesscode=YOUR_ACCESS_CODE&vindecode=TRUE";
        String imagePath = "YOUR_IMAGE_PATH";
        WebClient client = new WebClient();
        byte[] response = client.UploadFile(url, imagePath);
        String responseString = client.Encoding.GetString(response);
        XElement root = XElement.Parse(responseString);

        // Iterating for "VIN_Captured" item in the root tag.
        var el = root.Elements("VIN_Captured");
        Console.WriteLine("VIN Captured: " + (string) el.Value);

        IEnumerable<XElement> test =
             from el in root.Elements("VIN_Captured")
             where (string) el.Value != null
             select el;
         foreach (XElement el in test)
             Console.WriteLine("VIN captured: " + (string)el.Value);
    }

    // C# Json

    using System;
    using System.IO;
    using System.Net;
    using System.Net.Http;
    using System.Xml;
    using Newtonsoft.Json.Linq;

    static void Main(string[] args)
    {
        String url = "https://www.recognition.ws/vinocr/v2?accesscode=YOUR_ACCESS_CODE&vindecode=TRUE&format=JSON";
        String imagePath = "YOUR_IMAGE_PATH";
        WebClient client = new WebClient();
        byte[] response = client.UploadFile(url, imagePath);
        String responseString = client.Encoding.UTF8.GetString(response);

        Console.WriteLine("\nJSON Output (Parsed): \n");

        JObject jsonResponse = JObject.Parse(responseString);

        foreach (var node in jsonResponse)
        {
            Console.WriteLine(node.Key + ": " + node.Value);
        }
    }

Java(JavaScript, Python, C#, Swift)



    // Java XML

    ...
    import java.net.HttpURLConnection;
    import java.net.URL;


    public static void main( String[] args )
    {
        URL url;
        String response = "";
        try {

            url = new URL("https://www.recognition.ws/vinocr/v2?accesscode=YOUR_ACCESS_CODE&vindecode=TRUE");

            final HttpURLConnection con = (HttpURLConnection) url.openConnection();

            final String imagePath = "YOUR_IMAGE_PATH";
            postImage(con, imagePath);

            BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream()));
            StringBuilder sb = new StringBuilder();
            while ((response = br.readLine()) != null) {
                sb.append(response);

            }

            response = sb.toString();
            System.out.println(response);

        con.disconnect();
        } catch (MalformedURLException e) {
            e.printStackTrace();
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    // Java Json

    ...
    import java.net.HttpURLConnection;
    import java.net.URL;


    public static void main( String[] args )
    {
        URL url;
        String response = "";
        try {

            url = new URL("https://www.recognition.ws/vinocr/v2?accesscode=YOUR_ACCESS_CODE&vindecode=TRUE&format=JSON");

            final HttpURLConnection con = (HttpURLConnection) url.openConnection();

            final String imagePath = "YOUR_IMAGE_PATH";
            postImage(con, imagePath);

            BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream()));
            StringBuilder sb = new StringBuilder();
            while ((response = br.readLine()) != null) {
                sb.append(response);

            }

            response = sb.toString();
            System.out.println(response);

        con.disconnect();
        } catch (MalformedURLException e) {
            e.printStackTrace();
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    /////////////////////////////////////////////////////////////////
    /// function postImage(HttpURLConnection con, String filePath) //
    ////////////////////////////////////////////////////////////////

    public static void postImage(HttpURLConnection con, String filePath) {
        String charSet = "UTF-8";
        File binaryFile = new File(filePath);
        String boundary = "--";
        String CRLF = "\r\n";
        try {
            con.setDoInput(true);
            con.setDoOutput(true);
            con.setRequestMethod("POST");
            con.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);

            OutputStream output = con.getOutputStream();
            PrintWriter pw = new PrintWriter(new OutputStreamWriter(output, charSet));
            pw.append("--" + boundary).append(CRLF);
            pw.append("Content-Disposition: form-data; name \"file\"; filename=\"" + binaryFile.getName() + "\"").append(CRLF);
            pw.append("Content-Type: image/gif").append(CRLF);
            pw.append(CRLF).flush();

            Files.copy(binaryFile.toPath(), output);
            output.flush();

            pw.append(CRLF).append("--" + boundary + "--").flush();

            pw.close();
            output.close();

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

Swift(JavaScript, Python, C#, Java)



    // Swift XML

    import UIKit

    let url = URL(string: "https://www.recognition.ws/vinocr/v2?accesscode=YOUR_ACCESS_CODE&vindecode=TRUE")
    let boundary = UUID().uuidString
    let session = URLSession.shared
    var urlRequest = URLRequest(url: url!)
    urlRequest.httpMethod = "POST"
    urlRequest.setValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type")
    let fileName = "YOUR_IMAGE_FILE_NAME"  // optional
    var img = UIImage(named: fileName)!
    var data = Data()
    data.append("\r\n--\(boundary)\r\n".data(using: .utf8)!)
    data.append("Content-Disposition: form-data; filename=\"\(fileName)\"\r\n".data(using: .utf8)!)
    data.append("Content-Type: image/png\r\n\r\n".data(using: .utf8)!)
    data.append(img.pngData()!)
    data.append("\r\n--\(boundary)--\r\n".data(using: .utf8)!)
    session.uploadTask(with: urlRequest, from: data, completionHandler: {responseData, response, error in
        if (error != nil) {
            print("error occurred")
        }
        if let responseString = String(data: responseData!, encoding: .utf8) {
            print("uploaded: \(responseString)")
        } else {
            print("error occurred")
        }
    }).resume()



    // Swift Json

    import UIKit

    let url = URL(string: "https://www.recognition.ws/vinocr/v2?accesscode=YOUR_ACCESS_CODE&vindecode=TRUE&format=JSON")
    let boundary = UUID().uuidString
    let session = URLSession.shared
    var urlRequest = URLRequest(url: url!)
    urlRequest.httpMethod = "POST"
    urlRequest.setValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type")
    let fileName = "YOUR_IMAGE_FILE_NAME"  // optional
    var img = UIImage(named: fileName)!
    var data = Data()
    data.append("\r\n--\(boundary)\r\n".data(using: .utf8)!)
    data.append("Content-Disposition: form-data; filename=\"\(fileName)\"\r\n".data(using: .utf8)!)
    data.append("Content-Type: image/png\r\n\r\n".data(using: .utf8)!)
    data.append(img.pngData()!)
    data.append("\r\n--\(boundary)--\r\n".data(using: .utf8)!)
    session.uploadTask(with: urlRequest, from: data, completionHandler: {responseData, response, error in
        if (error != nil) {
            print("error occurred")
        }
        if let responseString = String(data: responseData!, encoding: .utf8) {
            print("uploaded: \(responseString)")
        } else {
            print("error occurred")
        }
    }).resume()