The whole dataset, machine-readable

Base URL https://api.whichtrim.com/v1. Send your key in the x-api-key header. Keys are created in the dashboard; each has its own client ID for per-app attribution. Over-quota requests return 429 with Retry-After; a missing or revoked key returns 403.

curl "https://api.whichtrim.com/v1/vehicles?make=toyota&year=2026" -H "x-api-key: YOUR_KEY"

GET https://api.whichtrim.com/v1/compare?a=<id>[:<trim>]&b=<id>[:<trim>][&c=…][&weights=4-3-4-2-2-3-2] returns the same verdict the site shows, with the arithmetic.

Categories (weights 0–5, order for the weights parameter): price · fuel & range · safety · space & cargo · performance · tech & comfort · warranty. Or name them: weights=budget:5,safety:4.

Scoring. Relative metrics (MSRP, EPA fuel cost, mpg/MPGe, cargo, horsepower, warranty terms…) give 100 to the best contender and a proportional share to the rest (best/value for lower-is-better, value/best for higher-is-better). Absolute metrics keep their own scale: NHTSA overall stars ×20, Safety Signal as-is. A metric missing for any contender is dropped for all of them. Category score = weighted mean of its metrics; overall = weighted mean of the categories using your weights; categories with no usable metric are excluded and the weights renormalised. An open park-outside or do-not-drive advisory costs 25 safety points. Verdict strength: margin ≥ 6 = clear, ≥ 2 = edge, otherwise toss-up.

Response. overall[], verdict{winner, runner_up, margin, strength}, categories[] (each with available, weight, scores[], metrics[]{label, unit, dir, values[], scores[]}), reasons[] (category contributions to the lead), flips[] (the weight change that would reverse the verdict) and a plain-English summary. A contender given without a trim uses its base trim (lowest MSRP) wherever a press kit is on file — base compares with base — and its most efficient EPA configuration; a trim-level contender uses that trim's own MSRP, specs and equipment; a vehicle without a press kit is compared on EPA and NHTSA data only. The response says which (contenders[].trim_auto, trim_label). Add detail=1 for the side-by-side sections the site shows: detail.specs (by family, with best/worst flags where the direction is unambiguous), detail.equipment (feature matrix by system, differences flagged), detail.safety (NCAP, Safety Signal, recalls with remedy status, complaints), detail.ownership (price range, fuel cost, warranty). Add narrative=1 for the plain-English take WhichTrim publishes on that pair (narrative.summary, pick_a_if, pick_b_if, basis) — written from the default-weight verdict on the base trims and cached at build time, so it exists for the pre-computed head-to-heads and is null for other pairs. Where no manufacturer press kit exists, seating and horsepower fall back to what the manufacturer filed with NHTSA (vPIC), decoded from the VIN pattern; a press-kit value is never overridden. Engine version is returned as version (c3); the method above is versioned with it.

Vehicle ids are <year>_<make>_<model> in lowercase with spaces as underscores — 2026_ford_f_150. A "vehicle" is one nameplate in one model year as defined by the EPA base model, so gas, hybrid and plug-in versions share a record and are distinguished inside configs and, for recalls, by the variants field. Trim ids are prefixed with the vehicle id (2026_kia_sportage_sx_prestige_awd). Recall campaigns use NHTSA numbers. Dates are ISO YYYY-MM-DD.

Model level (every vehicle): EPA fueleconomy.gov configurations (mpg, MPGe, range, fuel cost), NHTSA recalls with severity and park-outside / do-not-drive flags, owner-complaint aggregates and excerpts, defect investigations, NCAP crash ratings, crash reports filed under NHTSA’s Standing General Order (Level 2 driver-assist and automated-driving systems, as filed), the WhichTrim Safety Signal grade.

Trim level (where a manufacturer press kit is on file): MSRP, ~55 specifications on one schema (engine, dimensions, cargo, weights, warranty…), ~260 canonical features with standard / optional availability per trim. Records list trims, specs, features; an empty trims array means model-level only.

Refresh. The dataset is rebuilt daily (NHTSA and EPA files re-read every build). Manufacturer newsrooms are crawled weekly for new spec sheets and pricing; a new kit is extracted, checked and published on the next build. Every response carries x-data-generated-at.

Provenance. Press-kit values are transcribed from the manufacturer's official documents and carry source_url, source_type and a confidence; nothing is hand-edited.

WhichTrim is also an MCP server, so an assistant can look a vehicle up directly instead of guessing. No key and no account — everything it returns is already on a public page, and we would rather be the thing that gets cited.

https://whichtrim.com/portal/mcp

