API Documentation

 

VMMR API 2.0 (Coding Examples)


Similar to our LPR API, our VMMR API can be deployed in one of two basic approaches; one allows for the entire process to be performed at the location in real-time, the other transmits all the images from multiple locations to a central location and performs the VMMR process there via our VMMR API at some later point in time. When done on the spot, the image of a vehicle, date-time, location identification, and any other information that is required can be acquired and transmitted to remote computers for further processing if necessary, or stored at the same location for later retrieval.


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. 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://vmmr.recognition.ws/v1?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&saveimage=TRUE
Input Image* Image File* JPG, JPEG, PNG, GIF, BMP POST https://vmmr.recognition.ws/v1?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&saveimage=TRUE
Save Image** saveimage** TRUE or FALSE (default: FALSE) POST https://vmmr.recognition.ws/v1?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&saveimage=TRUE
Data Format*** format*** XML or JSON (default: XML) POST https://vmmr.recognition.ws/v1?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&saveimage=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 "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://vmmr.recognition.ws/v1?accesscode=xxxxx-xxxxx-xxxxx-xxxxxx&saveimage=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

  • Only one vehicle in any given image would be captured and processed.
  • Up to 3 most probable predictions would be provided.
  • Make: vehicle brand in ASCII, such as BMW, Chevrolet, Ford, GMC;
    Click here for a complete list of makes/brands covered
  • Model: vehicle model in ASCII, such as 3-Series, Corvette, Escape, Terrain;
    (A complete list of models covered is comming soon...)
  • Generation: the lifecycle of a design for that specific Make and Model, for instance, 2016-2020;
  • Body_Style: the shape of the vehicle in ASCII, namely Convertible, Coupe, Hatchback, Sedan, SUV, Pickup, Minivan, Van, Wagon;
  • Doors: the number of doors in ASCII, namely 2D,3D,4D,5D;
  • Position of a vehicle 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.
VMMR API output in XML format: POST https://vmmr.recognition.ws/v1?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx
        

    // XML

    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <VMMR Version="1.0." Date="12/7/2021 3:53:26 PM" Status="SUCCESS">
      <Vehicle>VEHICLE-1</Vehicle> 
         <Make>MAKE</Make>
         <Model>MODLE</Model>
         <Generation>GENERATION</Generation>
         <Body_Style>BODY_STYLE</Body_Style>
         <Doors>DOORS</Doors>
         <Confidence>CONFIDENCE</Confidence>
      </Vehicle>
      <Vehicle>VEHICLE</Vehicle> 
         <Make>MAKE</Make>
         <Model>MODLE</Model>
         <Generation>GENERATION</Generation>
         <Body_Style>BODY_STYLE</Body_Style>
         <Doors>DOORS</Doors>
         <Confidence>CONFIDENCE</Confidence>
      </Vehicle>
      <Vehicle>VEHICLE</Vehicle> 
         <Make>MAKE</Make>
         <Model>MODLE</Model>
         <Generation>GENERATION</Generation>
         <Body_Style>BODY_STYLE</Body_Style>
         <Doors>DOORS</Doors>
         <Confidence>CONFIDENCE</Confidence>
      </Vehicle>
      <Left>LEFT</Left>
      <Top>TOP</Top>
      <Width>WIDTH</Width>
      <Height>HEIGHT</Height>
    </VMMR>
        
    
VMMR API output in Json format: POST https://vmmr.recognition.ws/v1?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&format=JSON
        

    //Json

    {
      "service": "vmmr",
      "version": "1.0",
      "date": "12/7/2021 3:53:26 PM",
      "status": "SUCCESS",
      "vehicle":[
         {
            "make": "MAKE",
            "model": "MODEL",
            "generation":"GENERATION",
            "body_style": "BODY_STYLE",
            "doors": "DOORS",
            "Confidence": CONFIDENCE,         
         },
         {
            "make": "MAKE",
            "model": "MODEL",
            "generation":"GENERATION",
            "body_style": "BODY_STYLE",
            "doors": "DOORS",
            "Confidence": CONFIDENCE,         
         },
         {
            "make": "MAKE",
            "model": "MODEL",
            "generation":"GENERATION",
            "body_style": "BODY_STYLE",
            "doors": "DOORS",
            "Confidence": CONFIDENCE,         
         }                              
      ]
      "left": LEFT,
      "top": TOP,
      "width": WIDTH,
      "height": HEIGHT
    }
        
    

Error Codes

Following errors can occur when the system attempts to locate & recognize a vehicle 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"?>
    <VMMR version="1.0" Date="3/7/2021 3:53:26 PM" Status="FAILED">
      <Message Key="0" Value="Database Errors." />
    </VMMR>
        
    
        

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

Coding Examples (XML and Json)

JavaScript(Python, C#, Java)


    <html>
    <head></head>
    <body>
    <form id = "form">
        <label>Please submit an image containing a vehicle:<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://vmmr.recognition.ws/v1?accesscode=YOUR_ACCESS_CODE"
        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://vmmr.recognition.ws/v1?accesscode=YOUR_ACCESS_CODE&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://vmmr.recognition.ws/v1?accesscode=YOUR_ACCESS_CODE"
    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 = "Make: " + xml[0].text
            print(output)

    ### Json

    import requests
    import json
    import os

    url = "https://vmmr.recognition.ws/v1?accesscode=YOUR_ACCESS_CODE&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://vmmr.recognition.ws/v1?accesscode=YOUR_ACCESS_CODE";
        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 "Make" item in the root tag.
        var el = root.Elements("Make");
        Console.WriteLine("Make: " + (string) el.Value);

        IEnumerable<XElement> test =
             from el in root.Elements("Make")
             where (string) el.Value != null
             select el;
         foreach (XElement el in test)
             Console.WriteLine("Make: " + (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://vmmr.recognition.ws/v1?accesscode=YOUR_ACCESS_CODE&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://vmmr.recognition.ws/v1?accesscode=YOUR_ACCESS_CODE");

            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://vmmr.recognition.ws/v1?accesscode=YOUR_ACCESS_CODE&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();
        }
    }