VIN Analyzer

API to analyze vehicle VIN numbers, return associated data, and also detect possible writing errors.

VIN stands for Vehicle Identification Number. This API allows you to analyze valid VIN numbers and extract the data associated with that VIN.

This API also allows detecting possible writing errors in the VIN codes, proposing possible nearby valid VINS.

API connection

Server and protocols involved.

API connection details
Server:	https://zpk.systems
Scheme:	HTTPS, secure connections only.
Protocol:	JSON recommended Sending a JSON in the request body, and specifying a Content-Type: application/json header in the request Files should be sent encoded as a base64 string. Form-Data not recommended Format used in web forms, not recommended. When sending a form_data request you can send all the fields separately. However if the request is very large we recommend that you send the content of the request in a single text field called _json (with an underscore). This special parameter will be processed by our backend as if it were a regular JSON request.

The server to send the requests to is https://zpk.systems, using a secure HTTPS connection.

The recommended communication type is JSON, in which case we will specify in the connection a Content-Type: application/json, and we will send the request body as a valid JSON string.

Endpoint & Parameters

POST /api/vin_analyzer/analyze
Parameter	Description
application_id	string required An application id. You can get the id of an application by clicking on 'details' in your panel
api_key	string required The API KEY of the application that makes the call to this API, you can obtain it in your panel, by clicking on the 'details' button of an application
vins	array : strings required One ore more VIN numbers to analyze.
score_filters	array optional When an invalid VIN is provided, this API will try to propose the correct VINS that it considers closest to the incorrect VIN provided. The score_filters array allows you to alter the internal score that different VIN codes receive based on data such as manufacturing area, country of manufacture, manufacturer name, or brand. Allowing, for example, to prioritize VINs from a specific manufacturer or country. score_filters must contain an array of elements, each of them indicating a filter and a score that will be applied in case that filter is met Ejemplo de score_filters `[ { "zone": "America", "country": "", "manufacturer": "", "brand": "", "score": "0.3" }, { "zone": "Europe", "country": "", "manufacturer": "", "brand": "", "score": "-0.3" } ]` In this example, three filters have been applied to alter the score, giving priority to vehicles manufactured in Africa, and penalizing those manufactured in America. Additionally, it is desired to filter out those manufacturers of tractors, and motorcycles. Vehicles manufactured in Africa will receive an extra +1 on their score Vehicles made in America will receive a -1 penalty on the score All manufacturers of motorcycles, buses, or tractors will receive a -20 penalty on their score. Zones, Countries and Manufacturers This API can provide you with all the manufacturers, countries, and commercial brands that a VIN can return. See: Getting all countries, Getting all manufacturers, Obtaining all brands

Responses

Success response

Response OK

{
  "success": true,
  "results": [
    {
      "sent": "L6TCX2E70ME005154",
      "vin": {
        "vin_number": "L6TCX2E70ME005154",
        "valid": true,
        "fixed": false,
        "year": 2021,
        "wmi": "L6T",
        "vis": "ME005154",
        "serial": "005154",
        "manufacturer_name": "Geely",
        "uses_manufacturation_plant_code": true,
        "manufacturation_plant_code": "E",
        "manufacturer_code": "L6T",
        "uses_check_digit": true,
        "provided_check_digit": "0",
        "expected_check_digit": "0",
        "valid_check_digit": true,
        "low_volume_manufacturer": false,
        "brands": [
          "geely"
        ],
        "country_name": "China (Mainland)",
        "country_zone": "Asia"
      },
      "considered_vins": [
        {
          "vin_code": "L6TCX2E70ME005154",
          "quality": 1
        }
      ]
    }
  ],
  "costs": {
    "base_request_cost": 0.007,
    "price_per_extra_vin": 0.003,
    "extra_vins": 0,
    "extra_vins_cost": 0,
    "total_cost": 0.007
  }
}

Response structure

Response structure
Parameter	Description
success	boolean A boolean with value true if your request could be processed. Or false, in case of errors.
results	array An array that will contain all the VINs that have been sent, along with the extracted data and an analysis of the validity of each VIN code. See the following table for details on the elements of this array.
costs	associative : array Detailed information on the cost of the request sent, where: base_request_cost: The minimum cost when making the request to scan a VIN, and price of first VIN. price_per_extra_vin: The cost of parsing an extra VIN code in the same request. extra_vins: The number of VINS sent apart from the first. If you submitted three VIN codes, extra_vins will be two. extra_vins_cost: The cost of analyzing the other VIN codes after the first one. total_cost: Total cost of API request.

results array structure

Parameter

Description

sent

string

The VIN code as it was sent in your request, before it is corrected in case of detecting errors.

vin

associative : array

Array with the information extracted from this VIN and the possible corrections in case of detecting a potentially wrongly typed VIN.