Streamable HTTP, stateless: one JSON-RPC POST, one JSON reply. Nine tools — search_vehicles, get_vehicle, get_trims (every trim of a model year from the manufacturer's press kit: MSRP, specs and which equipment is standard where, or one trim's full spec sheet), check_recalls, decode_vin, lookup_trouble_code, lookup_bulletin (the number on a service-campaign letter or a dealer bulletin), compare_vehicles and federal_cases (the federal dockets in the RECAP index that name the manufacturer and mention a model and system, cached nightly). GET the same URL for a plain description of the server and its tools.

// Claude Desktop / any MCP client that speaks HTTP
{
  "mcpServers": {
    "whichtrim": { "url": "https://whichtrim.com/portal/mcp" }
  }
}

Every tool response carries the page URL it came from and the source line, because an answer a reader cannot trace is not worth giving. One rule is built into every recall answer and into the server's own instructions: a recall covers a build range, not a model year, so nothing here can tell somebody their particular car is clear — only NHTSA's VIN lookup settles that.

2026-10-11 (recall fix sheets) — additive. Every recall record (in recalls.json, advisories.json and each vehicle record) gains fix: null, or what the manufacturer’s dealer documents filed with NHTSA say — stop_sale, remedy_available (true, false, or null when the notice does not say), remedy_availability_quote, remedy, labor (operation code and hours from the warranty table), parts, tools, owner_instructions, sources (the two PDFs) and line, the one-line summary. Read nightly; a campaign whose documents are not yet read carries null.

2026-10-06 (bulletin depth, warranty terms) — all additive. A bulletin record gains applies_to (the build windows, engine and transmission NHTSA’s summary states, each with its own words), supersedes and superseded_by ([{number, page}]; page is null when the other filing has no page here). Each row of a vehicle record’s complaints.excerpts gains a fifth element, the NHTSA ODI number. A vehicle record whose press kit states no warranty gains warranty_fallback: the make’s consensus terms, with how many of its kits state them and agree, the model years they span and the source, labelled as the make’s terms rather than this model year’s.

2026-10-02 (what else a bulletin names) — each row of a vehicle record’s bulletins.items may carry for: the model years the filing names, one entry per model (“2016 Patriot”, “2016 Compass”, “2016 Dodge Journey”), the record’s own model first. Absent when the filing names only that model year.

2026-09-28 (one bulletin page per filing) — a number the manufacturer filed under several of its brands (GM’s Chevrolet, GMC, Buick and Cadillac; Ford and Lincoln; Stellantis; Jaguar Land Rover) is now one page listing every brand’s vehicles. /v1/bulletins/{make}/{slug} still answers for every brand, and each record gains makes (every brand it lists) and maker; page is the one page, which may sit under another brand’s address. Rows of GET /v1/bulletins stay one per brand, with that brand’s own nameplates.

2026-09-14 (usage) — GET /portal/usage gains route_errors (failed responses per endpoint), by_key_route (calls and failures per key per endpoint) and key_names. Your dashboard now shows which endpoint is failing rather than a single error total. Counting starts with this release: requests answered before it have a total but no per-endpoint breakdown, and the page says so rather than reporting zero.

2026-09-14 (trouble codes) — new endpoint /v1/dtc, and /v1/vehicles/{id} gains trouble_codes: [{code, bulletins, owner_reports, components, page}]. A WhichTrim dataset derived from the federal record, filtered so that a part number which happens to look like a code is not counted as one. defined_by is standard, manufacturer or undefined; a meaning is only ever returned for the first. Counts are mentions in the federal files, not failure rates.

2026-09-29 (complaints by system) — a vehicle record’s complaints gains by_comp: for up to eight of NHTSA’s component groups on the model year, the complaint count, how many report a crash, a fire or an injury, the count by year filed, and up to five owner accounts about that system (scrubbed as everywhere else). It is what the new problems pages (/<make>/<model>/<year>/problems/<system>/) are built from. Additive.

2026-09-29 (the build window the document states) — document_body gains build_windows: the production-date windows the manufacturer’s own PDF sets (“built on or before 04-Dec-2023”, “produced from 8/24/2022 – 12/06/2022”), each as from / to ISO dates (YYYY-MM when the document gives only a month; an open end is null), bound (before, on or before, after, on or after, between), for (the model the sentence names, or null) and quote (the document’s own words). An empty list when the document states none; a VIN-only cut-off is not a window. Documents read before today are read again over the coming nights. Additive.

2026-09-29 (the codes the document names) — document_body gains trouble_codes: the diagnostic trouble codes the manufacturer’s own PDF names, read with the same test as the summary’s codes (a code only where the text is discussing diagnostics), up to 40, in code order. An empty list when the document names none. Additive.

