API Documentations - VINbarcode API

API Documentation

VINbarcode API 2.0 (Coding Examples)

Our VINbarcode API only works with Code 39. Generally speaking, unlike a VIN captured by our VINocr API, a VIN captured through VINbarcode API requires no sanity check.

To achieve the highest possible recognition speed, the image size is a key factor.

Avoid Submitting The Same Image More Than Once

Our system deducts one credit from your account balance for each XML or JSON result returned, regardless of the outcome. Therefore, please ensure your system has a mechanism in place to prevent sending the same image to the API service more than once.

REST API Description

This API uses multipart POST HTTP method. Ensure your POST is a multipart/form-data request. The following three parameters and their values are required.

Parameter Name	Parameter	Value	Used in URL
API Key	accesscode	xxxxx-xxxxx-xxxxx-xxxxx	POST https://www.recognition.ws/vinbarcode/v2?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&saveimage=TRUE
Input Image*	Image File*	JPG, JPEG, PNG, GIF, BMP	POST https://www.recognition.ws/vinbarcode/v2?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&saveimage=TRUE
Save Image**	saveimage**	TRUE or FALSE (default: FALSE)	POST https://www.recognition.ws/vinbarcode/v2?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&saveimage=TRUE
VIN Decode***	vindecode***	TRUE or FALSE (default: FALSE)	POST https://www.recognition.ws/vinbarcode/v2?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&saveimage=TRUE&vindecode=TRUE
Data Format****	format****	XML or JSON (default: XML)	POST https://www.recognition.ws/vinbarcode/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 barcode will be processed if an input image contains more than one barcode.

** Set parameter "saveimage" to "TRUE" if you'd like our system 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/vinbarcode/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>

Output in XML or Json

VIN: VIN number in ASCII
Position of the barcdoe 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.

VINbarcode without VINdecode output: POST https://www.recognition.ws/vinbarcode/v2?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx

                
    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <VINbarcode Version="1.0.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>
    </VINbarcode>

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

                
    {
      "service": "vinbarcode",
      "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
    }

VINbarcode with VINdecode output: POST https://www.recognition.ws/vinbarcode/v2?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&vindecode=TRUE

                
    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <VINbarcode Version="2.0.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>
    </VINbarcode>

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

            
    {
      "service": "vinbarcode",
      "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 barcode 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"?>
    <VINbarcode version="2.0" Date="5/28/2015 1:39:10 PM" Status="FAILED">
      <Message Key="0" Value="Database Errors." />
    </VINbarcode>

                

    // Json

    {
      "service": "vinbarcode",
      "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	Invalid VIN number: 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"?>
    <VINbarcode 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>
    </VINbarcode>

                

    // Json

    {
      "service": "vinbarcode",
      "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 barcode:<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/vinbarcode/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/vinbarcode/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/vinbarcode/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/vinbarcode/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/vinbarcode/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/vinbarcode/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/vinbarcode/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/vinbarcode/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/vinbarcode/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/vinbarcode/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()