Wheel Fitment API — Release notes & updates

The measuring rim width code now rounds to the nearest 0.5″, as ISO 4000-1 requires, instead of always rounding up. Computed values change for about half of all metric tire sizes on two endpoints. No request changes, and nothing that was accepted before is rejected now — but if you cache or compare rim width codes, design section widths, tire weights or upstep candidates, expect them to move.

1. 1. What changed and why

   The measuring rim width code (Rmc) is the rim width ISO 4000-1 assigns to a tire size: the nominal section width times a factor set by the aspect ratio, converted to inches and rounded to 0.5″. The API used to round that result up; it now rounds to the nearest 0.5″, as the standard specifies. The design section width and the estimated tire weight are derived from Rmc, so they move with it. Rmc changes for 452 of the 841 catalogue sizes /v2/upsteps/ works with, and for 49.3 % of the section width × aspect ratio pairs /v2/spec/metadata/ accepts.

   Example 155/70R12: rim width code 5.0 → 4.5, design section width 162 → 157 mm, estimated weight 6.9 → 6.8 kg.

2. 2. /v2/spec/metadata/

   • Tire mode — "tire_geometry.rim_width_code", "design_section_width_mm" and "est_weight_kg" change, and so do the hints that quote them. "overall_diameter_mm", section height and sidewall values do not change.
   • Package mode — "recommended_rim_width" changes for the same sizes, and "rim_width_match" changes for about 7 % of size × rim width inputs — 155/70R12 on a 5.5″ rim moves from within_recommended to near_recommended.

3. 3. /v2/upsteps/

   • Candidate rows on a size whose Rmc changed get a 0.5″ narrower "rim.width", and with it "rim.designation", "rim.backspacing", "rim.weight", "tire.weight" and the "difference.s_*" values. Offsets and the overall diameter differences do not change, and the OE row still echoes the requested rim.
   • Because the design section width changes, some candidates enter or leave the "s_max" tolerance. For the 235/60R18 example the default response grows from 25 to 27 rows (255/60R18 and 255/40R20 are added; 15 rows get a narrower rim). Across all 841 catalogue OE sizes with the default request, compared with the release earlier the same day: 11 responses are unchanged, 349 change only rim widths, 201 only gain rows and 280 lose at least one row.

4. 4. "rim_width" validation keeps every width accepted before

   The accepted rim width range for a tire size is the union of the old and the new range, so no request that was accepted before is rejected now — 135/80R12 (rim width code 4.0 → 3.5) still accepts a 5.0″ rim.

5. 5. Not affected

   /v2/classified/by_rim/ does not use the rim width code; its tire lists are unchanged. The wheel-size.com calculator is served by /v2/upsteps/ and shows the same values as the API.

The plus/minus sizing calculator can now step below the OE diameter as well as above it in one request, every option says which step it is on, and the response summarises the count per diameter. The old "steps" parameter keeps working but is deprecated (item 2). A few responses are ordered or bounded differently than before — item 3 lists them.

1. 1. New: "steps_min" / "steps_max", "step" and "meta.by_diameter"

   • "steps_min" (−3..0, default 0) and "steps_max" (0..3, default 2) are the lowest and highest 1-inch rim diameter steps around the OE diameter. steps_min=-1&steps_max=2 for an 18″ OE wheel returns 17–20″ in one request. The OE diameter is always included, and the two defaults are independent: steps_min=-1 alone means −1..+2.
   • Every option in "data" carries "step": the rim diameter minus the OE diameter in whole inches, 0 on the OE diameter. Half-inch diameters count by their whole part (17.5″ is step −1 from 18″).
   • "meta.by_diameter" lists every enumerated diameter in order, including those where nothing fits, keyed the way "rim.designation" spells the diameter. For an 18×7.5 ET35 rim with 235/60R18 and steps_min=-1&steps_max=2:

   "by_diameter": {
     "17":   {"step": -1, "count": 12},
     "17.5": {"step": -1, "count": 1},
     "18":   {"step": 0,  "count": 10},
     "19":   {"step": 1,  "count": 9},
     "19.5": {"step": 1,  "count": 0},
     "20":   {"step": 2,  "count": 8}
   }

   A diameter with "count": 0 is still listed, so a client can render a −1 / OE / +1 tab for every diameter without a second request. "meta.count" equals the number of options, the sum of "meta.by_rim" and the sum of the "by_diameter" counts; exactly one option has "is_oe": true, and it is on step 0.

2. 2. Deprecated: "steps"

   "steps" keeps working and is marked deprecated in both schemas. Its meaning in the new terms:

   Old	Equivalent
   steps=n (n > 0)	steps_max=n
   steps=-n	steps_min=-n&steps_max=0
   steps=0	steps_max=0

   Sending "steps" together with "steps_min" or "steps_max" returns 400 VALIDATION_ERROR with the message Use either 'steps' (deprecated) or 'steps_min'/'steps_max', not both. Note that steps_min=-1 alone means −1..+2, which is not the same as steps=-1 (−1..0).