2026-09-29 (what the document itself lists) — a bulletin record (/v1/bulletins/{make}/{number}, /data/b/<make>/<number>.json) gains document_body once the PDF NHTSA serves for it has been read (about 2,000 documents a night): parts (number, description, qty — a number only in the manufacturer’s own catalogue shape), labor (operation, description, time, unit), supersedes, title, pdf, pages, read_at. A description the reader could not settle is null, never a guess. Absent until the document has been read. Additive.

2026-09-26 (bulletin nameplates) — every row of GET /v1/bulletins gains nameplates: the make/model slugs ("alfa-romeo/giulia") of the model-year pages the communication names. Additive.

2026-09-20 (bulletins for machines) — GET /v1/bulletins and GET /v1/bulletins/{make}/{number} (above); the MCP server gains lookup_bulletin; every bulletin page has a JSON twin at /data/b/<make>/<number>.json. Additive.

2026-09-20 (bulletin pages) — every entry in bulletins.items (the vehicle record) and every bulletin listed under a trouble code now carries url: the bulletin number’s own page, /bulletins/<make>/<number>/, when this build wrote one. Every bulletin with a usable number that a vehicle record lists has one; a communication filed with no usable number (blank, “N/A”) carries no url. Additive; nothing else changes.

2026-09-13 (owner narratives) — complaints.excerpts changes shape and content. Each entry was [date, component, text] and is now [date, component, text, miles], where miles is the odometer reading from the same filing or null. Up to six are returned instead of three, chosen one per component in order of how often that component is cited rather than by date. The text itself is now scrubbed before it is stored: whole sentences containing a VIN, phone number, email address or URL are removed, NHTSA's clerical marks are stripped, and filings written in upper case are sentence-cased. Nothing is paraphrased — the owner's words are unchanged.

2026-09-12 (emissions) — every EPA configuration in configs gains emissions: smog rating 1–10, the certified emission standard, SmartWay status, engine family id, and the EPA sales areas that say whether the configuration is a 50-state car or a California/CARB one (fifty_state, carb_only). A configuration holding both a federal and a California certificate reports a score range.

2026-09-12 (bulletins) — /v1/vehicles/{id} gains bulletins: the manufacturer communications filed with NHTSA for that model year — service bulletins, service campaigns, warranty extensions and over-the-air updates — with counts by kind and component, the most recent few document numbers, dates and summaries. The layer that describes what actually goes wrong with a car short of a recall, and one no vehicle-history report carries.

2026-09-12 (c4) — /v1/vin/{vin} returns decode.equipment: the driver-assist equipment the manufacturer filed for that configuration, normalised to standard / optional. /v1/compare scores it as its own safety metric for vehicles with no press kit — never against a press-kit feature count, since the two are itemised differently.

2026-09-12 (c3) — vehicles with no press kit now carry vinspec: engine, transmission, seating, body class and driver-assist equipment as filed with NHTSA and decoded from the VIN pattern. /v1/compare uses seating and horsepower from it when the press kit has none, so space and performance stop scoring as "no data".

2026-09-12 — /v1/vin/{vin}: decode a 17-character VIN against NHTSA vPIC and get it back joined to this dataset — the model-year record, its grade, every recall campaign, complaint aggregates and published trims. The same decoder powers the free tool at /vin/.

2026-09-13 — /v1/compare?narrative=1 returns the "our take" text shown on the site's head-to-head pages (summary, pick_a_if, pick_b_if, basis) for pre-computed pairs.

2026-09-12 (c2) — /v1/compare: a vehicle given without a trim now scores its base trim when a press kit is on file (was model-level only); detail=1 returns specs by family, the equipment matrix, safety record and ownership. Contenders carry trim_auto / trim_label.

2026-09-12 — Feature rows carry name (the manufacturer's own wording) and oem_label; press-kit equipment that matches nothing in the shared catalog is now published under its own label (feature_id prefixed x_). Free-text specs are verbatim from the press kit.

2026-09-11 — /v1/compare added (engine c1). Vehicle records gained warranty, park_outside, do_not_drive, url. API moved to api.whichtrim.com. Portal: dashboard usage counts are live per key.

2026-09-10 — Trim-level press-kit layer (trims / specs / features) on vehicle records; carry-over model years; HD nameplates.

You may use responses in your own products and cache them for up to 7 days. Attribution ("Data: WhichTrim, from EPA and NHTSA public records") is required on the Free plan and appreciated on all plans. You may not resell the raw dataset or use it to build a competing data feed without a license. Federal data are public domain; our joins, grades, transcriptions and identifiers are ours. See the terms of use.