TrimScout
Whole-market vehicle search and dealership reverse-auction bidding. Next.js + Tailwind, deployed on Vercel.
npm install
npm run dev
Open http://localhost:3000.
Paste-a-VIN similar lots (Ford window sticker)
This lives inside Launch Dealership Bidding Hunt (components/BiddingWizard.tsx) — not a separate page.
How to run it
- Click Bid Out a Deal / Launch Dealership Bidding Hunt.
- Step 1 payment defaults to Cash.
- Step 2: paste a VIN or dealer URL in the existing paste field. Some dealer URLs (e.g. Dealer.com hash paths) have no VIN in the URL. TrimScout fetches that page once and reads JSON-LD / labeled VIN fields. It will not treat AWS instance ids or hashes as VINs. If the dealer site blocks the fetch, paste the 17-character VIN — we will not decode a mock Explorer/Porsche.
- Enter your ZIP and search radius in miles next to that box (placeholders like
07405 / 100 are examples only — fields stay empty until you type). Those values are required before suggestions run. They are never hardcoded and never silently defaulted to 100.
- TrimScout fetches the official Ford Direct PDF (server-side, no account):
https://www.windowsticker.forddirect.com/windowsticker.pdf?vin={VIN}
- Factory options come from that sticker as checkboxes (not mock package lists). Every box starts unchecked — Ultimate Package and keypad are examples of filters, not defaults. Exterior (and interior, if parsed) color is listed. Standard
KEYLESS ENTRY W/PUSH START is never a filter even if the user ticks other lines. Toggling must-haves re-runs the hunt when ZIP + radius are set. Empty ticks = same model in radius, no option filter.
- After paste and zip+radius, the Increase Competition slots are the nearest sticker-confirmed similar lot within your radius of your ZIP, then the nearest lot from a different rooftop when one also sticker-matches. Two units at the same store never fill both slots — if every remaining match is that rooftop, slot 2 stays empty. Lots must have every ticked must-have on their Ford sticker (including color if ticked). No extra “Fill both slots” click. Each card shows dealer, VIN, and miles-from-your-ZIP even when the lot has no dealer URL. Distance from your ZIP ranks lots — not price or optional overlap. Lots outside the radius or missing a must-have are dropped — we do not pad. If ZIP/radius are missing, the hunt is in flight, nothing is in range, demo inventory is Explorer-only (e.g. a Bronco Sport), or the search errors, that block shows one clear reason instead of empty paste boxes. Demo Explorer lots are not applied to a Bronco Sport (or any other model).
Worked example must-haves: Ultimate Package and Keyless Entry Keypad. Distance is from the user ZIP, not the subject dealer ZIP.
| VIN | Result |
|---|
1FMWK8JC7TGB81309 Jim Shorkey Ford, White Oak PA | Keep only if your radius covers ~300 mi from your ZIP (e.g. 07405 + 400+). At 07405 + 100 mi → drop outside_radius. |
1FMWK8JC1TGB69561 Battlefield Ford, Culpeper VA | Keep only if your radius covers ~250 mi. At 07405 + 100 mi → drop outside_radius. |
1FMWK8JC7TGA20216 Mall of Georgia Ford | Drop (Ultimate, no keypad) |
1FMUK8JH8TGB25138 All American Ford Old Bridge | Drop (2.3L VIN prefix 1FMU) |
3FMCR9BN8TRE94740 Route 23 Bronco Sport Big Bend | Subject vehicle (not Explorer). Demo Tremor lots are not suggestions. |
Ford rules baked in
- VIN prefix
1FMWK = 3.0L EcoBoost V6. Prefix 1FMU = 2.3L. A 2.3 is not a match for a 3.0 Ultimate hunt.
KEYLESS ENTRY W/PUSH START is standard. It is never a must-have filter. User “keyless entry” means the $455 door-pillar Keyless Entry Keypad.- Must-have = hard filter on sticker text. Nice-to-have = overlap score, then lower price, then closer.
- Placeholder PDFs (“The window sticker has not yet been released”) are
unreleased. Dealer ad copy is never proof.
- Every price/option is labeled
sticker, listing, or unconfirmed. For any Ford VIN: a pasted VDP’s advertised selling price (JSON-LD offers.price / Sale / Internet / Our price) is the listing number; Ford Direct TOTAL MSRP is the MSRP line. VIN-only or a blocked scrape → sticker MSRP, listing omitted/unconfirmed. Increase Competition lots use listings-API price, else that lot’s VDP sale price, else that VIN’s sticker MSRP. Never invent a number and never print call dealer.
What works without listings API keys
Ford sticker fetch + parse always work. Demo Increase Competition for Explorer Tremor uses bundled sticker fixtures (no listings key, no live PDF round-trip for those example lots). Nationwide live inventory search for other models needs a key.
npm test
Env vars (do not commit secrets)
| Variable | Required? | Role |
|---|
MARKETCHECK_API_KEY | No | Preferred coarse listings (GET https://api.marketcheck.com/v2/search/car/active). Free developer tier: 500 calls/month, 5 req/sec, 100-mile radius cap. Do not clamp a wider hunt — if MarketCheck rejects the radius, the API note includes their HTTP status and message. |
AUTO_DEV_API_KEY | No | Fallback coarse listings (GET https://api.auto.dev/listings) when no MarketCheck key is set. Free plan: listings + VIN decode, no OEM Build. |
LISTINGS_PROVIDER | No | Optional override: marketcheck or auto.dev (also autodev / auto_dev). Ignored if that provider’s key is missing. |
If only one listings key is set, that provider is used. If both are set, MarketCheck wins unless LISTINGS_PROVIDER selects Auto.dev. If neither is set, Increase Competition stays on today’s no-key demo (Explorer Tremor fixtures only).
Listings APIs filter year/make/model/zip/radius. They cannot filter Ultimate / BlueCruise / keypad, and this hunt does not send a trim filter — option matching is the Ford window sticker. After one coarse query we sticker-pass only the first 25–50 candidate VINs.
Do not cache MarketCheck listing responses (Redis, KV, disk, or DB). Their developer ToS allows only transient in-memory data for the duration of one end-user request. Ford Direct window-sticker PDF caching is unchanged — those are Ford’s files, not MarketCheck’s.
What this is not
- Not a Visor.vin clone, VIN warehouse, or daily scrape of Ford rooftops.
- Not ChromeData / VinAudit / GoodCar as Ford source of truth.
- Not hooked to the existing BMW/Porsche scrapers, Excel, or SQLite inventory.
- Do not bulk-crawl Ford Direct. Lookups are user-initiated (subject VIN + up to 50 hunt candidates).
Trade-ins
Buyers can attach a trade-in (six required photos) to a quote request and dealers appraise it in-app. See docs/TRADE_IN.md for the fields, the photo rules and how equity flows into cash, finance and lease.
