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.

Do Not Send The Same Image More Than Once

Our system will take one credit off from your account balance when result in XML or Json format is returned regardless of what the result turns out to be. So please be sure to have a mechanism in place in your system to prevent the same image from being sent 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)


    <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")


    // 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;
    }

    // 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)


    ### 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)

    ### 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)


    // 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);
    }

    // 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#)


    // 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();
        }
    }

    // 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();
        }
    }