API Documentation

 

VINdecode API 1.0 (Coding Examples)


Our VINdecode API provides specifications for a vehicle based on the vehicle identification number (VIN) submitted. Specifications include year, make, and model as well as features like engine and transmission, color, standard and optional equipment. This API method supports submission of one individual VIN at a time and the API returns detailed specifications. Returned data summarizes each vehicle's country of origin and year/make/model details along with engine and powertrain details, options included by the manufacturer, and other specifications like gross vehicle weight (GVW), MSRP, etc.


Our record indicates that some of those who have unlimited access to the VINdecode API tend to make excessive and sometimes even needless API calls. Regardless of the cause, the ability of blocking traffic from a specific source once it reaches a certain level is necessary for the overall health of our system. It ensures that one developer's actions cannot negatively impact the larger community. We reserve the right to throttle such excessive API calls or even to refuse service.

 

REST API Description

Our VINdecode API provides programmatic access to our VIN decode database.

Parameter Name Parameter Value Used in URL
API Key * accesscode * xxxxx-xxxxx-xxxxx-xxxxx GET https://ws.vinquery.com/restxml.aspx?acccesscode=xxxxx-xxxxx-xxxxx-xxxxx&vin=XXXXXXXXXXXXXXXXX&reporttype=3
Vehicle Identification Number * vin * XXXXXXXXXXXXXXXXX GET https://ws.vinquery.com/restxml.aspx?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&vin=XXXXXXXXXXXXXXXXX&reporttype=3
Data Type * reporttype * 0, 1, 2, 3 GET https://ws.vinquery.com/restxml.aspx?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&vin=XXXXXXXXXXXXXXXXX&reporttype=3
Partial VIN ** partialvin ** TRUE or FALSE (default: FALSE) GET https://ws.vinquery.com/restxml.aspx?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&vin=XXXXXXXXXXXXXXXXX&reporttype=3&partialvin=TRUE
* These three parameters are mandatory.
** Set the optional parameter "partialvin" to "TRUE" if you'd like our system NOT to validate the VIN. The system will NOT do checksum test before submitting the VIN to our decoding engine for processing. Set the value of this parameter to "FALSE" otherwise.

Lookup Tables

These tables are static. They don't change often, if at all.

Body Style Show the complete list of all possible body styles used in our system.
COUPE 2-DR CREW CAB PICKUP 4-DR CROSSOVER 4-DR EXTENDED CAB PICKUP 4-DR HATCHBACK 2-DR HATCHBACK 4-DR PASSENGER VAN REGULAR CAB PICKUP 2-DR SEDAN 4-DR SPORT UTILITY 4-DR SPORTS VAN WAGON 4-DR WAGON 5-DR
Vehice Type Show the complete list of all possible vehicle types used in our system.
BUS MOTORCYCLE MPV PASSENGER RECREATIONAL TRAILER VAN LOW SPEED VEHICLE ELECTRIC VEHICLE DUMP TRUCK TRACTOR TRUCK SNOWMOBILE ATV
Fuel Type
CNG DIESEL ELECTRIC FFV GAS HYBRID HYDROGEN LPG No data
Engine Shape
H12 H4 H6 L2 L3 L4 L5 L6 No data NO ENGINE ROTARY V10 V12 V20 V4 V6 V8 VL W12 W16 W8
Driveline
10X4 10X6 12X6 4WD 4X2 4X4 6X2 6X4 8X4 8X6 AWD FWD FWD | AWD RWD RWD | AWD 2WD No data

Error Codes

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.
6 Invalid report type. A valid report type should be 0 for BASIC, 1 for STANDARD, 2 for EXTENDED or 3 for LITE.
8 Service access denied: Double check your Access Code.
9 Report type missing: A report type (0,1,2 or 3) must be specified.
10 Insufficient balance for Basic Reports.
11 Insufficient balance for Standard Reports.
12 Insufficient balance for Extended Reports.
13 VIN missing: A VIN must be submitted as part of the querystring.
14 Invalid VIN number: The 10th digit of a VIN number cannot be letter U, letter Z or number 0.
15 Insufficient balance for Lite Reports.
16 A VIN can only contain alphanumeric characters.
        
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<VINquery version="1.0.0" report_type="EXTENDED" Date="5/28/2006">
  <VIN number="1FTRF02W24KXXXXXX" status="FAILED">
    <Message Key="3" Value="Invalid VIN number: This VIN number did not pass checksum test." />
  </VIN>
</VINquery>
        
    

