API Documentation

 

VINfix API 2.0 (Coding Examples)


The VINfix API generates one or more suggestions when a problematic VIN is submitted. It is up to the end users to make the final decision on which suggestion to use, or to choose not to use any of the suggestions. Therefore, batch processing without human oversight is not recommended.

Avoid Submitting the Same VIN Multiple Times

Our system deducts one credit from your account balance for each XML result returned, regardless of the outcome. To prevent unnecessary charges, ensure your system has a mechanism to avoid sending the same VIN to the API service more than once.

 

REST API Description

VINfix API provides programmatic access to two of our state-of-the-art machine learning algorithms.

Parameter Name Parameter Value Used in URL
API Key accesscode xxxxx-xxxxx-xxxxx-xxxxx GET https://www.recognition.ws/vinfix/v2?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&vin=XXXXXXXXXXXXXXXXX
Vehicle Identification Number vin XXXXXXXXXXXXXXXXX GET https://www.recognition.ws/vinfix/v2?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&vin=XXXXXXXXXXXXXXXXX
Data Format format XML or JSON (default: XML) GET https://www.recognition.ws/vinfix/v2?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&vin=XXXXXXXXXXXXXXXXX&format=json

Output in XML or Json

VINfix API 1.0 has now been deprecated. It produces suggestions made by two machine learning algorithms: Algorithm 1 and Algorithm 2.

  • Algorithm 1 and Algorithm 2 don't always agree with each other;
  • Algorithm 1 usually produces more accurate suggestions than Algorithm 2 does;
  • Algorithm 1 always produces at least one suggestion;
  • Algorithm 1 usually produces only one suggestion;
  • Algorithm 2 often produces more than one suggestions;
  • Algorithm 2 could produce no suggestions at all.
  • It is recommended that the suggestions from Algorithm 2 should be hidden from end-users by default unless the suggestions from Algorithm 1 were not satifactory and a second opinion was needed.
                    
<VINfix Date="4/22/2015" Version="1.0" Status="SUCCESS" Number="XXXXXXXXXXX123456>
    <Algorithm1>
    <Item Value="XXXXXXXXXXX123456" Key="Suggestion1"/>
        <Item Value="..." Key="..."/>
        <Item Value="XXXXXXXXXXX123456" Key="SuggestionM"/>
    </Algorithm1>
    <Algorithm2>
       <Item Value="XXXXXXXXXXX123456" Key="Suggestion1"/>
       <Item Value="..." Key="..."/>
       <Item Value="XXXXXXXXXXX123456" Key="SuggestionN"/>
    </Algorithm2>
</VINfix>
        
    

VINfix API 2.0 produces only one suggestion with much higher accuracy and confidence. You no longer have to choose between two different outcomes. The system is smart enough to make the decision for you behind the scene. It can deliver results in either formats: XML or Json.

                    
API with XML return: https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=XXXXXXXXXXX123456&format=xml

<VINfix>
    <Version>2.0</Version>
    <Date>3/30/2021 2:03:34 AM</Date>
    <Status>SUCCESS</Status>
    <Input>XXXXXXXXXXX123456</Input>
    <Output>XXXXXXXXXXX123456</Output>
</VINfix>
        
    
                    
API with Json return: https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=XXXXXXXXXXX123456&format=json

{
  "service": "vinfix",
  "version": "2.0",
  "date": "3/30/2021 3:36:54 AM",
  "status": "SUCCESS",
  "input": "XXXXXXXXXXX123456",
  "ouput": "XXXXXXXXXXX123456"
}
        
    

Error Codes

Error Code (Key) Description (Value)
0 Database Errors.
17 Insufficient balance for VINfix
18 Length of VIN too short for VINfix; It must be at least 10 digits.
19 Invalid VIN number: The last 4 digits of this VIN number must all be numeric.
20 Invalid VIN number: The last 6 digits of this VIN number must all be numeric.
21 Invalid VIN number: The 12th digit of this VIN number must be a letter.
22 Invalid VIN number: The 13th digit of this VIN number must be a letter.
28 VINfix data model not ready.
                    

A sample error message returned in XML format:

<VINfix>
    <Version>2.0</Version>
    <Date>3/30/2021 2:21:09 AM</Date>
    <Status>FAILED</Status>
    <Input>1F4W3MCB0VA807600</Input>
    <Message_Key>0</Message_Key>
    <Message>Database Errors.</Message>
</VINfix>
        
    
                    
A sample error message returned in Json format:

{
  "service": "vinfix",
  "version": "2.0",
  "date": "3/30/2021 5:38:03 AM",
  "status": "FAILED",
  "input": "1F4W3MCB0VA807600",
  "message_key": 0,
  "message": "Database Errors."
}
        
    

Coding Examples (XML and Json)

JavaScript(Python, C#, Java, PHP, Swift)

    <html>
        <head></head>
        <body>
            <form id = "form">
                <label>Please input a VIN:<input type="text" id ="input"></label>
                <br>
                <a href="javascript: fetchResponseXml()">Submit (XML Output)</a>
                <br>
                <a href="javascript: fetchResponseJson()">Submit (Json Output)</a>
            </<form>
            <pre id="out"></pre>
        </body>

        <script>
            const form=document.getElementById("form")
            const out=document.getElementById("out")

        // Javascript XML 
            async function fetchResponseXml(){
                const url="https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN;
                var parser=new DOMParser();
                var xmlHttp=new XMLHttpRequest();
                xmlHttp.open("GET", url, false);
                xmlHttp.send();
                var xmlResponse=parser.parseFromString(xmlHttp.responseText, "text/xml");
                console.log(xmlResponse)

                var text="";
                var children=xmlResponse.documentElement.childNodes;
                for (var i=0; i < children.length; i++){
                    console.log(children)
                    // text += children[i].tagName+": "+children[i].textContent+"\n"
                    text += children[i].nodeName+": "+children[i].textContent+"\n"
                }
                out.textContent=text;
            }

        // Javascript Json
            async function fetchResponseJson(){
                const url = "https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN&format=json";
                fetch(url).then(function(response){
                    return response.json()
                }).then(function(data){
                    let text="";
                    for (let x in data){
                        text+=x+": "+data[x]+"\n";
                    }   
                    out.textContent=text;
                }).catch(function(){
                    out.textContent="Something went wrong..."
                });
            }
        </script>
    </html>

Python(JavaScript, C#, Java, PHP, Swift)


    # Python XML

    import requests
    import xml.etree.ElementTree as ET

    url = "https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN"

    response = requests.get(url)
    root = ET.fromstring(response.content.decode('UTF-8'))

    if root[2].text=="SUCCESS":
        print("Version: "+root[0].text)
        print("Date: "+root[1].text)
        print("Status: "+root[2].text)
        print("Input: "+root[3].text)
        print("Output: "+root[4].text)
    else:
        print("Version: "+root[0].text)
        print("Date: "+root[1].text)
        print("Status: "+root[2].text)
        print("Input: "+root[3].text)
        print("Message Key: "+root[4].text)
        print("Message: "+root[5].text)



    # Python Json

    import requests
    import json

    url = "https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN&format=json"

    response = requests.get(url)
    result=response.json()

    if result["status"]=="SUCCESS":
        print("Service: "+result["service"])
        print("Version: "+result["version"])
        print("Date: "+result["date"])
        print("Status: "+result["status"])
        print("Input: "+result["input"])
        print("Output: "+result["output"])
    else:
        print("Service: "+result["service"])
        print("Version: "+result["version"])
        print("Date: "+result["date"])
        print("Status: "+result["status"])
        print("Message Key: "+str(result["message_key"]))
        print("Message: "+result["message"])

C#(JavaScript, Python, Java, PHP, Swift)

    using System;
    using System.Net;
    using System.Xml;


    WebClient client = new WebClient();

    // C# XML

    string url = "https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN";
    string responseString = client.DownloadString(url);

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

    var xmlResponse = new XmlDocument();
    xmlResponse.LoadXml(responseString);

    foreach (XmlNode node in xmlResponse.DocumentElement.ChildNodes)
    {
        Console.WriteLine(node.Name + ": " + node.InnerText);
    }



    // C# Json 

    using System;
    using System.Net;
    using Newtonsoft.Json.Linq;

    String url = "https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN&format=json";
    String responseString = client.DownloadString(url);

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

    // Java XML
    import java.io.BufferedReader;
    import java.io.InputStreamReader;
    import java.io.StringReader;
    import java.net.HttpURLConnection;
    import java.net.URL;

    import org.w3c.dom.Document;
    import org.w3c.dom.Node;
    import org.w3c.dom.NodeList;
    import org.xml.sax.InputSource;
    import javax.xml.parsers.*;

    String response = "";
    URL url = new URL("https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN");
    final HttpURLConnection con = (HttpURLConnection) url.openConnection();
    con.setRequestMethod("GET");
    BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream()));
    StringBuilder sb = new StringBuilder();
    while ((response = br.readLine()) != null) {
        sb.append(response);
    }

    response = sb.toString();
    con.disconnect();

    System.out.println(response);
    String output = "";
    output = parseXML(response);
    System.out.println(output);

    private static String parseXML(String response) {
        String output = "";
        DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
        DocumentBuilder builder = factory.newDocumentBuilder();
        Document document = builder.parse(new InputSource(new StringReader(response)));
        document.getDocumentElement().normalize();

        NodeList list = document.getFirstChild().getChildNodes();
        Node node;
        for (int i = 0; i < list.getLength(); i++) {
            node = list.item(i);
            if (node.getNodeType() == Node.ELEMENT_NODE) {
                output += node.getNodeName() + ": " + node.getTextContent() + "\n";
            }
        }

        return output;
    }



    // Java Json
    import java.io.BufferedReader;
    import java.io.InputStreamReader;
    import java.io.StringReader;
    import java.net.HttpURLConnection;
    import java.net.URL;

    import org.json.JSONArray;
    import org.json.JSONObject;

    String response = "";
    URL url = new URL("https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN&format=json");
    final HttpURLConnection con = (HttpURLConnection) url.openConnection();
    con.setRequestMethod("GET");
    BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream()));
    StringBuilder sb = new StringBuilder();
    while ((response = br.readLine()) != null) {
        sb.append(response);
    }

    response = sb.toString();
    con.disconnect();

    System.out.println(response);
    String output = "";
    output = parseJSON(response);
    System.out.println(output);

    private static String parseJSON(String response) {
        String output = "";
        JSONObject jsonObject = new JSONObject(response.trim());
        JSONArray names = jsonObject.names();

        for (int i = 0; i < names.length(); i++) {
            output += names.getString(i) + ": " + jsonObject.get(names.getString(i)) + "\n";
        }
        return output;
    }

