API Documentation

VMMR API 1.0 (Coding Examples)

Similar to our LPR API, our VMMR API can be deployed in two main ways: the entire process can be performed on-site in real-time, or images from multiple locations can be transmitted to a central location for later processing via our VMMR API. When processed on-site, the vehicle image, date-time, location identification, and any other required information can be captured and transmitted to remote computers for further processing, or stored locally for later retrieval. To achieve the highest possible recognition speed, image size is a critical 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. 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, Swift)



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


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

    // JavaScript 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, Swift)



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

    ### Python 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, Swift)



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

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

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

Swift(JavaScript, Python, C#, Java)



    // Swift XML

    import UIKit

    let url = URL(string: "https://vmmr.recognition.ws/v1?accesscode=YOUR_ACCESS_CODE")
    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://vmmr.recognition.ws/v1?accesscode=YOUR_ACCESS_CODE&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()