3. 3. Changed: ordering, the OE row, tolerances, catalogue sizes and texts

   A request without step parameters returns the same options as before for most sizes. The differences:

   • Order is numeric. Rim widths of 10″ and wider used to sort before 9.5″; about one default response in four is re-ordered.
   • The OE row is always present, including for 82-series and 95-series sizes and for s_max=0 / do_max=0, which used to return an empty list.
   • Tolerances are inclusive and exact. A candidate exactly at "s_max" / "do_max" is now included, and the comparison no longer uses rounded percentages.
   • 14 more catalogue sizes are accepted as the requested size and considered as candidates: 385/95R25, 445/95R25, 325/85R16, 325/80R16, 345/75R16, 365/75R16, 385/70R16, 325/70R17, 345/70R17, 355/70R17, 345/60R17, 355/60R20, 355/50R20, 375/20R21.
   • Validation messages follow ISO 4000-1 wording. A section width that does not end in 5 is now rejected on the field itself ("shall end in 5") instead of with a generic combination error — it was a 400 before as well. The rim width error names the supported range and the tire size.
   • The method description no longer promises "secure" options or excludes sizes "unavailable in the current tire market". The calculator returns geometric candidates within the tolerances; load index, speed symbol and clearances are not checked. "meta.count" counts tire–rim combinations, not wheels.

The official Wheel-Size MCP server 0.7.1 passes "steps_min" / "steps_max", "step" and "by_diameter" through ws_calculate_upsteps — update with uvx --refresh wheel-size-mcp.

The tire branch of the classified endpoints gains the trim-level drill-down that the rim and package branches already had, and the two existing drill-downs now describe one OEM wheel pair per row. Nothing you send today changes; item 2 explains which values may differ.

1. 1. New: GET /v2/classified/by_tire/search/modifications/

   by_rim/search/ and by_package/search/ each had a generation → modifications pair; by_tire/search/ stopped at generations, so a client that had found a generation by tire size could not descend to the individual trims. The new endpoint closes that gap: take "make", "model" and "generation" (the slugs) from a by_tire/search/ row and call it with the same tire parameters.

   • Required — "make", "model", "generation", "section_width" (115–365), "aspect_ratio" (25–95), "rim_diameter" (8–26). Pagination with "offset" / "limit". There are no tolerance or sort parameters.
   • Matching is identical to by_tire/search/ — exact rim diameter, tire width and overall diameter within a fixed ±2 mm, front and rear (staggered) fitments alike. The tolerance is fixed rather than exposed so that both levels apply the same rules.
   • Rows are ordered by production start year (newest first), then trim.

   Example, Mitsubishi Outlander on 235/60R18 — GET /v2/classified/by_tire/search/modifications/?section_width=235&aspect_ratio=60&rim_diameter=18&make=mitsubishi&model=outlander&generation=a65f0f2858 returns "meta": {"count": 6, "offset": 0, "limit": 100}; first row:

   {"slug": "fcad99f8fe", "trim": "1.5T HEV", "body": null,
    "production_start_year": 2026, "production_end_year": 2026, "regions": ["cdm", "usdm"],
    "oem_rim": "7.5Jx18 ET35", "oem_tire": "235/60R18",
    "oem_rim_diameter": 18, "oem_rim_width": 7.5, "oem_rim_offset": 35,
    "oem_tire_width_mm": 235, "oem_tire_diameter_mm": 739, "oem_tire_aspect_ratio": 60,
    "ow_delta_mm": 0, "od_delta_mm": 0.2, "od_delta_percent": 0.03, "ar_delta": 0,
    "load_kg": 875, "load_index": 103}

   Fields per row: "slug", "trim", "body", "production_start_year", "production_end_year", "regions", "oem_rim", "oem_tire", "oem_rim_diameter", "oem_rim_width", "oem_rim_offset", "oem_tire_width_mm", "oem_tire_diameter_mm", "oem_tire_aspect_ratio", "ow_delta_mm", "od_delta_mm", "od_delta_percent", "ar_delta", "load_kg", "load_index". There is no "cb_diff_mm" and no frontspace / backspace fields — a tire has no centre bore or offset.

   Three things to know when reading rows:

   • The mm deltas are match precision, not a size change. Because the match window is ±2 mm, "ow_delta_mm" and "od_delta_mm" are always within ±2: they say how closely the searched tire matches the nearest OEM tire of that trim, not how far the trim's stock tire is from yours. For upsize / downsize calculations use /v2/upsteps/.
   • "oem_tire_aspect_ratio" and "ar_delta" can be null. Flotation and alpha-numeric OEM tires (37x12.50R17LT, G78-14) have no aspect ratio, yet they match on width and overall diameter like any other; both fields come back null for them while the mm deltas stay populated. 82-series tires omit the ratio from the size string but are reported as 82.
   • An empty drill-down is a normal result, not an error. The generation list and the drill-down are cached independently, so around a catalogue update a generation returned by by_tire/search/ can briefly drill down to no rows.

