Wheel Fitment API — Release notes & updates

A running log of new endpoints, parameter changes, and behaviour tweaks. Newest entries are shown first. For the authoritative reference of every field see the OpenAPI specification.

Wheel Fitment API

  1. Search by Tire — facet menus never dead-end

    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".

  2. High Load (HL) tire flag

    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.

  3. Search by Tire — load-index & speed-rating range bounds

    /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).

  4. Search by Tire — square / staggered fitment facet

    • 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.

  5. Interactive docs — Swagger UI "Try it out" overhaul

    • 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/.

  6. Search API — Generation-level results & relaxed validation

    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.

  7. OpenAPI 3.1 schema now available

    • 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.

  8. Classified API — enhanced vehicle-compatibility search

    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").

  9. Search API — pagination, response headers, deterministic ordering

    • 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.

  10. OpenAPI schema updates

    • 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).

  11. Performance improvements across v1 and v2

    • 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.

  12. Upstep calculator — fractional rim support & validation

    • 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.

  13. Upstep calculator — expanded tire coverage

    • 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.

  14. Diagnostic response headers added

    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.

  15. Bug fix — Search-by-Rim axis filtering

    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.

  16. Search endpoint hardening — validation & new filters

    • 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.

  17. Classified — configurable tire-dimension tolerances

    • 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.

  18. Classified API — backspace filtering & regions

    • 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.

  19. Classified API methods added

    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/

  20. Search by model — richer tire information

    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.

  21. Search by rim — diameter range support

    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.

  22. Wheel Configurator API integration hooks

    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.

  23. Search by rim — width range support

    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.

  24. Vehicle search — Year-first filter supported

    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)

  25. Tiresvote.com API — enriched /top-charts/{slug}/

    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)

  26. Trim level filter on /modifications/

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

  27. Engine / trim-name filter on /modifications/

    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.

  28. Fuel-type and horsepower filters on /modifications/

    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.

  29. Make logos on /makes/

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

  30. Wheel Fitment API v2 released

    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.

Wheel Configurator API

  1. Wheel Configurator API released

    Visualise rims on specific vehicles via our image-composition pipeline. See the OpenAPI spec for the Configurator and the Configurator FAQ for integration guidance.