# VIN Decoder API (`caulleonard/vin-api`) Actor Validate and decode Vehicle Identification Numbers offline via a simple HTTP API. - **URL**: https://apify.com/caulleonard/vin-api.md - **Developed by:** [Fatih Şahinbaş](https://apify.com/caulleonard) (community) - **Categories:** Developer tools - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.00 / 1,000 api-calls This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## VIN Decoder API — Validate & Decode Vehicle Identification Numbers A fast, **offline VIN decoder** and validator. Check the ISO 3780 check digit, identify the country of manufacture and the manufacturer, decode the model year, plant code and serial number — all through simple GET requests. No third-party lookups, no API keys to juggle, no rate limits, no US-only coverage. ### What it does - ✅ **Validate a VIN** — length, forbidden letters (`I`, `O`, `Q`) and the ISO 3780 check digit, with clear error messages. - 🔍 **Decode the structure** — WMI, VDS and VIS sections, country, manufacturer, model year, assembly plant code and serial number. - 🔢 **Calculate the check digit** — get the correct position-9 character and a corrected VIN. ### Why offline matters Most free VIN tools proxy a government database: they're rate-limited, they go down, and they typically only cover vehicles sold in the United States. This API resolves everything from the VIN's own structure using embedded reference tables, so it answers in milliseconds for **any** VIN worldwide — European, Japanese, Korean, Chinese, Turkish, Brazilian and more. ### Honest about what a VIN can tell you Positions 4–8 (the VDS) are **manufacturer-specific with no public standard**. Any generic decoder claiming to read your trim level, engine or transmission from those five characters is guessing. This API returns what is genuinely derivable from the VIN and says so explicitly — no invented specs in your data pipeline. ### The check digit nuance Position 9 is a mandatory checksum in North America and South Korea. Most **European and Japanese** manufacturers don't use a conforming check digit — a real Volkswagen VIN will "fail" a naive checksum test. This API reports two separate fields: - `checkDigitValid` — does the supplied digit match the calculation? - `checkDigitRequired` — is a conforming check digit expected for this market? So a legitimate European VIN is never wrongly flagged as invalid. ### VIN structure | Position | Section | Meaning | |----------|---------|---------| | 1–3 | **WMI** | World Manufacturer Identifier (country + manufacturer) | | 4–8 | **VDS** | Vehicle Descriptor Section (manufacturer-specific) | | 9 | Check digit | ISO 3780 modulo-11 checksum | | 10 | Model year | 30-year cycle code | | 11 | Plant code | Assembly plant | | 12–17 | Serial | Production sequence | ### Endpoints All endpoints are **GET** and return JSON. | Endpoint | Purpose | Params | |----------|---------|--------| | `/validate` | Validate structure and check digit | `vin` | | `/decode` | Full structural decode | `vin` | | `/checkdigit` | Compute the correct check digit | `vin` | ### Examples **Decode** ```` GET /decode?vin=WVWZZZ1JZ3W386752 ```` ```json { "normalized": "WVWZZZ1JZ3W386752", "valid": true, "checkDigit": "9", "checkDigitValid": false, "checkDigitRequired": false, "wmi": "WVW", "vds": "ZZZ1J", "vis": "3W386752", "country": "Germany", "manufacturer": "Volkswagen", "modelYearCode": "3", "modelYear": 2003, "modelYearAlternate": 2033, "plantCode": "W", "serialNumber": "386752" } ```` **Validate** ``` GET /validate?vin=1HGCM82633A004352 ``` ```json { "valid": true, "normalized": "1HGCM82633A004352", "errors": [], "checkDigit": "3", "checkDigitValid": true, "checkDigitRequired": true } ``` **Fix a typo** ``` GET /checkdigit?vin=1M8GDM9A0KP042788 ``` ```json { "checkDigit": "X", "provided": "0", "matches": false, "corrected": "1M8GDM9AXKP042788" } ``` ### Who it's for Dealership and marketplace platforms validating listing input, insurance and leasing systems checking policy data, fleet management tools, auction and salvage sites, parts catalogs, and anyone importing vehicle records who needs to catch transcription errors before they spread. ### Model year ambiguity The position-10 code repeats on a 30-year cycle, so `3` means either 2003 or 2033. For North American VINs the API disambiguates using position 7 (per FMVSS 565). Elsewhere it reports the plausible year and returns the other candidate in `modelYearAlternate` — never a silent guess. ### Tips - Spaces and hyphens in the input are ignored, and lowercase input is normalized. - A VIN never contains `I`, `O` or `Q` — if you see one, it's almost always a transcription error for `1` or `0`. - Use `/checkdigit` on North American VINs to catch single-character typos in imported data. - `manufacturer` may be `null` for rare or very new WMIs; `country` still resolves from the WMI range. ### Pricing Pay-per-event: **$0.001 per successful API call**. Readiness/health checks are never charged. No subscription, no minimums. # Actor input Schema ## Actor input object example ```json {} ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("caulleonard/vin-api").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("caulleonard/vin-api").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call caulleonard/vin-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=caulleonard/vin-api", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "VIN Decoder API", "description": "Validate and decode Vehicle Identification Numbers offline via a simple HTTP API.", "version": "0.0", "x-build-id": "ecb6vMFYnihJOxPRf" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/caulleonard~vin-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-caulleonard-vin-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/caulleonard~vin-api/runs": { "post": { "operationId": "runs-sync-caulleonard-vin-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/caulleonard~vin-api/run-sync": { "post": { "operationId": "run-sync-caulleonard-vin-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": {} }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```