2. 2. Changed: one OEM wheel pair per row in by_rim/search/modifications/ and by_package/search/modifications/

   When a vehicle had several wheel pairs matching the searched rim, each column of its row was aggregated on its own, so the rim string, the offset, the OEM frontspace and "fs_delta_mm" could each come from a different pair. Searching 7Jx18 ET45, an Acura ILX 2.4i row said "oem_rim": "7.5Jx18 ET50" next to "oem_rim_offset": 45 — two rims in one row — and a Mazda CX-30 2.5 Skyactiv-G row reported the same frontspace as the searched rim, yet "fs_delta_mm": -6.35.

   Now all OEM rim / tire fields and the fitment deltas in a row describe one OEM wheel pair — the one closest to the searched rim. "fs_delta_mm" / "bs_delta_mm" are the difference from that closest fitment.

   • What may differ, and only for vehicles with more than one matching pair: "oem_rim", "oem_tire", "oem_rim_diameter" / "oem_rim_width" / "oem_rim_offset", "oem_frontspace_mm", "oem_backspace_mm", "fs_delta_mm", "bs_delta_mm".
   • What does not change: which vehicles match, "meta.count", field names and types, "load_kg" / "load_index" (still the maximum over the vehicle's matching pairs) and "cb_diff_mm" (still the smallest centre bore among them).
   • Pagination is stable: rows are ordered by production start year (newest first), then trim, then an internal id, so pages no longer repeat or skip vehicles that share a year and trim.

   No client action is required.

3. 3. Schema only

   "oem_rim", "oem_rim_width" and "oem_rim_offset" are now declared nullable in both schemas (they already could be null), and the "ordering" parameter, which never had an effect, is no longer listed on the three modification drill-downs. Values are unchanged.

The official Wheel-Size MCP server 0.7.1 offers the same drill-down as ws_find_vehicle_modifications_for_tire — update with uvx --refresh wheel-size-mcp.

Two legacy "engine.fuel" labels were renamed in the data, a new "powertrain" object separates the combustion engine from the electric side of every vehicle, and the fuel filter switches to stable codes. Read item 1 first if your code compares "engine.fuel" strings or builds menus from "meta.engine.fuels"; items 2 – 8 add new fields and accept more input without removing anything.

1. 1.Action required: "engine.fuel" labels renamed for CNG vehicles (September 15, 2026)

   Two legacy "engine.fuel" values changed in the data on September 15, 2026, on every endpoint that returns the "engine" object:

   • "Natural gas" → "CNG" (106 modifications)
   • "Petrol-Natural gas" → "Petrol-CNG" (113 modifications)

   Petrol-CNG now mirrors the long-standing Petrol-LPG. What to change:

   • If you compare, group or display on the "engine.fuel" string (if fuel == "Natural gas") — update both constants. To keep exactly the same selection, match the new strings; ?fuel=cng is not a drop-in replacement for the comparison, because it also returns petrol/CNG bi-fuel cars (item 6).
   • If you build a fuel menu or a label map from "meta.engine.fuels" — that array now lists fuel codes (cng, petrol_lpg, …) instead of the old slugs (natural-gas, petrol-lpg, …). Re-key stored selections and labels; the old slugs are still accepted by the filter, so requests keep working (item 6).
   • Moving forward — read "powertrain.primary_fuel.code" / "powertrain.secondary_fuel.code" (item 2) and treat fuel codes as identifiers and "engine.fuel" / "title" as display labels.

   Translated values ("lang=ru", "lang=de") did not change. The "fuel" request parameter is not affected: the older spellings remain accepted.

2. 2. New: "powertrain" object — the structure of "engine" is unchanged

   Every modification returned by /modifications/, /search/by_model/, /by_rim/search/modifications/, /by_tire/search/modifications/ and /by_hf_tire/search/modifications/ now carries a "powertrain" object: everything about how the vehicle is propelled that is not the engine. It sits next to "engine", not inside it. "engine" keeps exactly its five keys — "fuel", "capacity", "type", "power", "code" — with the same types and order; the only value change is the CNG relabelling in item 1. Classified endpoints and v1 do not carry the new object. No new request parameters.

   Excerpt for BMW M5 2024 (plug-in hybrid), GET /v2/modifications/?make=bmw&model=m5&year=2024:

   "engine": {
     "fuel": "Hybrid", "capacity": "4.4", "type": "V8",
     "power": {"kW": 535.0, "PS": 727, "hp": 717},
     "code": "S68B44A"
   },
   "powertrain": {
     "combustion_engine": "present",
     "electrification_level": "phev",
     "primary_fuel": {"code": "petrol", "title": "Petrol"},
     "secondary_fuel": {"code": "not_applicable", "title": "Not applicable"},
     "engine_power": {"kW": 430.0, "PS": 585, "hp": 577},
     "system_power": {"kW": 535.0, "PS": 727, "hp": 717},
     "engine_power_secondary": null,
     "motors": [
       {"axle": "front", "power": {"kW": 145.0, "PS": 197, "hp": 194}, "code": "GC1P28M0"}
     ]
   }

   The headline "power" (535 kW) equals "system_power" and is not the engine alone (430 kW) — the split this object exists to make visible. Eight keys, always present:

   • "combustion_engine" — present | not_applicable | unknown. Whether this vehicle has an internal-combustion engine, and therefore how to read a null "engine_power".
   • "electrification_level" — how the vehicle is electrified, an axis independent of fuel: mild_hybrid, full_hybrid, phev, erev, bev, fcev; or not_applicable (combustion-only), not_reported (electrified, tier not recorded yet), unknown. A mild hybrid keeps its real base fuel (e.g. Petrol) and is distinguished here instead.
   • "primary_fuel" — {code, title}. What the vehicle mainly burns or stores. code is the same vocabulary ?fuel= accepts, so a real fuel code read here can be pasted straight back into a query (the absence values not_applicable / not_reported / unknown also appear in code and are not filter values). A blend partner never appears here; it is a "secondary_fuel". title is translated with "lang".
   • "secondary_fuel" — {code, title}. A second fuel the vehicle can run on — a bi-fuel tank or a blend the engine is rated for. This is what makes the legacy composites decodable: Flex-Fuel is petrol + ethanol_blend, Petrol-LPG is petrol + lpg. not_applicable for single-fuel vehicles (the majority); not_reported when the primary fuel is not recorded either.
   • "engine_power" — combustion-engine power only, on its primary fuel, excluding any electric motor. kW / PS / hp, or null.
   • "system_power" — manufacturer-declared total output of the whole powertrain — never the sum of its parts. A distinct quantity only on full hybrids, plug-in hybrids and EVs with a motor on each axle; normally null on a single-motor EV, a mild hybrid, a range-extender and a pure combustion vehicle.
   • "engine_power_secondary" — the same combustion engine's rating on its secondary fuel (LPG, CNG, ethanol blend). Not a second engine, and never to be added to "engine_power". Typically lower on gas, often higher on an ethanol blend.
   • "motors" — electric motors, one entry per driven axle: {axle, power, code}. Empty for a vehicle with no electric drive. axle: "front" is also where an aggregated figure with no front/rear split is recorded, and where a mild hybrid's belt starter-generator goes. "power" is the peak rating, not the 30-minute continuous figure on EU registration documents.

3. 3. What null and the three absence words mean

   Absence is spelled out, not left to guesswork:

   • not_applicable — the attribute cannot apply to this vehicle (a BEV has no engine; a single-fuel car has no secondary fuel). Final under the vehicle's current classification.
   • not_reported — the attribute applies; the source has not recorded it yet. May fill later as editors work.
   • unknown — the attribute applies; the value is genuinely not known (neither electrification level nor fuel recorded). For "combustion_engine" this means no claim is made about whether an engine exists, so a null "engine_power" cannot be interpreted either way.

   Nissan Leaf 2023 (battery electric) shows the two kinds of "nothing" on one row:

   "powertrain": {
     "combustion_engine": "not_applicable", "electrification_level": "bev",
     "primary_fuel": {"code": "electric", "title": "Electric"},
     "secondary_fuel": {"code": "not_applicable", "title": "Not applicable"},
     "engine_power": null, "system_power": null, "engine_power_secondary": null,
     "motors": []
   }

   "engine_power": null is final — "combustion_engine" says there is no engine. "motors": [] on a bev means the motor data has not been entered yet — read "electrification_level" to tell the two apart. not_reported and unknown are valid states, not errors, and may change as data is recorded. Today most vehicles whose legacy "engine.fuel" is Hybrid report "primary_fuel" as not_reported, because that value never said whether the base fuel is petrol or diesel — this is being recorded gradually. "engine_power_secondary" is likewise null on almost every bi-fuel vehicle for now; null there does not mean the engine has only one rating.

4. 4. "engine_power" is the figure most other providers call "power"

   Most other vehicle-data sources publish the combustion engine's output as their power figure. Wheel-Size's "power" is the headline figure, whose source depends on the electrification level (item 5). When matching hybrids against another dataset, check that dataset's field definition first; where it reports combustion-engine output, reconcile on "engine_power". On bi-fuel vehicles it may still be the higher of the engine's two ratings rather than the primary-fuel one, until the second rating is recorded in "engine_power_secondary".

   Do not reconstruct "system_power" by adding "engine_power" to the motor figures. The battery limits how much of each can be delivered at once, so the declared total is normally lower than their sum. Toyota Grand Highlander hybrid: engine 197.5 kW + front motor 64 kW + rear motor 75.9 kW = 337.4 kW, while the declared "system_power" is 270 kW. That is how hybrid system power is rated, not a data error.

5. 5. Corrected: what "power" means, per electrification level

   The August 27 entry described "power" as the total system output. That description was too broad: it holds for full hybrids, plug-in hybrids and EVs when a system figure is recorded, but not for mild hybrids (engine figure) or range-extenders (motor figure), and a fallback applies when the preferred figure is missing. The source of "power" is now stated per electrification level, in the API documentation and here:

   • no electrification level recorded, or mild_hybrid — the combustion engine
   • full_hybrid, phev — system power; else the sum of the motors; else the engine
   • erev — the sum of the motors; else the engine
   • bev, fcev — system power; else the sum of the motors

   The website describes the same number with the same words (System / Engine / Electric). "horsepower", "horsepower_min", "horsepower_max" and meta.engine.horsepower match this same headline figure — not always the combined system total, and not always the combustion engine. About 72 vehicles will see their published "power" change gradually as editors re-save them, not on a release date; a client comparing cached values may see individual cars move.

6. 6. Fuel filter now takes codes

   "fuel" accepts the 13 fuel codes — the same values "powertrain.*_fuel.code" returns: biodiesel_blend, cng, diesel, e100, electric, ethanol_blend, flex_fuel, h2, hybrid, lpg, petrol, petrol_cng, petrol_lpg. Codes follow the EN 16942 fuel-pump labelling families, and blend codes are country-agnostic (ethanol_blend, not e85).

   • Old spellings still work as aliases: flex-fuel, natural-gas, petrol-natural-gas, petrol-lpg, hydrogen, e85, b20, … Nothing you send today stops working.
   • An unknown value returns 400 VALIDATION_ERROR (display strings such as Natural gas were never valid filter values).
   • One parameter searches everywhere: legacy "engine.fuel", "primary_fuel" and "secondary_fuel". ?fuel=ethanol_blend returns the flex-fuel cars that can burn it; ?fuel=lpg returns dedicated-LPG and petrol/LPG bi-fuel cars alike. There are no separate primary/secondary fuel parameters.
   • Result counts that moved: petrol 37,885 → 38,763; ethanol_blend 0 → 562; lpg 41 → 244; cng 106 → 219. Counts may continue to change without a release as fuel data is recorded — for example as editors assign a base fuel to legacy Hybrid vehicles.
   • meta.engine.fuels on /modifications/ now lists codes instead of the old value-slugs, and is a menu of filterable values, not a census: every value can be sent straight back as ?fuel=. A flex-fuel result set lists flex_fuel, petrol and ethanol_blend, because all three match it. A menu or label map built from this array sees different strings than before (item 1); each old string still works as a filter alias.

7. 7. Fix: natural-gas and petrol-natural-gas returned empty results

   These two filter values could never match — 219 vehicles were unreachable through a value the schema itself listed, returning empty results rather than an error. Fixed; both spellings now return the same rows as cng / petrol_cng.

8. 8. Schema: new OpenAPI 3.1 components

   /v2/openapi.json adds Powertrain, Motor, FuelRef, CombustionEngineEnum, ElectrificationLevelEnum, EnginePower, SystemPower, EngineSecondaryPower, MotorPower and ModificationsEngineMeta beside the existing Power; each power field is oneOf: [$ref, null]. /v2/swagger.json (OpenAPI 2.0) carries the same fields and descriptions, inlined at each use. Regenerate your SDK to pick the block up. Adding the block added no database work per row.

The official Wheel-Size MCP server 0.6.0 exposes the same powertrain block, fuel codes and absence vocabulary to AI assistants — update with uvx --refresh wheel-size-mcp.

Please read this one if you use "power" or the horsepower filters for hybrid or electric vehicles.

• Important: hybrid power values changed on August 21, 2026 — between mid-June and August 21, hybrid and plug-in hybrid vehicles reported only their combustion engine's output — roughly half the real figure. This was corrected in the data on August 21. If you cached hybrid power values during that window, please re-fetch them. No action is needed for pure combustion vehicles, which were never affected.
• power means the whole powertrain — the "power" field is the vehicle's headline, total system output. For a hybrid, plug-in hybrid or EREV, that is the combined figure — engine plus electric motors — not the combustion engine alone. This has always been its meaning; it is now stated explicitly in the API documentation. Note that in v2 this field appears inside the "engine" object, next to "capacity", "type" and "code". Those three describe the combustion engine. "power" does not — it describes the whole powertrain.
• The horsepower filters work the same way — "horsepower", "horsepower_min" and "horsepower_max" match against that same total. Searching horsepower_min=300 returns vehicles whose combined output exceeds 300 hp, which for a plug-in hybrid is not its engine's rating.
• OpenAPI 3.1 schema: power was typed as a string — in /v2/openapi.json, the power field was incorrectly described as a text value with no documentation, even though it returns an object with "kW", "PS" and "hp" (or null). The OpenAPI 2.0 schema at /v2/swagger.json was always correct. If you generated a client SDK from the 3.1 schema, please regenerate it.

Update, September 15, 2026: the description of "power" in the second item was too broad. The source of "power" depends on the electrification level and on which figures are recorded — see the selection and fallback rules in the September 15 entry.

• /v2/openapi.json now always returns JSON — previously this URL returned YAML unless an explicit "Accept: application/json" header was sent, breaking tools that parse by file extension or Content-Type. It now always serves JSON with the standard OpenAPI media type.
• New: /v2/openapi.yaml — the same OpenAPI 3.1 schema is now also available in YAML at its own dedicated URL.

The hf_tire mode of /spec/metadata/ now works with real-world HF tire markings (e.g. 35x12.50R17).

• section_width accepts inches in HF mode — when "overall_diameter" is provided, "section_width" is now interpreted and validated as inches (4.5 – 14, decimals allowed — e.g. "12.5"), matching the /by_hf_tire/ search endpoints. Without "overall_diameter", it remains an integer in millimeters (115 – 365) as before.
• Clearer validation — providing both "overall_diameter" and "aspect_ratio" now returns a clear error (they select conflicting modes; previously the request was silently misinterpreted). The error message for incomplete parameters now lists all four modes, including the hf_tire parameter set. Parameter ranges now match the actual data coverage: "overall_diameter" 27 – 38, "aspect_ratio" 25 – 95.

All facets on /by_tire/search/ now use keep-alternatives behaviour: "speed_symbol" and "load_index" join "region" and "fitment" — every facet's options are computed over the set matching everything except that facet's own filter.

• Menus never collapse — selecting "speed_symbol=H" no longer shrinks facets.speed_symbol.options to a single value. The full menu stays, so your UI can switch or broaden values without a second request.
• Zero-result responses are self-correcting — facets are now computed even when count == 0 and a facet filter is active. Example: 235/60R18 + "load_index=91" previously returned 0 results with empty facets; now facets.load_index.options lists the load indexes that do match — the way out of the dead end.
• Unchanged — meta.summary still describes the actual result set, and the min/max range bounds still trim the menus.
• Docs polish — array parameters on /by_tire/search/ now prefill realistic example values in Swagger UI (e.g. H / 103) instead of placeholder "string" / "0".

The High Load (HL) tire marking — the sibling of Extra Load (XL) — is now surfaced in two places, mirroring "is_extra_load_tires" exactly:

• /search/by_model/ — each wheels[] item gains a boolean is_high_load_tires, next to is_extra_load_tires. The two are mutually exclusive — a tire is XL, HL, or neither.
• /by_tire/search/ — meta.summary.features gains a high_load count, next to extra_load.

The shape ships ahead of data population — no fitment carries the HL marking yet, so the field is currently always false and the count 0. Consumers can rely on the field now.

/by_tire/search/ gains four inclusive range parameters, motivated by tire-substitution math: a tire rated N is safe on cars needing a rating ≤ N.

• "load_index_min" / "load_index_max" — integer bounds (0 – 200), combinable for a true range, e.g. ?load_index_min=95&load_index_max=100.
• "speed_symbol_min" / "speed_symbol_max" — symbol bounds ordered by rated speed, not alphabetically: H (210 km/h) outranks U (200) and T (190). Unknown symbols return 400 rather than a silent empty set.
• Bounds, not facets — they don't appear in meta.facets and are independent of the exact "load_index" / "speed_symbol" facet filters (they combine with AND if both are sent). Facet menus drill to within-range values, so they stay useful under a bound.
• NULL ratings are excluded — like the exact filters, a bound drops fitments with an unknown load index or speed rating (an unknown rating can't be proven safe).

• New facet meta.facets.fitment on /by_tire/search/ — car-grain counts {square: N, staggered: N}. Staggered = a full wheel pair whose rear tire size differs from the front on width, aspect, or rim; everything else is square.
• New filter "fitment=square|staggered" — the facet value echoes straight back as the filter, matching "speed_symbol" / "load_index" / "region". Omit for both.
• Counts can overlap — a car can carry both square and staggered trims, so the two counts may sum to more than meta.count, and the facet keeps listing both even when one is selected.

• Execute works on first click — every endpoint prefills sensible defaults sourced from live data, so example slugs can't go stale.
• Required-only red asterisks — only parameters the contract actually requires (e.g. "make", "model") are marked required. "Happy path" parameters like "year" and "region" are prefilled as suggestions and can be cleared in favour of alternatives (e.g. "generation" or "modification").
• Stability fix — Swagger UI pinned to a stable version, resolving the endless "loading" spinner some users hit on Execute.
• OpenAPI 3.1 docs now public — api.wheel-size.com/v2/openapi/ and /v2/openapi.json are accessible without an API key, same as /v2/swagger/.

Enhancements to Search-by-Rim, Search-by-Tire and Search-by-Model endpoints.

• Generation-level detail in search results for /by_rim/search/, /by_tire/search/, /by_hf_tire/search/. Responses now include a generations array inside each car result with slug, name, and year ranges scoped to matching vehicles — eliminating the need for a second API call.
• Relaxed validation on /search/by_model/: "year" and "generation" are no longer required when "modification" is supplied.

• New schema endpoint /v2/openapi.json — OpenAPI 3.1 with full JSON Schema 2020-12 alignment, standard nullable types and multiple server support. /v2/swagger.json remains unchanged.
• New Swagger UI at api.wheel-size.com/v2/openapi/ — interactive documentation powered by the 3.1 schema. Supports ?user_key= auto-authorisation.
• 100% parameter descriptions — all 259 parameters across every endpoint now carry descriptions in both schemas.

Both schemas are kept in sync by automated parity tests. SDK generators produce better output from the 3.1 spec.

Major update with improved fitment accuracy, richer response data and a new drill-down endpoint.

• New endpoint — per-vehicle drill-down: /classified/by_rim/search/modifications/. Drill from a generation into individual vehicle trims with OEM wheel specs and fitment deltas. New response fields: slug (usable directly as the "modification" parameter on other v2 endpoints), trim, body, oem_rim, oem_tire, fs_delta_mm, bs_delta_mm, cb_diff_mm, load_kg, load_index.
• 2D frontspace / backspace filtering on /classified/by_rim/search/ and /classified/by_package/search/. New parameters: "fs_poke", "bs_push", "od_tolerance", "ow_tolerance". The previous "rim_bst_from" / "rim_bst_to" pair is still supported.
• Enriched vehicle-compatibility response — min/max frontspace and backspace deltas, OEM frontspace ratios, max load capacity and centre-bore difference.
• Diameter-range widening — new parameter "diameter_range" (0 – 3) widens the rim-diameter search by ±N inches.
• Sort modes — new parameter "sort": name (default), fitment, load.
• Production-year fix — vehicles still in production now show their correct end year (no more "9999").

• Pagination support on /search/by_model/, /by_rim/search/, /by_tire/search/, /by_hf_tire/search/. New "offset" / "limit" parameters (default 50, max 100). Response meta carries offset and limit.
• Response headers on every /v2/ endpoint: X-Total-Count — total items matching the query. The diagnostic headers (X-Execution-Time-ms, X-DB-Queries, X-DB-Time-ms) are emitted in debug environments only and are not part of the public contract.
• Deterministic ordering for /makes/, /models/, /generations/, /years/, /modifications/.
• Stable error codes — VALIDATION_ERROR, NOT_FOUND, AUTHENTICATION_FAILED, THROTTLED, etc.

• operationId standardisation — all 30 endpoint operation IDs renamed to a consistent snake_case format.
• Deprecated-field annotations — deprecated parameters and response fields now marked with x-deprecated: true.
• Response headers documented in the OpenAPI schema.
• rim_offset type fix — "rim_offset", "rim_offset_min", "rim_offset_max" now correctly documented as number (previously integer).

• Reduced database queries on /modifications/, /search/by_model/, /by_rim/search/, /by_tire/search/, /by_hf_tire/search/. Optimised access patterns eliminate redundant queries.
• Wheel-ordering fix in /search/by_model/ — OE (stock) wheels are now sorted first in the wheel results.

• Fractional rim-diameter support — handles fractional rim diameters (16.5", 17.5", 19.5", 22.5") used on commercial and military vehicles.
• Relaxed section-width validation — section width now accepts values ending in 0 or 5 (e.g. 210, 240), per ISO 4000-1.
• Improved error messages — validation errors now include the list of valid / available options.

• 35+ new tire sizes from the wheel-size database — added sizes across R13 – R22, covering approximately 1,600 additional vehicles.
• Commercial-truck tire sizes — R22.5, R19.5, R17.5, R16.5. Includes 295/80R22.5, 305/70R22.5, 315/60R22.5, 315/70R22.5, 315/80R22.5, 385/55R22.5, 385/65R22.5, 265/70R19.5, 205/75R17.5, 225/75R17.5, 225/80R17.5, 215/85R16.5 and more.

New diagnostic response headers on all /v2/ endpoints:

• X-Execution-Time-ms — server processing time, milliseconds.
• X-DB-Queries — number of database queries executed.
• X-DB-Time-ms — total database query time, milliseconds.

Fixed axis-specific filtering on /by_rim/search/ and /by_rim/search/modifications/. Range parameters ("rim_diameter_min", "rim_diameter_max", "rim_width_min", "rim_width_max", "rim_offset_min", "rim_offset_max", "cb_min", "cb_max") now correctly apply to both front and rear axes.

• Fastener-diameter filter on /by_rim/search/ — new optional parameter "fd" (float, 9.525 – 18 mm) to filter by fastener / lug-bolt diameter.
• Stricter parameter validation across /by_rim/ and /by_tire/ endpoints. Parameter ranges now enforce realistic automotive values (e.g. "rim_diameter": 8 – 26; "rim_width": 2 – 14; "rim_offset": -150 to 150; "aspect_ratio": 25 – 95; "section_width": 115 – 365).
• Swagger schema improvements — response field types for tire_list, params, year_ranges and regions now display correctly.

• New parameters on /classified/by_rim/: "od_tolerance" (float, default 0.01, range 0 – 0.05) — overall tire-diameter tolerance. "ow_tolerance" (float, default 0, range 0 – 0.03) — overall tire-width tolerance.
• Regions added to /classified/by_tire/search/ — the regions field is now included in the by-tire search response.

• Backspace-adjustment parameters on /classified/by_rim/search/ and /classified/by_package/search/ — new parameters "rim_bst_from" and "rim_bst_to" (integer, default 2, range 1 – 8 mm).
• New response fields — backspace_difference_mm, backspace_difference_percent, regions.
• Improved fitment matching — vehicle matching now uses ISO tire-dimension calculations with front / rear axis separation for more accurate results.

New endpoints let you generate product cards with vehicle compatibility for rims, tires, and packages:

• /classified/by_rim/search/
• /classified/by_tire/search/
• /classified/by_package/search/

The /search/by_model/ response now returns comprehensive tire specifications:

• Extra Load flag: wheel.is_extra_load_tires indicates whether a tire carries an XL marking.
• wheel.front.tire_full, wheel.rear.tire_full: full tire designation — e.g. 215/70R16 100H XL.
• tire_sizing_system: e.g. metric.
• tire_weight_kg: estimated tire weight ±10% — e.g. 11.09.
• tire_alpha_numeric: alpha-numeric size under the older standard — e.g. A78.
• tire_width_mm, tire_diameter_mm: tire width and overall diameter in millimetres.

In /by_rim/search/ and /by_rim/search/modifications/ you can now pass rim_diameter_min and rim_diameter_max instead of the required single rim_diameter.

Two new parameters on /by_rim/search/ (see Configurator DEMO #2 for reference):

• add_configurator — if true, includes linked Configurator templates in the response.
• configurator — if true, omits vehicles without a linked Configurator template.

One new parameter on /search/by_model/:

• add_configurator — if true, includes linked Configurator templates in the response.

In /by_rim/search/ and /by_rim/search/modifications/ you can now pass rim_width_min and rim_width_max instead of the required rim_width. Useful when surfacing additional wheel fitment custom options for a vehicle.

In /makes/ and /years/ the Year filter can be applied before the Make filter. Supported scenarios for searching by vehicle:

• makes → models → years → modifications → search/by_model/ (DEMO #1)
• makes → years → model → modifications → search/by_model/ (DEMO #2)
• years → makes → model → modifications → search/by_model/ (DEMO #8)
• makes → model → generations → modifications → search/by_model/ (DEMO #3)

BenchmarkItemProduct has been extended with:

• Tire image
• Recommend flag
• Test scoring
• Year (tire manufacture date)
• Manufacturer page link
• Regions (where the tire is sold)
• Studded flag
• "For Nordic winter" flag
• Rating (TireScore and Popularity)

Case-insensitive search by trim level — e.g. EX-L, Touring, Executive.

Non-strict search by engine or trim name — e.g. 2.0 PHEV, 2.0 TDI SCR BlueMotion 4Motion. Typically used when integrating with license-plate lookups or third-party car catalogues. Narrow results further with fuel and/or horsepower filters.

Filter by fuel: diesel, electric, hybrid, petrol, other (see the full list in the spec). When a horsepower value is supplied, the search matches within ±2.7 hp (e.g. 150). Minimum and maximum horsepower bounds are also supported.

These filters let you wire Wheel Size API into systems like license-plate lookups and third-party catalogues.

Every make now includes a 240 × 180 high-resolution logo on a transparent background.

Compared to v1, API v2 covers substantially more functionality and reorganises methods for better fit with modern integrations. See Comparison of API v2 vs v1 for the breakdown.