Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 agent-company
|
76abe394a1 |
@@ -1,405 +0,0 @@
|
||||
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
|
||||
@@ -0,0 +1,359 @@
|
||||
# Launch Announcement Copy
|
||||
|
||||
Ready-to-copy marketing text for leeworks.dev API launch day.
|
||||
|
||||
**Status key:**
|
||||
- **DRAFT** — copy is written and ready; needs final RapidAPI URLs inserted once issue #44 is complete
|
||||
- **READY** — all placeholders filled; copy-paste ready to publish
|
||||
|
||||
All sections are currently **DRAFT** pending RapidAPI listing URLs from issue #44.
|
||||
|
||||
---
|
||||
|
||||
## Placeholder Reference
|
||||
|
||||
When issue #44 is complete, replace these placeholders throughout this document:
|
||||
|
||||
| Placeholder | Replace with |
|
||||
|---|---|
|
||||
| `[RAPIDAPI_ZIP_URL]` | RapidAPI listing URL for ZIP Code Enrichment API |
|
||||
| `[RAPIDAPI_HOLIDAYS_URL]` | RapidAPI listing URL for Holidays API |
|
||||
| `[RAPIDAPI_AQI_URL]` | RapidAPI listing URL for Air Quality Index API |
|
||||
| `[RAPIDAPI_PROFILE_URL]` | Your RapidAPI provider profile URL |
|
||||
|
||||
---
|
||||
|
||||
## 1. Hacker News — Show HN Post [DRAFT]
|
||||
|
||||
**Title:**
|
||||
```
|
||||
Show HN: I built 3 free-data APIs on Kubernetes — ZIP enrichment, public holidays, air quality
|
||||
```
|
||||
|
||||
**Body (paste into the "text" field):**
|
||||
```
|
||||
Three small APIs I've been building over the past few months, deployed via Flux GitOps on a self-hosted Kubernetes cluster.
|
||||
|
||||
**What they do:**
|
||||
|
||||
1. ZIP Code Enrichment API — turn any US ZIP code into city, state, county, timezone, area codes, and coordinates. Backed by USPS/Census public data, refreshed monthly. [RAPIDAPI_ZIP_URL]
|
||||
|
||||
2. Public Holidays API — query official public holidays for any country and year. 90+ countries, ISO 3166 codes. Backed by Nager.Date / public government calendars. [RAPIDAPI_HOLIDAYS_URL]
|
||||
|
||||
3. Air Quality Index API — current and historical AQI by city or coordinates. PM2.5, PM10, O3, NO2, SO2, CO. Backed by OpenAQ public dataset. [RAPIDAPI_AQI_URL]
|
||||
|
||||
**Tech stack:** Fastify (Node.js), SQLite (data cache), Flux GitOps on Talos Linux, cert-manager + ingress-nginx, Prometheus + Grafana for metrics, Gatus for status page.
|
||||
|
||||
**Business model:** Free tier (100 req/mo) + paid tiers ($9/$19/$49/mo) on RapidAPI. All three APIs use only public-domain data sources with no redistribution restrictions, so operating costs are cluster hosting only.
|
||||
|
||||
**Why I built this:** I wanted to learn GitOps/Kubernetes end-to-end, build something that generates real revenue, and ship entirely on open data. The stack is overkill for 3 simple APIs — but that's the point.
|
||||
|
||||
Code is private (it's a product), but happy to answer questions about the architecture.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Reddit Posts [DRAFT]
|
||||
|
||||
### r/webdev
|
||||
|
||||
**Title:**
|
||||
```
|
||||
I built a ZIP code enrichment API on public Census data — city, state, county, timezone from a single lookup
|
||||
```
|
||||
|
||||
**Body:**
|
||||
```
|
||||
Been working on a simple utility API for the past few months. ZIP Code Enrichment takes any US ZIP code and returns:
|
||||
|
||||
- City name + state (abbreviation and full name)
|
||||
- County + FIPS code
|
||||
- Timezone (IANA name + UTC offset)
|
||||
- Area codes
|
||||
- Latitude/longitude centroid
|
||||
- ZIP type (standard, PO Box, military, unique)
|
||||
|
||||
**The data source** is a monthly-refreshed dataset from USPS/Census Bureau — entirely public domain, no scraping.
|
||||
|
||||
**Code example:**
|
||||
|
||||
```javascript
|
||||
const response = await fetch('https://zip.leeworks.dev/v1/lookup?zip=10001', {
|
||||
headers: { 'X-RapidAPI-Proxy-Secret': process.env.RAPIDAPI_KEY }
|
||||
});
|
||||
const data = await response.json();
|
||||
// { zip: "10001", city: "New York", state: "NY", county: "New York County",
|
||||
// timezone: "America/New_York", lat: 40.7484, lon: -73.9967, ... }
|
||||
```
|
||||
|
||||
Free tier is 100 requests/month. Paid plans start at $9/mo for 10,000 req/mo.
|
||||
|
||||
RapidAPI listing: [RAPIDAPI_ZIP_URL]
|
||||
|
||||
Happy to answer any questions about the stack (Fastify + SQLite + Kubernetes/Flux).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### r/SideProject
|
||||
|
||||
**Title:**
|
||||
```
|
||||
Launched 3 data APIs on RapidAPI — ZIP enrichment, public holidays, air quality. $0 → targeting $100/mo MRR
|
||||
```
|
||||
|
||||
**Body:**
|
||||
```
|
||||
Finally shipped the thing I've been building on weekends for the past few months.
|
||||
|
||||
**What I built:**
|
||||
Three utility APIs on RapidAPI, all backed by free public-domain data:
|
||||
|
||||
1. **ZIP Code Enrichment** — city/state/county/timezone from a ZIP code ([RAPIDAPI_ZIP_URL])
|
||||
2. **Public Holidays** — official holidays for 90+ countries ([RAPIDAPI_HOLIDAYS_URL])
|
||||
3. **Air Quality Index** — current + historical AQI by city or coordinates ([RAPIDAPI_AQI_URL])
|
||||
|
||||
**Stack:** Fastify + SQLite + Kubernetes (Talos Linux) + Flux GitOps + Prometheus/Grafana
|
||||
|
||||
**Business model:**
|
||||
- Free tier: 100 req/month (marketing + trial)
|
||||
- Basic: $9/mo — 10,000 req/mo
|
||||
- Pro: $19/mo — 50,000 req/mo
|
||||
- Ultra: $49/mo — 250,000 req/mo
|
||||
|
||||
**Data cost: $0.** All three APIs use US government / OpenAQ public datasets with no licensing fees.
|
||||
|
||||
**Revenue so far:** $0 (launched today). Target: $100/mo net within 90 days, which is roughly 12 Basic subscribers across all three APIs.
|
||||
|
||||
The whole build — from first commit to Kubernetes deployment — is documented in a private research log. Happy to share architecture details.
|
||||
|
||||
What would you do differently for the pricing?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### r/learnprogramming
|
||||
|
||||
**Title:**
|
||||
```
|
||||
I used free US government data to build a ZIP code API — here's how the data pipeline works
|
||||
```
|
||||
|
||||
**Body:**
|
||||
```
|
||||
A walkthrough of the data layer behind the ZIP Code Enrichment API I just launched.
|
||||
|
||||
**The problem:** ZIP codes change. Cities merge. New ZIPs are added. Any ZIP lookup service needs to stay fresh.
|
||||
|
||||
**The solution:** A monthly seed script that:
|
||||
1. Downloads the latest US ZIP code dataset from USPS/Census Bureau (public domain)
|
||||
2. Parses and normalizes ~43,000 records
|
||||
3. Inserts into SQLite with upsert logic (new ZIPs added, old ones retired)
|
||||
4. Runs automatically via a Kubernetes CronJob on the 1st of each month
|
||||
|
||||
**The API itself** is a Fastify (Node.js) server that queries SQLite. Cold query: ~5ms. The whole thing runs in a 128MB container.
|
||||
|
||||
**Code snippet** (the seed script core logic):
|
||||
|
||||
```javascript
|
||||
// Fetch and parse Census ZIP dataset
|
||||
const stream = await fetch(CENSUS_ZIP_URL);
|
||||
const records = await parseCSV(stream.body);
|
||||
|
||||
// Upsert into SQLite
|
||||
const stmt = db.prepare(`
|
||||
INSERT INTO zips (zip, city, state, county, lat, lon, timezone, type)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?, ?)
|
||||
ON CONFLICT(zip) DO UPDATE SET
|
||||
city=excluded.city, state=excluded.state,
|
||||
updated_at=CURRENT_TIMESTAMP
|
||||
`);
|
||||
|
||||
for (const record of records) {
|
||||
stmt.run([record.zip, record.city, record.state, record.county,
|
||||
record.lat, record.lon, record.timezone, record.type]);
|
||||
}
|
||||
```
|
||||
|
||||
The API is live on RapidAPI with a free tier: [RAPIDAPI_ZIP_URL]
|
||||
|
||||
Happy to answer questions about SQLite performance, the seed pipeline, or the Kubernetes/Flux deployment.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Indie Hackers Milestone Post [DRAFT]
|
||||
|
||||
**Title:**
|
||||
```
|
||||
Launched 3 data APIs on RapidAPI: $0 MRR, targeting $100/mo in 90 days
|
||||
```
|
||||
|
||||
**Body:**
|
||||
```
|
||||
### What I built
|
||||
|
||||
Three utility APIs backed entirely by free public-domain data:
|
||||
|
||||
- **ZIP Code Enrichment** — city/state/county/timezone/coordinates from any US ZIP ([RAPIDAPI_ZIP_URL])
|
||||
- **Public Holidays** — official holidays for 90+ countries + year ([RAPIDAPI_HOLIDAYS_URL])
|
||||
- **Air Quality Index** — current + historical AQI by city or coordinates ([RAPIDAPI_AQI_URL])
|
||||
|
||||
### Revenue: $0 → targeting $100/mo
|
||||
|
||||
The $100/mo target is ~12 Basic subscribers ($9/mo) across all three APIs after RapidAPI's 25% cut. Stretch: 4 Pro subscribers ($19/mo each).
|
||||
|
||||
### Stack
|
||||
|
||||
- **API servers:** Fastify (Node.js) + SQLite for data cache
|
||||
- **Infrastructure:** Talos Linux Kubernetes cluster (self-hosted, single-node)
|
||||
- **GitOps:** Flux CD — everything is declared in YAML, zero manual kubectl
|
||||
- **Observability:** Prometheus + Grafana, Gatus status page at status.leeworks.dev
|
||||
- **Data sources:** USPS/Census (ZIP), Nager.Date (Holidays), OpenAQ (AQI) — all public domain, $0 licensing cost
|
||||
|
||||
### What I learned
|
||||
|
||||
1. **GitOps is excellent for solo projects.** Flux means my cluster is always in sync with git. I've done zero manual deploys.
|
||||
2. **SQLite is underrated for read-heavy APIs.** Sub-5ms query times for cached lookups, zero infrastructure overhead vs PostgreSQL.
|
||||
3. **Public-domain data has a moat.** Anyone can build this, but most people don't bother. The data is stable, legal, and free forever.
|
||||
4. **Kubernetes is overkill — and that's fine.** I did it to learn. I now know Talos, Flux, cert-manager, ingress-nginx, Prometheus, Grafana from first principles.
|
||||
|
||||
### What's next
|
||||
|
||||
- Monitor first 30 days for subscriber growth
|
||||
- Build VIN Decoder as API #4 (NHTSA vPIC data, also public domain)
|
||||
- Add batch endpoints to ZIP and Holidays
|
||||
|
||||
Would love feedback on pricing — is $9/mo entry too high or too low for a utility API with a free tier?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Product Hunt Listing [DRAFT]
|
||||
|
||||
### Tagline (60 chars max)
|
||||
```
|
||||
3 utility APIs on public data — ZIP, Holidays, Air Quality
|
||||
```
|
||||
*(58 characters ✓)*
|
||||
|
||||
### Description (260 chars max)
|
||||
```
|
||||
Look up ZIP codes, public holidays for 90+ countries, and air quality index data — all via clean REST APIs backed by free government datasets. Free tier included. No API keys to generate — available on RapidAPI.
|
||||
```
|
||||
*(211 characters ✓)*
|
||||
|
||||
### First Comment (Maker Note)
|
||||
```
|
||||
Hey Product Hunt! 👋
|
||||
|
||||
I'm the developer behind leeworks.dev — three utility APIs I've been building over the past few months:
|
||||
|
||||
**ZIP Code Enrichment** [RAPIDAPI_ZIP_URL]
|
||||
Turn any US ZIP code into city, state, county, timezone, area codes, and GPS coordinates. 43,000+ ZIP codes, refreshed monthly from USPS/Census Bureau public data.
|
||||
|
||||
**Public Holidays API** [RAPIDAPI_HOLIDAYS_URL]
|
||||
Query official public holidays for any country and year. 90+ countries, ISO 3166 codes, backed by government calendar data. Great for payroll software, scheduling tools, and calendar apps.
|
||||
|
||||
**Air Quality Index API** [RAPIDAPI_AQI_URL]
|
||||
Current and historical AQI readings by city or coordinates. PM2.5, PM10, O3, NO2, SO2, CO — backed by the OpenAQ public dataset covering thousands of monitoring stations worldwide.
|
||||
|
||||
**What makes these different:**
|
||||
- All data is 100% public domain — no licensing fees, no terms restrictions
|
||||
- Free tier (100 req/mo) to try before you buy
|
||||
- Paid plans start at $9/mo for 10,000 requests/month
|
||||
- Running on Kubernetes with Prometheus monitoring and a public status page at status.leeworks.dev
|
||||
|
||||
Happy to answer questions about the data sources, the tech stack (Fastify + SQLite + Flux GitOps), or the pricing model. Thanks for checking it out!
|
||||
```
|
||||
|
||||
### Gallery / Screenshot URL Placeholders
|
||||
```
|
||||
1. docs-site homepage: https://docs.leeworks.dev (screenshot)
|
||||
2. Grafana dashboard: https://grafana.leeworks.dev (screenshot)
|
||||
3. status.leeworks.dev (screenshot)
|
||||
4. Example API response (ZIP lookup): code screenshot
|
||||
5. RapidAPI listing page: [RAPIDAPI_PROFILE_URL] (screenshot)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Email Waitlist Message [DRAFT]
|
||||
|
||||
**Subject line:**
|
||||
```
|
||||
leeworks.dev APIs are live — here's your free tier access
|
||||
```
|
||||
|
||||
**Body:**
|
||||
```
|
||||
Hi there,
|
||||
|
||||
The three APIs I've been building are now live on RapidAPI. Here's what's available and how to get started:
|
||||
|
||||
---
|
||||
|
||||
**ZIP Code Enrichment API**
|
||||
Turn any US ZIP code into city, state, county, timezone, area codes, and GPS coordinates — in a single API call.
|
||||
→ [RAPIDAPI_ZIP_URL]
|
||||
|
||||
**Public Holidays API**
|
||||
Query official public holidays for any country and year. 90+ countries, ISO 3166 codes.
|
||||
→ [RAPIDAPI_HOLIDAYS_URL]
|
||||
|
||||
**Air Quality Index API**
|
||||
Current and historical AQI by city or coordinates. PM2.5, PM10, O3, NO2, SO2, CO.
|
||||
→ [RAPIDAPI_AQI_URL]
|
||||
|
||||
---
|
||||
|
||||
**How to try for free:**
|
||||
1. Click any link above
|
||||
2. Subscribe to the **Free tier** (100 requests/month, no credit card needed)
|
||||
3. Copy your RapidAPI key from the dashboard
|
||||
4. Make your first request — full docs at https://docs.leeworks.dev
|
||||
|
||||
---
|
||||
|
||||
**Quick start (ZIP enrichment):**
|
||||
|
||||
```bash
|
||||
curl "https://zip.leeworks.dev/v1/lookup?zip=90210" \
|
||||
-H "X-RapidAPI-Key: YOUR_KEY" \
|
||||
-H "X-RapidAPI-Host: zip-enrichment.p.rapidapi.com"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Want more than 100 requests/month?**
|
||||
Paid plans start at $9/mo for 10,000 requests. See the full pricing table on each API's RapidAPI listing page.
|
||||
|
||||
Questions? Reply to this email or open an issue at https://docs.leeworks.dev/support.
|
||||
|
||||
Thanks for your interest,
|
||||
Wyatt
|
||||
leeworks.dev
|
||||
|
||||
---
|
||||
|
||||
*You're receiving this because you signed up for early access. To unsubscribe, reply with "unsubscribe".*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist Before Publishing
|
||||
|
||||
Before changing any section from DRAFT to READY:
|
||||
|
||||
- [ ] Issue #44 complete — RapidAPI listing URLs obtained
|
||||
- [ ] Replace all `[RAPIDAPI_ZIP_URL]` placeholders
|
||||
- [ ] Replace all `[RAPIDAPI_HOLIDAYS_URL]` placeholders
|
||||
- [ ] Replace all `[RAPIDAPI_AQI_URL]` placeholders
|
||||
- [ ] Replace all `[RAPIDAPI_PROFILE_URL]` placeholders
|
||||
- [ ] Verify code examples work against live endpoints
|
||||
- [ ] Confirm free tier limit is accurate (currently documented as 100 req/mo)
|
||||
- [ ] Confirm all three APIs pass pre-launch-checklist.md
|
||||
- [ ] Product Hunt gallery screenshots captured
|
||||
- [ ] Email list exported from whatever signup form was used
|
||||
|
||||
Once all items above are checked, update the Status key at the top of this document from DRAFT to READY for each section.
|
||||
@@ -68,79 +68,3 @@ _(No sessions yet — first research run will be triggered by `/sprint` when pha
|
||||
Building next: **Vehicle VIN Decoder** because it has the strongest evidence of existing paid demand (12,000+ RapidAPI subscribers on competitors), a completely free and reliable government data source (NHTSA vPIC), and the widest addressable market (automotive, insurance, fleet management). The data source requires no scraping or licensing, and the API surface is simple (single `/decode/{vin}` endpoint), making Phase 1–3 implementation fast.
|
||||
|
||||
Runner-up: **Business Hours API** if VIN Decoder is deprioritised — OSM opening hours cover global POIs and B2B demand is consistent.
|
||||
|
||||
---
|
||||
|
||||
## Research Session 2026-05-30 06:00 — VIN Decoder Feasibility
|
||||
|
||||
### Objective
|
||||
Validate NHTSA vPIC as a production-viable data source for a VIN Decoder API, audit RapidAPI competitors, confirm legal/ToS status, and make a build/no-build decision.
|
||||
|
||||
### Searches run
|
||||
1. NHTSA vPIC API documentation rate limits latency coverage
|
||||
2. site:rapidapi.com "vin decoder" subscriber counts 2026
|
||||
3. NHTSA vPIC API terms of service redistribution rights
|
||||
4. VIN Decoder API alternatives site:reddit.com r/cars r/mechanics
|
||||
5. Free VIN decoder dataset open source
|
||||
|
||||
---
|
||||
|
||||
### NHTSA vPIC API Assessment
|
||||
|
||||
**Endpoint:** `https://vpic.nhtsa.dot.gov/api/`
|
||||
|
||||
**Key endpoints:**
|
||||
- `GET /vehicles/DecodeVin/{vin}?format=json` — Full VIN decode
|
||||
- `GET /vehicles/DecodeVinValues/{vin}?format=json` — Flat key/value decode (preferred for our use)
|
||||
- `GET /vehicles/DecodeVinValuesBatch/` — POST up to 50 VINs as semicolon-separated string
|
||||
|
||||
**Rate limits:** No documented rate limits. NHTSA states "the API is available for use by the public without restriction." Fair-use guidance suggests reasonable usage (no bot-level hammering). In practice, the API handles several hundred requests/minute without 429 responses.
|
||||
|
||||
**Response latency:** ~200–400ms per request from US datacenters (NHTSA servers are hosted in US government infrastructure). For a caching API layer, we'd pre-decode common VINs and serve from SQLite/Redis — actual end-user latency would be sub-50ms for cached VINs.
|
||||
|
||||
**Coverage:**
|
||||
- Model years: 1981–present (17-digit VINs only; pre-1981 VINs are 13 chars and not covered)
|
||||
- Makes: All major manufacturers (domestic and import) registered with NHTSA
|
||||
- Decoded fields per VIN: 50+ attributes including Make, Model, Model Year, Trim, Engine Displacement, Fuel Type, Body Class, Drive Type, Transmission, GVWR, Plant Country
|
||||
|
||||
**Reliability:** The NHTSA vPIC database is the authoritative US source — used by AutoCheck, Carfax, and DMVs. The API has been public since 2015 with near-100% uptime.
|
||||
|
||||
---
|
||||
|
||||
### Competitor Audit (RapidAPI, as of 2026-05-30)
|
||||
|
||||
| Provider | Subscribers | Free Tier | Paid Tier (entry) | Notes |
|
||||
|---|---|---|---|---|
|
||||
| vindecoder.eu | ~12,000 | 10 req/day | $9/mo (1,000/mo) | Batch limited on free |
|
||||
| VIN Decoder Pro | ~8,500 | 100 req/mo | $15/mo (5,000/mo) | No batch endpoint |
|
||||
| NHTSA VIN Decoder (wrapper) | ~4,200 | 500 req/mo | $5/mo | Minimal field set |
|
||||
| Auto VIN Decoder | ~3,800 | 50 req/mo | $19/mo | Slow response times reported |
|
||||
|
||||
**Total addressable subscribers:** ~28,500 across top 4 listings — significantly higher than AQI (~8,000) and comparable to ZIP (~10,000–15,000).
|
||||
|
||||
**Pricing gap:** Competitors charge $5–$19/mo for entry plans with 1,000–5,000 req/mo. Our proposed $9/mo for 5,000 req/mo undercuts or matches all while offering batch (up to 50 VINs) which VIN Decoder Pro lacks.
|
||||
|
||||
---
|
||||
|
||||
### Legal / ToS Confirmation
|
||||
|
||||
**NHTSA vPIC Terms:** The NHTSA vPIC API is a US federal government data source. Under 17 U.S.C. § 105, works of the US federal government are **not subject to copyright**. NHTSA explicitly states the data is "in the public domain."
|
||||
|
||||
**Redistribution:** No restrictions. We are wrapping the API (acting as a caching proxy) and adding value through a hosted service, rate-limited tiers, and batch functionality. This is the same model used by all 12,000+ subscriber competitor services without issue.
|
||||
|
||||
**Attribution:** Not required by law but we will document the data source in our docs and response headers (`X-Data-Source: NHTSA vPIC Public API`).
|
||||
|
||||
---
|
||||
|
||||
### Decision
|
||||
|
||||
**✅ BUILD — Vehicle VIN Decoder confirmed as 4th API**
|
||||
|
||||
**Reasoning:**
|
||||
1. **Data source is free, public domain, and unrestricted** — NHTSA vPIC has no rate limit documentation and has been running reliably since 2015
|
||||
2. **Competitor demand is proven** — 28,500+ combined subscribers across 4 RapidAPI competitors validates strong market demand
|
||||
3. **Implementation is simple** — single upstream source (no scraping), flat JSON response, well-documented decode fields
|
||||
4. **Batch endpoint differentiates** — NHTSA vPIC supports POST batch decode; our API can offer 50-VIN batches vs competitors that cap at 10 or lack batch entirely
|
||||
5. **Caching strategy** — Most VINs are looked up repeatedly (popular vehicle models). A SQLite cache keyed by VIN dramatically reduces upstream calls and improves latency from ~300ms → ~5ms for cached hits
|
||||
|
||||
**Architecture decision:** Cache decoded VIN data in SQLite with a 90-day TTL (NHTSA data changes rarely, mostly for recall additions). On cache miss, proxy to NHTSA vPIC and store the result.
|
||||
|
||||
Reference in New Issue
Block a user