Known Issues

  • A single VIN returns data related to multiple trim levels.
  • Occasionally, information coded by the manufacturer in a submitted VIN may not be sufficient for our VIN decoding engine to narrow it down to a single trim level so all available records for that particular VIN will be returned. In this case, all available trim levels may have to be presented to end users so they can make a selection from those returned choices.

  • A single trim level returns multiple transmissions, exterior colors, interior trims, ABS(Non-ABS |* 2-Wheel ABS |* 4-Wheel ABS) etc.
  • For instance, a decoded VIN may offer all exterior color choices that were available for a particular vehicle, but can't tell you what color the vehicle actually is - therefore all available color choices for the vehicle might have to be presented to end users so they can select the color or have the option to enter another color choice in case the vehicle was painted over.

    * "|" is used as a delimiters or separator when a data item contains multiple choices.

Coding Examples

JavaScript(Python, C#, Java, PHP)

    const url="https://ws.vinquery.com/restxml.aspx?accesscode=YOUR_ACCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN";

    //To fetch the XML data feed synchronously
    var parser = new DOMParser();
    var xhttp = new XMLHttpRequest();
    xhttp.open("GET", url, false);
    xhttp.send();
    xmlDoc = parser.parseFromString(xhttp.responseText,"text/xml");
    alert(xhttp.responseText);
    var output = "Model Year: " + xmlDoc.getElementsByTagName("Item")[0].getAttribute("Value") + "\n";
    output += "Make: " + xmlDoc.getElementsByTagName("Item")[1].getAttribute("Value") + "\n";
    output += "Model: " + xmlDoc.getElementsByTagName("Item")[2].getAttribute("Value") + "\n";
    ...
    alert(output);

    //To fetch the XML data feed asynchronously
    var parser = new DOMParser();
    var xhttp = new XMLHttpRequest();
    xhttp.open("GET", url, true);
    xhttp.send();
    xhttp.onreadystatechange = function () {
    if (this.readyState == 4 && this.status == 200) {      
        xmlDoc = parser.parseFromString(xhttp.responseText, "text/xml");
        alert(xhttp.responseText);
        var output = "Model Year: " + xmlDoc.getElementsByTagName("Item")[0].getAttribute("Value") + "\n";
        output += "Make: " + xmlDoc.getElementsByTagName("Item")[1].getAttribute("Value") + "\n";
        output += "Model: " + xmlDoc.getElementsByTagName("Item")[2].getAttribute("Value") + "\n";
        ...
        alert(output);
    }


Python(JavaScript, C#, Java, PHP)

    import xml.etree.ElementTree as ET
    import requests

    url = "https://ws.vinquery.com/restxml.aspx?accesscode=YOUR_ACCCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN"
    response = requests.get(url)
    xml = ET.fromstring(response.content.decode('UTF-8'))

    output = "Model Year: " + xml[0][0].attrib['Model_Year'] + "\n"
    output += "Make: " + xml[0][0].attrib['Make'] + "\n"
    output += "Model: " + xml[0][0].attrib['Model'] + "\n"
    output += "Trim Level: " + xml[0][0].attrib['Trim_Level']
    ...
    print(output)


C#(JavaScript, Python, Java, PHP)

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

    static void Main(string[] args)
    {
    String url = "https://ws.vinquery.com/restxml.aspx?accesscode=YOUR_ACCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN";
    WebRequest request = WebRequest.Create(url);
    WebResponse response = request.GetResponse();

    using (Stream dataStream = response.GetResponseStream())
    {
        StreamReader stream = new StreamReader(dataStream);
        String responseString = stream.ReadToEnd();

        XElement root = XElement.Parse(responseString);

        IEnumerable<XElement> tests =
            from el in root.Elements("VIN").Elements("Vehicle").Elements("Item")
            where (string) el.Attribute("Key") != null
            select el;
        foreach (XElement el in tests)
            Console.WriteLine((string) el.Attribute("Key") + ": " + (string) el.Attribute("Value"));
    }
    response.Close();
    }


Java(JavaScript, Python, C#, PHP)

    ...
    import java.net.HttpURLConnection;
    import java.net.URL;
    

    public static void main(String[] args) {
	    final URL url = new URL(
	    "https://ws.vinquery.com/restxml.aspx?accesscode=YOUR_ACCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN");
	    final HttpURLConnection con = (HttpURLConnection)url.openConnection();
	    con.setRequestMethod("GET");
                // use your favorite Java XML processing libraries for parsing, such as DOM Parser, SAX Parser, StAX Parser, 
                // JAXB, XStream, Jackson XML, Simple XML
                ...
	    con.disconnect();
    }

PHP(JavaScript, Python, C#, Java)

    <?php

    $response = file_get_contents('http://ws.vinquery.com/restxml.aspx?accesscode=YOUR_ACCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN');
    $response = new SimpleXMLElement($response);
    $string = $response -> asXML();

    echo($string);

    foreach($response -> VIN -> Vehicle -> Item as $Item) {
        echo $Item['Key'], ': ', $Item['Value'], ' ';
    }

    ?>