diff --git a/docs-site/public/specs/vin-decoder.yaml b/docs-site/public/specs/vin-decoder.yaml
new file mode 100644
index 0000000..7e40b3a
--- /dev/null
+++ b/docs-site/public/specs/vin-decoder.yaml
@@ -0,0 +1,405 @@
+openapi: 3.1.0
+info:
+ title: VIN Decoder API
+ version: 1.0.0
+ description: |
+ Decode any 17-character Vehicle Identification Number (VIN) into structured
+ vehicle data including make, model, year, trim, engine, body style, and more.
+ Powered by the NHTSA vPIC public-domain database.
+
+ **Data source:** NHTSA Product Information Catalog and Vehicle Listing (vPIC)
+ public API - US federal government data, public domain (17 U.S.C. 105).
+
+ **Coverage:** Model years 1981-present, all major manufacturers registered
+ with NHTSA (domestic and import).
+
+ **Caching:** Decoded results are cached for 90 days; cache status is
+ indicated by the X-Cache response header.
+ contact:
+ name: leeworks.dev API Support
+ url: https://docs.leeworks.dev
+ license:
+ name: MIT
+ url: https://opensource.org/licenses/MIT
+
+servers:
+ - url: https://vin.leeworks.dev/v1
+ description: Production
+
+security:
+ - RapidApiProxy: []
+
+tags:
+ - name: decode
+ description: VIN decoding endpoints
+ - name: health
+ description: Service health and observability
+
+paths:
+ /decode:
+ get:
+ operationId: decodeVin
+ summary: Decode a single VIN
+ description: |
+ Decodes a 17-character VIN and returns structured vehicle attributes.
+ Results are cached for 90 days; a cache hit is indicated by
+ X-Cache: HIT in the response headers.
+ tags:
+ - decode
+ parameters:
+ - name: vin
+ in: query
+ required: true
+ description: 17-character Vehicle Identification Number (uppercase, no I/O/Q).
+ schema:
+ type: string
+ minLength: 17
+ maxLength: 17
+ pattern: "^[A-HJ-NPR-Z0-9]{17}$"
+ example: 1HGCM82633A004352
+ - name: raw
+ in: query
+ required: false
+ description: If true, include raw NHTSA vPIC fields in the response.
+ schema:
+ type: boolean
+ default: false
+ responses:
+ "200":
+ description: VIN successfully decoded
+ headers:
+ X-Cache:
+ schema:
+ type: string
+ enum: [HIT, MISS]
+ description: Whether the result was served from cache
+ X-Data-Source:
+ schema:
+ type: string
+ description: Upstream data source identifier
+ X-Request-Id:
+ schema:
+ type: string
+ description: Unique request identifier
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/VinDecodeResult"
+ "400":
+ description: Invalid VIN format or missing parameter
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Error"
+ "403":
+ description: Missing or invalid RapidAPI proxy secret
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Error"
+ "429":
+ description: Rate limit exceeded for your plan
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Error"
+ "500":
+ description: Internal server error or upstream NHTSA API failure
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Error"
+
+ /batch:
+ post:
+ operationId: decodeVinBatch
+ summary: Decode up to 50 VINs in a single request
+ description: |
+ Accepts a JSON body with an array of VINs (1-50) and returns a decoded
+ result for each. Each VIN is processed independently; partial failures
+ return an error object in that position rather than failing the whole batch.
+ tags:
+ - decode
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - vins
+ properties:
+ vins:
+ type: array
+ minItems: 1
+ maxItems: 50
+ items:
+ type: string
+ minLength: 17
+ maxLength: 17
+ pattern: "^[A-HJ-NPR-Z0-9]{17}$"
+ description: Array of 17-character VINs to decode
+ example:
+ vins:
+ - 1HGCM82633A004352
+ - WBABW33486PX01612
+ responses:
+ "200":
+ description: Batch decode results (one entry per input VIN, in order)
+ headers:
+ X-Request-Id:
+ schema:
+ type: string
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ results:
+ type: array
+ items:
+ oneOf:
+ - $ref: "#/components/schemas/VinDecodeResult"
+ - $ref: "#/components/schemas/VinDecodeError"
+ count:
+ type: integer
+ description: Total number of VINs processed
+ cached_count:
+ type: integer
+ description: Number of results served from cache
+ error_count:
+ type: integer
+ description: Number of VINs that could not be decoded
+ "400":
+ description: Invalid request body
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Error"
+ "403":
+ description: Missing or invalid RapidAPI proxy secret
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Error"
+ "429":
+ description: Rate limit exceeded
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Error"
+ "500":
+ description: Internal server error
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Error"
+
+ /health:
+ get:
+ operationId: healthCheck
+ summary: Service health check
+ description: |
+ Returns health status of the VIN Decoder service including cache
+ statistics and NHTSA API reachability. Does not require X-RapidAPI-Proxy-Secret.
+ tags:
+ - health
+ security: []
+ responses:
+ "200":
+ description: Service is healthy
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/HealthResponse"
+ "503":
+ description: Service is degraded (upstream unreachable or DB error)
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/HealthResponse"
+
+components:
+ securitySchemes:
+ RapidApiProxy:
+ type: apiKey
+ in: header
+ name: X-RapidAPI-Proxy-Secret
+ description: |
+ RapidAPI proxy secret injected automatically by RapidAPI on every
+ subscriber request. Direct callers must include this header manually.
+
+ schemas:
+ VinDecodeResult:
+ type: object
+ required:
+ - vin
+ - error_code
+ properties:
+ vin:
+ type: string
+ description: The input VIN (uppercased)
+ example: 1HGCM82633A004352
+ make:
+ type: ["string", "null"]
+ description: Vehicle manufacturer brand
+ example: HONDA
+ model:
+ type: ["string", "null"]
+ description: Vehicle model name
+ example: Accord
+ model_year:
+ type: ["string", "null"]
+ description: Model year as a 4-digit string
+ example: "2003"
+ trim:
+ type: ["string", "null"]
+ description: Trim level (e.g. EX, LX, Sport)
+ example: EX
+ series:
+ type: ["string", "null"]
+ description: Series designation if applicable
+ body_class:
+ type: ["string", "null"]
+ description: Body style classification
+ example: Sedan/Saloon
+ drive_type:
+ type: ["string", "null"]
+ description: Drive configuration
+ example: FWD/Front-Wheel Drive
+ engine_displacement_cc:
+ type: ["number", "null"]
+ description: Engine displacement in cubic centimetres
+ example: 2354
+ engine_displacement_l:
+ type: ["number", "null"]
+ description: Engine displacement in litres
+ example: 2.4
+ engine_cylinders:
+ type: ["integer", "null"]
+ description: Number of engine cylinders
+ example: 4
+ fuel_type_primary:
+ type: ["string", "null"]
+ description: Primary fuel type
+ example: Gasoline
+ transmission_style:
+ type: ["string", "null"]
+ description: Transmission type (Automatic, Manual, CVT, etc.)
+ example: Automatic
+ transmission_speeds:
+ type: ["string", "null"]
+ description: Number of transmission speeds as string
+ example: "5"
+ plant_city:
+ type: ["string", "null"]
+ description: Assembly plant city
+ example: MARYSVILLE
+ plant_state:
+ type: ["string", "null"]
+ description: Assembly plant state/province
+ example: OHIO
+ plant_country:
+ type: ["string", "null"]
+ description: Assembly plant country
+ example: UNITED STATES (USA)
+ manufacturer_name:
+ type: ["string", "null"]
+ description: Full legal name of the manufacturer
+ example: HONDA OF AMERICA MFG., INC.
+ vehicle_type:
+ type: ["string", "null"]
+ description: NHTSA vehicle type classification
+ example: PASSENGER CAR
+ error_code:
+ type: string
+ description: NHTSA decode error code. "0" means successful decode.
+ example: "0"
+ error_text:
+ type: ["string", "null"]
+ description: Human-readable decode error (null when error_code is "0")
+ cached:
+ type: boolean
+ description: Whether this result was served from the local cache
+ example: true
+
+ VinDecodeError:
+ type: object
+ required:
+ - vin
+ - error
+ - message
+ properties:
+ vin:
+ type: string
+ description: The VIN that could not be decoded
+ error:
+ type: string
+ description: Error code
+ example: INVALID_VIN
+ message:
+ type: string
+ description: Human-readable error description
+ example: VIN must be exactly 17 alphanumeric characters
+
+ Error:
+ type: object
+ required:
+ - error
+ - message
+ - status
+ properties:
+ error:
+ type: string
+ description: Machine-readable error code
+ example: BAD_REQUEST
+ message:
+ type: string
+ description: Human-readable error description
+ example: "Query parameter 'vin' is required"
+ status:
+ type: integer
+ description: HTTP status code
+ example: 400
+
+ HealthResponse:
+ type: object
+ required:
+ - status
+ - version
+ properties:
+ status:
+ type: string
+ enum: [ok, degraded]
+ description: Overall service health
+ version:
+ type: string
+ description: Service version
+ example: "1.0.0"
+ uptime_seconds:
+ type: integer
+ description: Seconds since the service started
+ example: 86400
+ cache:
+ type: object
+ properties:
+ entries:
+ type: integer
+ description: Number of cached VIN records
+ hit_rate_24h:
+ type: number
+ description: Cache hit rate over the last 24 hours (0.0-1.0)
+ size_mb:
+ type: number
+ description: SQLite cache file size in megabytes
+ upstream:
+ type: object
+ properties:
+ nhtsa_vpic:
+ type: string
+ enum: [reachable, unreachable]
+ description: NHTSA vPIC API reachability
+ last_check:
+ type: string
+ format: date-time
+ description: ISO-8601 timestamp of last upstream health check
diff --git a/docs-site/src/pages/blog/vin-decoder.mdx b/docs-site/src/pages/blog/vin-decoder.mdx
new file mode 100644
index 0000000..094b1f2
--- /dev/null
+++ b/docs-site/src/pages/blog/vin-decoder.mdx
@@ -0,0 +1,340 @@
+---
+title: "How to Decode a VIN Number with Node.js Using Free NHTSA Data"
+description: "Learn how to decode any 17-character Vehicle Identification Number (VIN) with Node.js using the free NHTSA vPIC database — or skip the plumbing and call the leeworks.dev VIN Decoder API directly."
+date: "2026-05-30"
+author: "leeworks.dev"
+tags: ["vin-decoder", "nodejs", "automotive", "api", "tutorial"]
+---
+
+import Base from '../../layouts/Base.astro';
+
+
+
+
+
+
+
+# How to Decode a VIN Number with Node.js Using Free NHTSA Data
+
+Every vehicle sold in the United States since 1981 carries a unique 17-character fingerprint stamped into the chassis: the **Vehicle Identification Number**, or VIN. Decode it and you unlock make, model, year, trim level, engine type, body class, transmission, plant of manufacture, and more — without paying Carfax $40 per report.
+
+In this tutorial you'll learn how VINs are structured, how to query the free NHTSA vPIC database directly in Node.js, and how to call the **leeworks.dev VIN Decoder API** for a production-ready solution that handles caching, error handling, and batch decoding out of the box.
+
+---
+
+## What Is a VIN?
+
+A VIN is a 17-character alphanumeric string divided into three logical sections:
+
+| Section | Characters | Name | What It Encodes |
+|---------|-----------|------|-----------------|
+| **WMI** | 1–3 | World Manufacturer Identifier | Country of origin + manufacturer |
+| **VDS** | 4–9 | Vehicle Descriptor Section | Model, body style, engine type, check digit |
+| **VIS** | 10–17 | Vehicle Identifier Section | Model year, plant, sequential serial number |
+
+### Breaking down a real VIN
+
+Take `1HGCM82633A004352` — a 2003 Honda Accord EX:
+
+- `1HG` → Manufactured in the USA by Honda
+- `CM826` → Accord EX 4-door sedan, 2.4L i-VTEC engine (position 9 = check digit `3`)
+- `3` → Model year 2003 (position 10)
+- `A` → Marysville, Ohio assembly plant (position 11)
+- `004352` → Sequential production number
+
+VIN characters deliberately exclude `I`, `O`, and `Q` to avoid confusion with `1`, `0`, and `0` respectively — something to remember when validating user input.
+
+---
+
+## Why NHTSA vPIC?
+
+The **NHTSA Product Information Catalog and Vehicle Listing (vPIC)** is a US federal government database maintained by the National Highway Traffic Safety Administration. It covers:
+
+- All model years 1981 to present
+- Every manufacturer registered with NHTSA (domestic and imported)
+- 70+ decoded attributes per VIN including engine displacement, fuel type, GVWR, and more
+- **No API key, no rate limits** (beyond fair-use throttling), **public domain** under 17 U.S.C. 105
+
+The base endpoint is:
+
+```
+https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinValues/{vin}?format=json
+```
+
+---
+
+## Calling NHTSA vPIC Directly in Node.js
+
+Here's a minimal Node.js script using the built-in `fetch` API (Node 18+):
+
+```js
+// decode-vin.js
+const VIN = process.argv[2] ?? '1HGCM82633A004352';
+
+async function decodeVin(vin) {
+ // Validate: 17 chars, no I/O/Q
+ if (!/^[A-HJ-NPR-Z0-9]{17}$/.test(vin)) {
+ throw new Error(`Invalid VIN format: ${vin}`);
+ }
+
+ const url = `https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinValues/${vin}?format=json`;
+ const res = await fetch(url);
+
+ if (!res.ok) {
+ throw new Error(`NHTSA returned HTTP ${res.status}`);
+ }
+
+ const json = await res.json();
+ const r = json.Results[0];
+
+ return {
+ vin: r.VIN,
+ make: r.Make,
+ model: r.Model,
+ modelYear: r.ModelYear,
+ trim: r.Trim,
+ series: r.Series,
+ bodyClass: r.BodyClass,
+ driveType: r.DriveType,
+ engineDisplacementL: r.DisplacementL,
+ engineCylinders: r.EngineCylinders,
+ fuelTypePrimary: r.FuelTypePrimary,
+ transmissionStyle: r.TransmissionStyle,
+ manufacturerName: r.Manufacturer,
+ plantCity: r.PlantCity,
+ plantState: r.PlantState,
+ plantCountry: r.PlantCountry,
+ errorCode: r.ErrorCode,
+ errorText: r.ErrorText,
+ };
+}
+
+decodeVin(VIN)
+ .then(data => console.log(JSON.stringify(data, null, 2)))
+ .catch(err => { console.error(err.message); process.exit(1); });
+```
+
+Run it:
+
+```bash
+node decode-vin.js 1HGCM82633A004352
+```
+
+Expected output (abridged):
+
+```json
+{
+ "vin": "1HGCM82633A004352",
+ "make": "HONDA",
+ "model": "Accord",
+ "modelYear": "2003",
+ "trim": "EX",
+ "bodyClass": "Sedan/Saloon",
+ "driveType": "FWD/Front-Wheel Drive",
+ "engineDisplacementL": "2.4",
+ "engineCylinders": "4",
+ "fuelTypePrimary": "Gasoline",
+ "transmissionStyle": "Automatic",
+ "manufacturerName": "HONDA OF AMERICA MFG., INC.",
+ "plantCity": "MARYSVILLE",
+ "plantState": "OHIO",
+ "plantCountry": "UNITED STATES (USA)"
+}
+```
+
+---
+
+## The Problem with Rolling Your Own
+
+Calling NHTSA directly works great for a quick script. But for a production application, you'll quickly run into friction:
+
+1. **No caching** — every request hits the NHTSA servers. At scale, this is slow (NHTSA p99 ≈ 800ms) and risks being throttled.
+2. **Raw NHTSA response** — the flat key/value array has 80+ fields, many empty; you need to map and filter these yourself.
+3. **No batch support** — decoding 50 VINs means 50 sequential round-trips.
+4. **No SLA** — the NHTSA API is a government service; it has no uptime guarantee.
+5. **Header boilerplate** — proxy-secret validation, request IDs, CORS headers — you write it every time.
+
+---
+
+## Using the leeworks.dev VIN Decoder API
+
+The **leeworks.dev VIN Decoder API** wraps NHTSA vPIC with a 90-day SQLite cache, pre-mapped response schema, and batch endpoint — all available on RapidAPI.
+
+### Single VIN decode
+
+```js
+// Using the leeworks.dev VIN Decoder API
+const VIN = '1HGCM82633A004352';
+const API_KEY = process.env.RAPIDAPI_KEY; // Your RapidAPI key
+
+const res = await fetch(`https://vin.leeworks.dev/v1/decode?vin=${VIN}`, {
+ headers: {
+ 'X-RapidAPI-Key': API_KEY,
+ 'X-RapidAPI-Host': 'vin.leeworks.dev',
+ },
+});
+
+const data = await res.json();
+console.log(`${data.make} ${data.model} (${data.model_year})`);
+// → HONDA Accord (2003)
+
+// Check cache status
+const cacheStatus = res.headers.get('X-Cache'); // "HIT" or "MISS"
+console.log(`Cache: ${cacheStatus}`);
+```
+
+### Batch decode (up to 50 VINs)
+
+```js
+const vins = [
+ '1HGCM82633A004352', // 2003 Honda Accord
+ '1FTFW1ET5DFA18803', // 2013 Ford F-150
+ 'WBA3A5G59DNP26082', // 2013 BMW 3 Series
+];
+
+const res = await fetch('https://vin.leeworks.dev/v1/batch', {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ 'X-RapidAPI-Key': API_KEY,
+ 'X-RapidAPI-Host': 'vin.leeworks.dev',
+ },
+ body: JSON.stringify({ vins }),
+});
+
+const { results, count, cached_count } = await res.json();
+console.log(`Decoded ${count} VINs, ${cached_count} from cache`);
+
+results.forEach(r => {
+ if (r.error) {
+ console.log(`${r.vin}: ERROR — ${r.error}`);
+ } else {
+ console.log(`${r.vin}: ${r.make} ${r.model} ${r.model_year}`);
+ }
+});
+```
+
+### Health check
+
+```js
+// No auth required on /health
+const health = await fetch('https://vin.leeworks.dev/v1/health').then(r => r.json());
+console.log(`Status: ${health.status}, Cache: ${health.cache.total_entries} entries`);
+```
+
+---
+
+## Real-World Use Cases
+
+### Automotive apps and dealership software
+
+Show instant vehicle details when a user types a VIN at checkout or trade-in. Cache the result — the same VIN is often looked up dozens of times across different users.
+
+```js
+async function enrichListing(listingVin) {
+ const vehicle = await decodeVinCached(listingVin);
+ return {
+ title: `${vehicle.model_year} ${vehicle.make} ${vehicle.model} ${vehicle.trim}`,
+ engine: `${vehicle.engine_displacement_l}L ${vehicle.engine_cylinders}-cyl ${vehicle.fuel_type_primary}`,
+ drivetrain: vehicle.drive_type,
+ body: vehicle.body_class,
+ };
+}
+```
+
+### Insurance tech and underwriting
+
+Premium calculators, claims systems, and underwriting platforms need reliable vehicle specs. A VIN decode call returns body class (sedan vs. SUV vs. pickup) and engine details in under 50ms with a cache hit — fast enough for real-time quote generation.
+
+### Fleet management platforms
+
+Decode entire fleets in a single batch call. The `/v1/batch` endpoint processes up to 50 VINs per request, making it practical to seed a database of 10,000 fleet vehicles with 200 API calls rather than 10,000 sequential hits.
+
+### Used car marketplaces
+
+User-generated listings often contain VIN typos or incorrect specs. Validate and auto-fill vehicle details server-side on listing creation:
+
+```js
+app.post('/listings', async (req, res) => {
+ const { vin, ...listing } = req.body;
+
+ // Validate + enrich
+ const vehicle = await vinApi.decode(vin);
+ if (vehicle.error_code !== '0') {
+ return res.status(422).json({ error: 'Invalid or unrecognised VIN' });
+ }
+
+ const enriched = { ...listing, vin, make: vehicle.make, model: vehicle.model, year: vehicle.model_year };
+ await db.listings.create(enriched);
+ res.status(201).json(enriched);
+});
+```
+
+---
+
+## VIN Validation
+
+Before calling any API, validate the VIN client-side to save an unnecessary round-trip:
+
+```js
+function isValidVin(vin) {
+ // 17 chars, alphanumeric excluding I, O, Q
+ if (!/^[A-HJ-NPR-Z0-9]{17}$/.test(vin)) return false;
+
+ // Optional: verify check digit (position 9)
+ const weights = [8,7,6,5,4,3,2,10,0,9,8,7,6,5,4,3,2];
+ const transliteration = { A:1,B:2,C:3,D:4,E:5,F:6,G:7,H:8,
+ J:1,K:2,L:3,M:4,N:5,P:7,R:9,S:2,T:3,U:4,V:5,W:6,X:7,Y:8,Z:9 };
+
+ const vals = vin.toUpperCase().split('').map(c =>
+ /\d/.test(c) ? parseInt(c) : transliteration[c]
+ );
+
+ const sum = vals.reduce((acc, v, i) => acc + v * weights[i], 0);
+ const check = sum % 11;
+ const expected = check === 10 ? 'X' : String(check);
+
+ return vin[8].toUpperCase() === expected;
+}
+
+console.log(isValidVin('1HGCM82633A004352')); // true
+console.log(isValidVin('1HGCM82633A00435X')); // false (bad check digit)
+```
+
+---
+
+## About the Data Source
+
+The NHTSA vPIC database is maintained by the US Department of Transportation under its statutory mandate (49 U.S.C. § 30111). Manufacturers are legally required to register VIN patterns with NHTSA, so coverage is comprehensive for vehicles sold in the US market.
+
+Key facts:
+- **Coverage**: Model years 1981–present; 1980 and earlier VINs were not standardised and are not covered
+- **Accuracy**: Authoritative for the original vehicle specification; does not reflect modifications, title brands, or recall status
+- **Update frequency**: NHTSA updates the database when new model variants are registered, typically months before vehicles reach dealerships
+- **Licence**: US federal government work, public domain under 17 U.S.C. 105 — free to use commercially with no attribution requirement
+
+---
+
+## Get Started
+
+The leeworks.dev VIN Decoder API is available on RapidAPI with a free tier (100 requests/month, no credit card required):
+
+👉 **[VIN Decoder API on RapidAPI](https://rapidapi.com/leeworks/api/vin-decoder)**
+
+Full API reference, including request/response schemas and error codes:
+
+👉 **[API Documentation](/vin-decoder)**
+
+---
+
+*Built with ❤️ by [leeworks.dev](https://docs.leeworks.dev) — production-ready data APIs powered by free public-domain data sources.*
+
+
+
diff --git a/docs-site/src/pages/index.astro b/docs-site/src/pages/index.astro
index 80b9e4c..c7c9b90 100644
--- a/docs-site/src/pages/index.astro
+++ b/docs-site/src/pages/index.astro
@@ -20,7 +20,7 @@ import Base from '../layouts/Base.astro';
Simple. Reliable. APIs.
-
Production-ready data APIs for ZIP enrichment, public holidays, and air quality. Available on RapidAPI.
+
Production-ready data APIs for ZIP enrichment, public holidays, air quality, and VIN decoding. Available on RapidAPI.
Get API Key on RapidAPI
@@ -52,6 +52,15 @@ import Base from '../layouts/Base.astro';
RapidAPI
+
+
In Development
+
VIN Decoder API
+
Decode any 17-character VIN into make, model, year, trim, engine, body class, and more. Powered by the NHTSA vPIC public-domain database.
+
+