PHP(JavaScript, Python, C#, Java, Swift)

    // PHP XML

    <?php

    $responseXml = file_get_contents("https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN");
    // echo($responseXml);

    // Trim whitespace to avoid empty text nodes.
    $responseXml = preg_replace("/>\s*<", $responseXml);

    $xml = new DOMDocument();
    $xml -> loadXML($responseXml);
    $children = $xml -> documentElement -> childNodes;

    foreach ($children as $child) {
        echo ($child -> nodeName.': '.$child -> nodeValue."\n");
    }
    ?>
    
    

    // PHP Json

    <?php

    $responseJson = file_get_contents("https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN&format=json");
    // echo($responseJson);

    $json = json_decode($responseJson, true);
    foreach ($json as $key => $value) {
        echo($key.": ".$value."\n");
    }

    ?>
Swift(JavaScript, Python, C#, Java, PHP)

    // Swift XML

    import UIKit

    if let url = URL(string: "https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN") {
        do {
            let contents = try String(contentsOf: url)
            print(contents)
        } catch {
            print("contents of the URL couldn't be loaded")
        }
    } else {
        print("bad URL, try again")
    }

    
    

    // Swift Json

    import UIKit

    if let url = URL(string:"https://www.recognition.ws/vinfix/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN&format=json") {
        do {
            let contents = try String(contentsOf: url)
            print(contents)
        } catch {
            print("contents of the URL couldn't be loaded")
        }
    } else {
        print("bad URL, try again")
    }