*vins* array structure
Parameter	Description
vin_number	string The VIN that the API finally processed, this VIN could be corrected if a possible typing error was detected, or if there were any characters missing from the submitted code that could be automatically deduced.
valid	boolean A boolean indicating whether the final VIN is considered correct or not. In those manufacturers or countries where a control digit is used, this is considered when determining if the VIN is correct or not.
fixed	boolean In the event that the submitted VIN has been corrected by the API as it is considered incorrect, it will be true
year	integer The year of manufacture of the vehicle if it can be calculated.
wmi	string The WMI (World Merchant Identifier) code of the VIN. A manufacturer identifier.
vis	string VIS Section (Vehicle Identification Section), the code that each manufacturer uses at its discretion internally to determine the vehicle and its characteristics.
serial	string The manufacturer's serial number, used by manufacturers internally and at their discretion.
manufacturer_name	string Manufacturer name.
uses_manufacturation_plant_code	boolean If there is evidence that this manufacturer does or does not use the manufacturing plant code internally, true if so.
manufacturation_plant_code	string A one-character code that identifies the vehicle's manufacturing plant.
manufacturer_code	string Manufacturer code, usually the same as WMI, with exceptions for some countries and manufacturers.
uses_check_digit	boolean Whether this manufacturer uses a check digit or not. Dependent on manufacturers, and geographical areas, with some exceptions. true if yes. For vehicles that use this digit, the API performs extra checks to better determine if the VIN code provided is correct or not.
provided_check_digit	string The check digit extracted from the VIN that was provided to the API. Before possible corrections.
expected_check_digit	string The check digit expected for this manufacturer.
valid_check_digit	boolean Whether the provided check digit is correct or not. To determine the final vin code, this validation is ignored in case the manufacturer does not use a check digit.
low_volume_manufacturer	boolean Indicates if it is a manufacturer with a low production volume. Multiple manufacturers of these vehicles are often grouped under the same manufacturer code.
brands	array : strings An array of strings containing the names of the brands involved in the production and/or manufacturing of the vehicle. In most cases it usually contains a single element.
country_name	string The country where the vehicle was manufactured or assembled.
country_zone	string The geographic area where the vehicle was assembled or manufactured. Possible values: Africa, Asia, Europe, North America, South America y Oceania

considered_vins

array

A list of the VINs that were considered during the autocorrection phase, in case the vin was considered correct as provided to the API will contain a single element.

In the event that the API has considered several VINs, this list will contain those that it has considered together with a quality score).

Each element of the considered_vins array contains:

vin_code: The considered VIN code string

quality: The score that the API gave to that vin code, and which may be affected by scoring filters if provided. float

Error response

Response ERROR

{
  "success": false,
  "errors": [
    {
      "id": "MISSING_REQUIRED_PARAMETER",
      "message": "Required parameter 'vins' not sent",
	  "on": "vins"
    }
  ]
}

Getting all manufacturers.

To get all the vehicle manufacturers that the API can return to prepare your database or to create your filters, you can use the following endpoint.

GET /api/vin-analyzer/manufacturers
Parameter	Description
application_id	string required An application id. You can get the id of an application by clicking on 'details' in your panel
api_key	string required The API KEY of the application that makes the call to this API, you can obtain it in your panel, by clicking on the 'details' button of an application

A list containing all possible manufacturers will be returned::

Manufacturers list

{
	"success": true,
	"manufacturers": [
		{
			"code": "LDC",
			"name": "Dongfeng Peugeot-Citroën",
			"zone": "Europe",
			"country": "Slovenia",
			"brands": ["Peugeor","Citroën"]
		}
	]
}

Getting all countries.

If you want to get all the countries where the vehicle manufacturers operate to prepare your database, or to create filters, you can use the following endpoint.

GET /api/vin-analyzer/countries
Parameter	Description
application_id	string required An application id. You can get the id of an application by clicking on 'details' in your panel
api_key	string required The API KEY of the application that makes the call to this API, you can obtain it in your panel, by clicking on the 'details' button of an application

A list with all the countries and the zone to which they belong will be returned.

Countries list

{
	"success": true,
	"countries": [
		{
			"code": "KA-KE",
			"name": "Sri Lanka",
			"zone": "Asia"
		}
	]
}

Obtaining all commercial brands.

If you need to get all the vehicle commercial brands that the API can return to prepare your database, or to create filters, you can use the following endpoint.

GET /api/vin-analyzer/brands
Parameter	Description
application_id	string required An application id. You can get the id of an application by clicking on 'details' in your panel
api_key	string required The API KEY of the application that makes the call to this API, you can obtain it in your panel, by clicking on the 'details' button of an application

A list with all commercial brands will be returned.

Brands list response

{
	"success": true,
	"brands": [
		"opel","peugeot","sundiro","..."
	]
}

PHP Integration

ZPK-PHP is an open source composer-installable library that will allow you to integrate our APIs into your PHP project with minimal effort.

Go to PHP-SDK

Installing ZPK-PHP with composer

Terminal

composer require zpksystems/phpzpk

Example PHP code

Ejemplo SDK en PHP

<?php
// Initialize ZPK application
$app = new zpkApplication('appid','key');

$vinAnalyzer = new VinAnalyzer($app);
$vinAnalyzer->addVin('L6TCX2E70ME005154');
$vinAnalyzer->addVins(['L6TCX2E70ME005154','6TCX2E70ME005154']);

// Make a request
$response = $vinAnalyzer->analyze()

var_dump($response);

Pricing

0,004 Euros/Request, 1 VIN

0,003 Euros for each extra VIN on the request

VinAnalyzer has a cost per number of requests, the cost per request is 0,004 which will be deducted from your current credit.

However, in each request you can request up to 20 VINS, the price for each extra VIN is only 0,003

If you do not have credit in your account when making a request, the VIN Analyzer API will return an error.

Pricing table

Requests	VINS per request	Request price	Vin decoding price
1	1	0,004	0,004
1	5	0,016	0,003
1	20	0,061	0,003
100	1	0,400	0,400
100	5	1,600	0,320
100	20	6,100	0,305
1.000	1	4,000	4,000
1.000	5	16,000	3,200
1.000	20	61,000	3,050
5.000	1	20,000	20,000
5.000	5	80,000	16,000
5.000	20	305,000	15,250
10.000	1	40,000	40,000
10.000	5	160,000	32,000
10.000	20	610,000	30,500
100.000	1	400,000	400,000
100.000	5	1.600,000	320,000
100.000	20	6.100,000	305,000

Signup to try

Login, or Signup for freee to test this API

Register Log in